MapArgs (LSST CCS - Toolkit (Pom) 3.1.3 API)

java.lang.Object
- org.lsst.gruth.jutils.MapArgs

All Implemented Interfaces:

Serializable, Cloneable, Iterable<Object>, Map<String,Object>
```
public class MapArgs
extends Object
implements Map<String,Object>, Iterable<Object>, Serializable, Cloneable
```
An hybrid object: it is an immutable Map but has some behaviour of an immutable List. It could be used to specify arguments to a constructor or method call. These arguments could be named (then use static method argMap) or not (then use static method argList).
The order of arguments might be important because the values (of the map, or of the list) will be passed "as such" to the constructor or method invocations if there is no use of ConstructorProperties to annotate the corresponding constructor
The objects that are part of this Map/list can be "hollow" (see HollowParm). so to get a full Map/list where all objects have been set test isSafe then asFullMap (or asFullArray, or asFullList) to get data that can be used as a set of parameters for constructors or methods.

Author:

bamade

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class MapArgs.LEntry
Map.Entry implementation.
- Nested classes/interfaces inherited from interface java.util.Map
  Map.Entry<K,V>

Nested Classes
Modifier and Type	Class and Description
`static class`	`MapArgs.LEntry` `Map.Entry` implementation.

Field Summary

Fields
Modifier and Type Field and Description

static MapArgs EMPTY_MAPARGS

