org.lsst.gruth.jutils

Class MapArgs

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>

Method Summary

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	aList(String key, String strList)
static MapArgs.LEntry	aList(String key, String strList, 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	aMap(String key, String strMap)
static MapArgs.LEntry	aMap(String key, String strMap, 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 <T> Class	anImpl(Class<T> anInterface, Class<? extends T> aClass) Deprecated.
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	argList(Object... args) factory method for specifying a list of parameter: the ensuing MapArg has only list features.
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<String,Object> objectDictionary) same remarks as asFullMap
List<Object>	asFullList(IndirectMap<String,Object> objectDictionary) same remarks as asFullMap
MapArgs	asFullMap(IndirectMap<String,Object> 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	aStruct(String key, Class clazz, List list) parameter is a list used to create a struct object.
static MapArgs.LEntry	aStruct(String key, Class clazz, List list, Map properties)
static MapArgs.LEntry	aStruct(String key, Class clazz, Map map)
static MapArgs.LEntry	aStruct(String key, Class clazz, Map map, Map 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.
static String	predicate(String argName, String expr) Deprecated.
boolean	prefersList() this Map/list has only some list features and not those of a Map.
static MapArgs	proxy(Object obj) Deprecated.
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	rawList(Object... args) hybrid list that may contains HollowParms
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

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:

argList

public static MapArgs argList(Object... args)

factory method for specifying a list of parameter: the ensuing MapArg has only list features.

Parameters:

args -

proxy

@Deprecated
public static MapArgs proxy(Object obj)

Deprecated.

creates a dummy list with one argument (kept for future "proxy" enhancements)

Parameters:

obj -

rawList

public static MapArgs rawList(Object... args)

hybrid list that may contains HollowParms

Parameters:

args -

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)

aList

public static MapArgs.LEntry aList(String key,
                                   String strList)

aList

public static MapArgs.LEntry aList(String key,
                                   String strList,
                                   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)

aMap

public static MapArgs.LEntry aMap(String key,
                                  String strMap)

aMap

public static MapArgs.LEntry aMap(String key,
                                  String strMap,
                                  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)

aStruct

public static MapArgs.LEntry aStruct(String key,
                                     Class clazz,
                                     List list)

parameter is a list used to create a struct object. that is Serializable, method toString returns a List in groovy format and has a constructor with corresponding members of the list

Parameters:

key -

clazz -

list -

aStruct

public static MapArgs.LEntry aStruct(String key,
                                     Class clazz,
                                     Map map)

aStruct

public static MapArgs.LEntry aStruct(String key,
                                     Class clazz,
                                     List list,
                                     Map properties)

aStruct

public static MapArgs.LEntry aStruct(String key,
                                     Class clazz,
                                     Map map,
                                     Map properties)

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)

predicate

@Deprecated
public static String predicate(String argName,
                                           String expr)

Deprecated.

to be used in constraints definition to declare an expression that will be evaluated with a single variable

Parameters:

argName - the name of the variable in the expression

expr - the code of the expression

Returns:

a String to be evaluated by constraints

anImpl

@Deprecated
public static <T> Class anImpl(Class<T> anInterface,
                                           Class<? extends T> aClass)

Deprecated.

declares a modifiable class : any modification to this value must implement the interface.

Type Parameters:

T -

Parameters:

anInterface -

aClass -

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<String,Object> 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<String,Object> objectDictionary)

same remarks as asFullMap

Parameters:

objectDictionary -

asFullList

public List<Object> asFullList(IndirectMap<String,Object> 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)