Fields
Modifier and Type	Field and Description
`static MapArgs`	`EMPTY_MAPARGS`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static MapArgs.LEntry`	`a(String key, Object value)` declares a parameter that is not open for modification.
`static MapArgs.LEntry`	`aBool(String key)` declares a modifiable parameter of type boolean and initializes it to `false`
`static MapArgs.LEntry`	`aBool(String key, Boolean value)`
`static MapArgs.LEntry`	`aBool(String key, Boolean value, Map<?,?> map)`
`static MapArgs.LEntry`	`aBool(String key, String strVal)`
`static MapArgs.LEntry`	`aBool(String key, String strVal, Map<?,?> map)`
`static MapArgs.LEntry`	`aDbl(String key)` declares a modifiable parameter of type `Double` or `BigDecimal` and does not initialize it.
`static MapArgs.LEntry`	`aDbl(String key, BigDecimal value)` declares a modifiable parameter of type `BigDecimal` and sets the initial value.
`static MapArgs.LEntry`	`aDbl(String key, BigDecimal value, Map<?,?> map)`
`static MapArgs.LEntry`	`aDbl(String key, Double value)` declares a modifiable parameter of type `Double` and sets the initial value.
`static MapArgs.LEntry`	`aDbl(String key, Double value, Map<?,?> map)`
`static MapArgs.LEntry`	`aDbl(String key, String strVal)` declares a modifiable parameter of type `BigDecimal` and sets the initial value with a (numeric) `String`
`static MapArgs.LEntry`	`aDbl(String key, String strVal, Map<?,?> map)`
`static MapArgs.LEntry`	`aList(String key, double[] arrayDouble)`
`static MapArgs.LEntry`	`aList(String key, float[] arrayFloat)`
`static MapArgs.LEntry`	`aList(String key, List list)` declares a modifiable parameter which is a list of simple values (do not use for references)
`static MapArgs.LEntry`	`aList(String key, List list, Map<?,?> map)`
`static MapArgs.LEntry`	`aMap(String key, Map map)` declares a modifiable parameter which is a Map where values are of a simple type (do not use for references)
`static MapArgs.LEntry`	`aMap(String key, Map map, Map props)`
`static MapArgs.LEntry`	`anArray(String key, boolean[] array)`
`static MapArgs.LEntry`	`anArray(String key, boolean[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, byte[] array)`
`static MapArgs.LEntry`	`anArray(String key, byte[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, char[] array)`
`static MapArgs.LEntry`	`anArray(String key, char[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, double[] array)`
`static MapArgs.LEntry`	`anArray(String key, double[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, float[] array)`
`static MapArgs.LEntry`	`anArray(String key, float[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, int[] array)` declares a modifiable parameter of an array type.
`static MapArgs.LEntry`	`anArray(String key, int[] array, Map map)`
`static MapArgs.LEntry`	`anArray(String key, Object[] array)`
`static MapArgs.LEntry`	`anArray(String key, Object[] array, Map map)`
`static MapArgs.LEntry`	`anInt(String key)` declares a modifiable parameter of type `Integer` and does not initialize it.
`static MapArgs.LEntry`	`anInt(String key, Integer value)` declares a modifiable parameter of type `Integer` and sets the initial value.
`static MapArgs.LEntry`	`anInt(String key, Integer value, Map<?,?> map)`
`static MapArgs.LEntry`	`anInt(String key, String strVal)` declares a modifiable parameter of type `Integer` and sets the initial value with a (numeric) `String`
`static MapArgs.LEntry`	`anInt(String key, String strVal, Map<?,?> map)`
`static MapArgs.LEntry`	`aRef(String key)` declares a modifiable parameter of type `Object` whose reference will be later found using a name.
`static MapArgs.LEntry`	`aRef(String key, String value)` declares a modifiable parameter of type `Object` whose reference will be later found using a name.
`static MapArgs.LEntry`	`aRef(String key, String value, Map<?,?> map)`
`static MapArgs`	`argMap()` the `argMap` methods are convenience factories for creating pair of String key-Object value
`static MapArgs`	`argMap(MapArgs.LEntry... args)` used in combination with Entry factory methods such as `a`, `anInt`, `aDbl`, `aString`, `aRef`
`static MapArgs`	`argMap(Object... args)` to use only when the corresponding object has a constructor with all needed arguments.
`Object[]`	`asFullArray(IndirectMap objectDictionary)` same remarks as `asFullMap`
`List<Object>`	`asFullList(IndirectMap objectDictionary)` same remarks as `asFullMap`
`MapArgs`	`asFullMap(IndirectMap objectDictionary)` better calls `isSafe` before calling this method otherwise will throw an EmptyParmException.
`List<Object>`	`asList()` returns a List of values contained in this structure (without the corresponding keys).
`static MapArgs.LEntry`	`aString(String key)` declares a modifiable parameter of type `String` but does not initialize it.
`static MapArgs.LEntry`	`aString(String key, String value)` declares a modifiable parameter of type `String` and sets the initials value.
`static MapArgs.LEntry`	`aString(String key, String value, Map<?,?> map)` declares a modifiable parameter of type `String` sets the initials value and annotates some properties
`static MapArgs.LEntry`	`aVal(Serializable val)` same as `aVal (key, value)` but here the name of the key is generated from the Class Name of the object.
`static MapArgs.LEntry`	`aVal(Serializable val, Map properties)`
`static MapArgs.LEntry`	`aVal(String key, Serializable val)` to be used for any object that has : `Serializable` implementation a symmetric way of dealing with strings: the `toString()` method returns a String that can be used to create an Object through static method `valueOf(thatString)` A typical example are `Enums`
`static MapArgs.LEntry`	`aVal(String key, Serializable val, Map properties)`
`void`	`clear()` the structure being immutable this is unsupported.
`MapArgs`	`clone()`
`boolean`	`containsKey(Object o)` as all "get" methods from the `Map` interface contract this method is implemented by testing all the values in the structure.
`boolean`	`containsValue(Object o)`
`Set<Map.Entry<String,Object>>`	`entrySet()`
`Object`	`get(int index)` the structure being immutable and having list features this method is both efficient and guaranteed to return always the same value.
`Object`	`get(Object o)`
`MapArgs.LEntry[]`	`getEntries()`
`boolean`	`isEmpty()`
`boolean`	`isSafe()` tells if all "hollow" parameters have been initialized.
`boolean`	`isValuesOnly()` tells that the structure does not contain any `HollowParm` object (so the contained values can be used "as is")
`Iterator<Object>`	`iterator()`
`Set<String>`	`keySet()`
`static Property`	`kv(String key, String value)`
`MapArgs`	`overlap(boolean acceptNullValues, List<Object> list)`
`boolean`	`overlap(boolean acceptNullValues, MapArgs.LEntry entry)` modifies a local Entry with another entry with the same key since modification could only operate on hollow parameters this is used if the entry reference a `HollowParm` object.
`MapArgs`	`overlap(boolean acceptNullvalues, MapArgs other)` operates a set of assignments of valued `HollowParm` objects in the argument to the corresponding `HollowParm` object in the current structure.
`MapArgs`	`overlap(boolean acceptNullvalues, Object[] array)` modifies the `HollowObjects` values with the values contained in the argument.
`boolean`	`prefersList()` this Map/list has only some list features and not those of a Map.
`Object`	`put(String s, Object o)` the structure being immutable this is unsupported.
`void`	`putAll(Map<? extends String,? extends Object> map)` the structure being immutable this is unsupported.
`static MapArgs.LEntry`	`ref(String key)`
`Object`	`remove(Object o)` the structure being immutable this is unsupported.
`int`	`size()`
`Object[]`	`toArray()` returns an array of values contained in this structure (without the corresponding keys).
`String`	`toString()`
`Collection<Object>`	`values()`

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Field Detail

EMPTY_MAPARGS

public static final MapArgs EMPTY_MAPARGS

Method Detail

argMap
```
public static MapArgs argMap()
```
the argMap methods are convenience factories for creating pair of String key-Object value

argMap
```
public static MapArgs argMap(MapArgs.LEntry... args)
```
used in combination with Entry factory methods such as a, anInt, aDbl, aString, aRef

Parameters:

args -

argMap
```
public static MapArgs argMap(Object... args)
```
to use only when the corresponding object has a constructor with all needed arguments. each object parameter which is a modifiable "named" parameter will be used as such, other objects will just get a default name (which is the argument number) and will be an immutable parameter.
Remember: this only works with classes that have the proper constructor (since a method like set3 may be called otherwise!).

Parameters:

args -

Returns:

a

public static MapArgs.LEntry a(String key,
                               Object value)

declares a parameter that is not open for modification.

Parameters:: key -; value -

aString

public static MapArgs.LEntry aString(String key,
                                     String value)

declares a modifiable parameter of type String and sets the initials value.

Parameters:: key -; value -

aString

public static MapArgs.LEntry aString(String key,
                                     String value,
                                     Map<?,?> map)

declares a modifiable parameter of type String sets the initials value and annotates some properties

Parameters:: key -; value -; map - keys and values will be transformed in Strings

aString
```
public static MapArgs.LEntry aString(String key)
```
declares a modifiable parameter of type String but does not initialize it.

Parameters:

key -

aRef
```
public static MapArgs.LEntry aRef(String key,
                                  String value)
```
declares a modifiable parameter of type Object whose reference will be later found using a name. sets the initials value.

Parameters:

key -

value -

aRef

public static MapArgs.LEntry aRef(String key,
                                  String value,
                                  Map<?,?> map)

ref

public static MapArgs.LEntry ref(String key)

aRef
```
public static MapArgs.LEntry aRef(String key)
```
declares a modifiable parameter of type Object whose reference will be later found using a name. does not initialize it.

Parameters:

key -

anInt

public static MapArgs.LEntry anInt(String key,
                                   Integer value)

declares a modifiable parameter of type Integer and sets the initial value.

Parameters:: key -; value -

anInt

public static MapArgs.LEntry anInt(String key,
                                   Integer value,
                                   Map<?,?> map)

anInt

public static MapArgs.LEntry anInt(String key,
                                   String strVal)

declares a modifiable parameter of type Integer and sets the initial value with a (numeric) String

Parameters:: key -; strVal -

anInt

public static MapArgs.LEntry anInt(String key,
                                   String strVal,
                                   Map<?,?> map)

anInt
```
public static MapArgs.LEntry anInt(String key)
```
declares a modifiable parameter of type Integer and does not initialize it.

Parameters:

key -

aBool

public static MapArgs.LEntry aBool(String key,
                                   Boolean value)

aBool

public static MapArgs.LEntry aBool(String key,
                                   Boolean value,
                                   Map<?,?> map)

aBool

public static MapArgs.LEntry aBool(String key,
                                   String strVal)

aBool

public static MapArgs.LEntry aBool(String key,
                                   String strVal,
                                   Map<?,?> map)

aBool
```
public static MapArgs.LEntry aBool(String key)
```
declares a modifiable parameter of type boolean and initializes it to false

Parameters:

key -

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  Double value)

declares a modifiable parameter of type Double and sets the initial value.

Parameters:: key -; value -

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  Double value,
                                  Map<?,?> map)

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  BigDecimal value)

declares a modifiable parameter of type BigDecimal and sets the initial value.

Parameters:: key -; value -

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  BigDecimal value,
                                  Map<?,?> map)

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  String strVal)

declares a modifiable parameter of type BigDecimal and sets the initial value with a (numeric) String

Parameters:: key -; strVal -

aDbl

public static MapArgs.LEntry aDbl(String key,
                                  String strVal,
                                  Map<?,?> map)

aDbl
```
public static MapArgs.LEntry aDbl(String key)
```
declares a modifiable parameter of type Double or BigDecimal and does not initialize it.

Parameters:

key -

aList

public static MapArgs.LEntry aList(String key,
                                   List list)

declares a modifiable parameter which is a list of simple values (do not use for references)

Parameters:: key -; list -

aList

public static MapArgs.LEntry aList(String key,
                                   double[] arrayDouble)

aList

public static MapArgs.LEntry aList(String key,
                                   float[] arrayFloat)

aList

public static MapArgs.LEntry aList(String key,
                                   List list,
                                   Map<?,?> map)

aMap

public static MapArgs.LEntry aMap(String key,
                                  Map map)

declares a modifiable parameter which is a Map where values are of a simple type (do not use for references)

Parameters:: key -; map -

aMap

public static MapArgs.LEntry aMap(String key,
                                  Map map,
                                  Map props)

anArray

public static MapArgs.LEntry anArray(String key,
                                     int[] array)

declares a modifiable parameter of an array type.

Parameters:: key -; array -

anArray

public static MapArgs.LEntry anArray(String key,
                                     int[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     byte[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     byte[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     char[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     char[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     float[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     float[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     double[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     double[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     boolean[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     boolean[] array,
                                     Map map)

anArray

public static MapArgs.LEntry anArray(String key,
                                     Object[] array)

anArray

public static MapArgs.LEntry anArray(String key,
                                     Object[] array,
                                     Map map)

aVal
```
public static MapArgs.LEntry aVal(String key,
                                  Serializable val)
```
to be used for any object that has :
- Serializable implementation
- a symmetric way of dealing with strings: the toString() method returns a String that can be used to create an Object through static method valueOf(thatString)
A typical example are Enums
Parameters:

key -

val -

aVal

public static MapArgs.LEntry aVal(String key,
                                  Serializable val,
                                  Map properties)

aVal
```
public static MapArgs.LEntry aVal(Serializable val)
```
same as aVal (key, value) but here the name of the key is generated from the Class Name of the object.
So if the value is of type RunningWay (an Enum) then the key will be runningWay

Parameters:

val -

aVal

public static MapArgs.LEntry aVal(Serializable val,
                                  Map properties)

kv

public static Property kv(String key,
                          String value)

toString
```
public String toString()
```
Overrides:

toString in class Object

clone
```
public MapArgs clone()
```
Overrides:

clone in class Object

prefersList
```
public boolean prefersList()
```
this Map/list has only some list features and not those of a Map.

size
```
public int size()
```
Specified by:

size in interface Map<String,Object>

isEmpty
```
public boolean isEmpty()
```
Specified by:

isEmpty in interface Map<String,Object>

containsKey
```
public boolean containsKey(Object o)
```
as all "get" methods from the Map interface contract this method is implemented by testing all the values in the structure. Though generally inefficient compared to a true Map it is considered that, due to the low number of values, it is still an acceptable compromise.

Specified by:

containsKey in interface Map<String,Object>

Parameters:

o -

containsValue
```
public boolean containsValue(Object o)
```
Specified by:

containsValue in interface Map<String,Object>

get
```
public Object get(Object o)
```
Specified by:

get in interface Map<String,Object>

get
```
public Object get(int index)
```
the structure being immutable and having list features this method is both efficient and guaranteed to return always the same value.

Parameters:

index -

put
```
public Object put(String s,
                  Object o)
```
the structure being immutable this is unsupported. unless it is to change a modifiable hollow Parameter

Specified by:

put in interface Map<String,Object>

Parameters:

s -

o -

remove
```
public Object remove(Object o)
```
the structure being immutable this is unsupported.

Specified by:

remove in interface Map<String,Object>

Parameters:

o -

putAll
```
public void putAll(Map<? extends String,? extends Object> map)
```
the structure being immutable this is unsupported.

Specified by:

putAll in interface Map<String,Object>

Parameters:

map -

clear
```
public void clear()
```
the structure being immutable this is unsupported.

Specified by:

clear in interface Map<String,Object>

keySet
```
public Set<String> keySet()
```
Specified by:

keySet in interface Map<String,Object>

values
```
public Collection<Object> values()
```
Specified by:

values in interface Map<String,Object>

toArray
```
public Object[] toArray()
```
returns an array of values contained in this structure (without the corresponding keys). Beware the corresponding values may not be used "as is" since some may be HollowParm : to get a safe array of object use isSafe and then asFullArray, otherwise to be sure that the array can be used directly test isValuesOnly()

asList
```
public List<Object> asList()
```
returns a List of values contained in this structure (without the corresponding keys). Beware the corresponding values may not be used "as is" since some may be HollowParm : to get a safe List of object use isSafe and then asFullList, otherwise to be sure that the list can be used directly test isValuesOnly()

entrySet
```
public Set<Map.Entry<String,Object>> entrySet()
```
Specified by:

entrySet in interface Map<String,Object>

getEntries
```
public MapArgs.LEntry[] getEntries()
```

iterator
```
public Iterator<Object> iterator()
```
Specified by:

iterator in interface Iterable<Object>

isSafe
```
public boolean isSafe()
```
tells if all "hollow" parameters have been initialized.

isValuesOnly
```
public boolean isValuesOnly()
```
tells that the structure does not contain any HollowParm object (so the contained values can be used "as is")

asFullMap
```
public MapArgs asFullMap(IndirectMap objectDictionary)
```
better calls isSafe before calling this method otherwise will throw an EmptyParmException.

Parameters:

objectDictionary - a map that can resolve an object reference using its name if null it will be considered that there are no "Hollow" Object in the structure (see isValuesOnly) so use at your own risk!

asFullArray
```
public Object[] asFullArray(IndirectMap objectDictionary)
```
same remarks as asFullMap

Parameters:

objectDictionary -

Returns:

asFullList

public List<Object> asFullList(IndirectMap objectDictionary)

same remarks as asFullMap

Parameters:: objectDictionary -

overlap
```
public boolean overlap(boolean acceptNullValues,
                       MapArgs.LEntry entry)
```
modifies a local Entry with another entry with the same key since modification could only operate on hollow parameters this is used if the entry reference a HollowParm object.

Parameters:

acceptNullValues - do we accept setting values to null

entry -

Returns:

true if an assignment has been operated

Throws:

org.lsst.gruth.types.IncompatibleTypeException - if the assignment can not be made due to type incompatible org.lsst.gruth.types.

overlap
```
public MapArgs overlap(boolean acceptNullvalues,
                       MapArgs other)
```
operates a set of assignments of valued HollowParm objects in the argument to the corresponding HollowParm object in the current structure.
see overlap with Object[] for more details.
beware ; implementation not synchronized!

Parameters:

acceptNullvalues - if null values in the other arguments should be assigned to objects in the result

other - another MapArgs object

Returns:

a new modified object

Throws:

org.lsst.gruth.types.IncompatibleTypeException - if incompatible assignment

ParmStructureException - if incompatible structure

overlap
```
public MapArgs overlap(boolean acceptNullvalues,
                       Object[] array)
```
modifies the HollowObjects values with the values contained in the argument. the structure of the current Mapargs and the argument should be analog but not necessarily the same:
for each element in the array argument
- if it is a HollowParm and the local corresponding data is an HollowParm then an assignment of values is tried
- if it is a HollowParm and the local corresponding data is not a ParmStructureException is fired
- if it is not a HollowParm and the local corresponding data is an HollowParm then an assignment of values is tried But if org.lsst.gruth.types are incompatible there will be a ParmStructureException fired
- if it is not a HollowParm and the local corresponding data is not an HollowParm nothing happens at this stage
Parameters:

acceptNullvalues -

array -

Returns:

another MapArgs with modified values

overlap

public MapArgs overlap(boolean acceptNullValues,
                       List<Object> list)

Class MapArgs

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Methods inherited from interface java.lang.Iterable

Field Detail

EMPTY_MAPARGS

Method Detail

argMap

argMap

argMap

a

aString

aString

aString

aRef

aRef

ref

aRef

anInt

anInt

anInt

anInt

anInt

aBool

aBool

aBool

aBool

aBool

aDbl

aDbl

aDbl

aDbl

aDbl

aDbl

aDbl

aList

aList

aList

aList

aMap

aMap

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

anArray

aVal

aVal

aVal

aVal

kv

toString

clone

prefersList

size

isEmpty

containsKey

containsValue

get

get

put

remove

putAll

clear

keySet

values

toArray