Package com.softwareag.connectivity.util

Class MapExtractor

java.lang.Object

com.softwareag.connectivity.util.MapExtractor

All Implemented Interfaces:

java.lang.Iterable<java.lang.Object>

public class MapExtractor
extends java.lang.Object
implements java.lang.Iterable<java.lang.Object>

Provides a type-safe way to extract values from a heterogenous Map (where keys and values could be of any type), with user-friendly error messages identifying the map and key within the map if any item is missing or has the wrong type.

Useful for handling message payload, metadata or plug-in configuration objects. Typical usage would involve creating an instance called "config" for accessing a plug-in's configuration, calling appropriate get methods to extract all required information into correctly typed fields then calling checkNoItemsRemaining() to produce a clear error if the user tried to specify any unsupported options.

Automatic conversions are performed in both directions between String and numeric/boolean/enumeration types, but not between String and complex types such as list/map.

This class does not provide thread-safety so the caller must supply locking if accessed from multiple threads.

Example:

MapExtractor config = new MapExtractor(params.getConfig(), "configuration");

// must specify either default value (if optional) or class (to indicate the type if mandatory)
myLongInteger = config.get("myLongInteger", 1000L);
myEnum = config.get("myEnum", MyEnumType.MY_DEFAULT_VALUE);
myBool = config.get("myBool", Boolean.class); 
myString = config.getStringDisallowEmpty("myString");
myList = config.getList("myList", String.class, true);

config.checkNoItemsRemaining();
 

Since:

10.0.0

Constructor Summary

Constructors

Constructor	Description
MapExtractor(java.util.Map<?,?> map, java.lang.String displayName)	Create a new instance wrapping the specified map.

Method Summary

Modifier and Type	Method	Description
void	checkNoItemsRemaining()	Checks that all entries in this map have been read (using one of the get methods on this class), and throws an exception listing the unexpected items that were not read if there are any.
<T> T	get(java.lang.Object key, java.lang.Class<T> clazz)	Get a value of the specified type, throwing an exception if it has the wrong type, a null value or is not present.
<T> T	get(java.lang.Object key, java.lang.Class<T> clazz, T defaultValue)	Get a value of the specified type, returning a default value if not present or null, and throwing an exception if it has the wrong type.
<T> T	get(java.lang.Object key, T defaultValue)	Get a value of the specified type, returning a default value if not present or null, and throwing an exception if it has the wrong type.
java.lang.String	getDisplayName()	Retrieve the display name associated with this map.
<T> java.util.List<T>	getList(java.lang.Object key, java.lang.Class<T> itemType, boolean emptyIfMissing)	Get a list where each item has the same type.
java.util.List<MapExtractor>	getListOfMaps(java.lang.Object key, boolean emptyOnMissingKeys)	Get a list where each item is a Map, each wrapped in its own MapExtractor for simplified access.
java.util.List<MapExtractor>	getListOfMaps(java.lang.Object key, boolean emptyOnMissingKeys, boolean singleEntryMapForNonMapValues)	Get a list where each item is a Map, each wrapped in its own MapExtractor for simplified access.
MapExtractor	getMap(java.lang.Object key, boolean emptyIfMissing)	Get a value of type Map, wrapped in a new MapExtractor.
java.lang.String	getStringAllowEmpty(java.lang.Object key)	Get a string value; if the value is an empty string it will be returned, if the value is missing or null an exception is thrown.
java.lang.String	getStringAllowEmpty(java.lang.Object key, java.lang.String defaultValue)	Get a string value; if the value is an empty string it will be returned, if the value is missing or null the specified defaultValue is returned.
java.lang.String	getStringDisallowEmpty(java.lang.Object key)	Get a string value; if the value is an empty string, null or missing an exception is thrown.
java.lang.String	getStringDisallowEmpty(java.lang.Object key, java.lang.String defaultValue)	Get a string value; if the value is an empty string, null or missing the defaultValue will be returned instead.
java.util.Map<?,?>	getUnderlyingMap()	Get the Map object that this extractor refers to.
boolean	isEmpty()	Returns true if the map is empty.
java.util.Iterator<java.lang.Object>	iterator()	Iterates over the keys (non-deterministic order).
MapExtractor	put(java.lang.Object key, java.lang.Object value)	Adds or replaces an item in the underlying map.
java.lang.String	toString()	A string representation of this object including both the display name and map contents.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

MapExtractor

public MapExtractor(java.util.Map<?,?> map,
                    java.lang.String displayName)

Create a new instance wrapping the specified map.

The underlying map is not copied, and any mutations on it will also affect this object.

Parameters:

map - The map to be used. A null value is treated as an empty map.

displayName - A user-friendly string for identifying this map, used in error messages. Use of lowerCamelCase without spaces is recommended, for example "message.metadata", "config", "config.myListOfMaps".

Method Detail

isEmpty

public boolean isEmpty()

Returns true if the map is empty.

Returns:

true if the map is empty.

getUnderlyingMap

public java.util.Map<?,?> getUnderlyingMap()

Get the Map object that this extractor refers to.

getDisplayName

public java.lang.String getDisplayName()

Retrieve the display name associated with this map.

Returns:

The display name for this map.

toString

public java.lang.String toString()

A string representation of this object including both the display name and map contents. The exact format of this string may change at any time.

Overrides:

toString in class java.lang.Object

iterator

public java.util.Iterator<java.lang.Object> iterator()

Iterates over the keys (non-deterministic order).

Specified by:

iterator in interface java.lang.Iterable<java.lang.Object>

Returns:

An iterator over the set of keys contained in this map.

put

public MapExtractor put(java.lang.Object key,
                        java.lang.Object value)

Adds or replaces an item in the underlying map.

Returns:

This MapExtractor instance (for fluent API usage).

checkNoItemsRemaining

public void checkNoItemsRemaining()
                           throws java.lang.IllegalArgumentException

Checks that all entries in this map have been read (using one of the get methods on this class), and throws an exception listing the unexpected items that were not read if there are any. This is useful for checking there are no unsupported keys in the map, for example after to detect any invalid settings in a plug-in's configuration map.

Throws:

java.lang.IllegalArgumentException - If there are any unexpected items in this map that were not read.

get

public <T> T get(java.lang.Object key,
                 java.lang.Class<T> clazz,
                 T defaultValue)
          throws java.lang.IllegalArgumentException

Get a value of the specified type, returning a default value if not present or null, and throwing an exception if it has the wrong type.

Type Parameters:

T - The type of the value. This can be any type including an enumeration.

Parameters:

key - The lookup key.

clazz - The type for the value.

defaultValue - A default value of the appropriate type. Can be null.

Returns:

The value corresponding to the key (if found and not null), or else the defaultValue. Cannot be null unless defaultValue is null.

Throws:

java.lang.IllegalArgumentException

get

public <T> T get(java.lang.Object key,
                 T defaultValue)
          throws java.lang.IllegalArgumentException

Get a value of the specified type, returning a default value if not present or null, and throwing an exception if it has the wrong type.

Type Parameters:

T - The type of the value. This can be any type including an enumeration.

Parameters:

key - The lookup key.

defaultValue - A default value of the appropriate type; since this is used to infer the type it cannot be null.

Returns:

The value, if found, corresponding to the key. Never null.

Throws:

java.lang.IllegalArgumentException

get

public <T> T get(java.lang.Object key,
                 java.lang.Class<T> clazz)
          throws java.lang.IllegalArgumentException

Get a value of the specified type, throwing an exception if it has the wrong type, a null value or is not present.

Type Parameters:

T - The type of the value. This can be any type including an enumeration.

Parameters:

key - The lookup key.

clazz - The type for the value.

Returns:

The value, if found, corresponding to the key. Never null.

Throws:

java.lang.IllegalArgumentException

getMap

public MapExtractor getMap(java.lang.Object key,
                           boolean emptyIfMissing)
                    throws java.lang.IllegalArgumentException

Get a value of type Map, wrapped in a new MapExtractor.

Remember to call checkNoItemsRemaining() on the returned map if required to detect invalid items (e.g. for configuration).

Parameters:

key - The lookup key.

emptyIfMissing - If true, an empty (read-only) map is returned when the key is missing, if false then an exception is thrown.

Returns:

A MapExtractor containing the requested map, never null. May be empty.

Throws:

java.lang.IllegalArgumentException - If the value is missing (unless emptyIfMissing), null or has the wrong type.

getList

public <T> java.util.List<T> getList(java.lang.Object key,
                                     java.lang.Class<T> itemType,
                                     boolean emptyIfMissing)
                              throws java.lang.IllegalArgumentException

Get a list where each item has the same type.

See also the get(Object, Class) method which should be used for lists where the item type can vary, and the getListOfMaps(Object, boolean, boolean) method which provides improved functionality when the item type is Map.

Type Parameters:

T - The type of the items in this list.

Parameters:

key - The lookup key.

itemType - The expected type of the items in this list.

emptyIfMissing - If true, an empty (read-only) list is returned when the key is missing, if false then an exception is thrown.

Returns:

A List containing the elements, never null, and never containing any null items.

Throws:

java.lang.IllegalArgumentException - If the value is missing (unless emptyIfMissing), null or has the wrong type, or any item in the list is of the wrong type or null.

getListOfMaps

public java.util.List<MapExtractor> getListOfMaps(java.lang.Object key,
                                                  boolean emptyOnMissingKeys)
                                           throws java.lang.IllegalArgumentException

Get a list where each item is a Map, each wrapped in its own MapExtractor for simplified access.

Parameters:

key - The lookup key.

emptyOnMissingKeys - If true, an empty (read-only) list is returned when the key is missing, if false then an exception is thrown.

Returns:

A List containing the map extractors for each item in the list. There will be no null items in this list.

Throws:

java.lang.IllegalArgumentException - If the value is missing (unless emptyIfMissing), null or has the wrong type or item type.

getListOfMaps

public java.util.List<MapExtractor> getListOfMaps(java.lang.Object key,
                                                  boolean emptyOnMissingKeys,
                                                  boolean singleEntryMapForNonMapValues)
                                           throws java.lang.IllegalArgumentException

Get a list where each item is a Map, each wrapped in its own MapExtractor for simplified access. Also supports automatic conversion of non-maps to singleton maps for use when reading yaml.

Parameters:

key - The lookup key.

emptyOnMissingKeys - If true, an empty (read-only) list is returned when the key is missing, if false then an exception is thrown.

singleEntryMapForNonMapValues - If true, any non-map items in the list are represented as the key of a 1-entry map with a null value. This is useful for configuration loaded from a .yaml file where maps that have no values are usually represented as simple strings. Provides simple uniform processing regardless where items may be strings or maps.

Returns:

A List containing the map extractors for each item in the list. There will be no null items in this list.

Throws:

java.lang.IllegalArgumentException - If the value is missing (unless emptyIfMissing), null or has the wrong type or item type.

getStringDisallowEmpty

public java.lang.String getStringDisallowEmpty(java.lang.Object key)
                                        throws java.lang.IllegalArgumentException

Get a string value; if the value is an empty string, null or missing an exception is thrown.

If the type does not match an exception is thrown unless the value is a Boolean or a Number in which case the string representation is returned.

Use getStringAllowEmpty(Object) instead of this method if empty string values should be permitted.

Parameters:

key - The lookup key.

Returns:

The value (never null or empty).

Throws:

java.lang.IllegalArgumentException - If the value is empty, missing, null or has the wrong type. Never null or empty.

getStringDisallowEmpty

public java.lang.String getStringDisallowEmpty(java.lang.Object key,
                                               java.lang.String defaultValue)
                                        throws java.lang.IllegalArgumentException

Get a string value; if the value is an empty string, null or missing the defaultValue will be returned instead.

If the type does not match an exception is thrown unless the value is a Boolean or a Number in which case the string representation is returned.

Use getStringAllowEmpty(Object, String) instead of this method if empty string values should be permitted.

Parameters:

key - The lookup key.

defaultValue - The return value if the key is missing; can be empty/null if desired.

Returns:

The value (never null or empty), or defaultValue.

Throws:

java.lang.IllegalArgumentException - If the value exists but has the wrong type. Cannot be null or empty unless defaultValue is null or empty.

getStringAllowEmpty

public java.lang.String getStringAllowEmpty(java.lang.Object key,
                                            java.lang.String defaultValue)
                                     throws java.lang.IllegalArgumentException

Get a string value; if the value is an empty string it will be returned, if the value is missing or null the specified defaultValue is returned.

If the type does not match an exception is thrown unless the value is a Boolean or a Number in which case the string representation is returned.

This method is equivalent to calling get(Object, Class, Object) for the String class. Use getStringDisallowEmpty(Object, String) instead of this method if empty string values should not be returned.

Parameters:

key - The lookup key.

defaultValue - The return value if the key is missing; can be empty/null if desired.

Returns:

The value (which may be empty but never null), or defaultValue.

Throws:

java.lang.IllegalArgumentException - If the value exists but has the wrong type. Cannot be null unless defaultValue is null.

getStringAllowEmpty

public java.lang.String getStringAllowEmpty(java.lang.Object key)
                                     throws java.lang.IllegalArgumentException

Get a string value; if the value is an empty string it will be returned, if the value is missing or null an exception is thrown.

If the type does not match an exception is thrown unless the value is a Boolean or a Number in which case the string representation is returned.

This method is equivalent to calling get(Object, Class) for the String class. Use getStringDisallowEmpty(Object) instead of this method if empty string values should not be returned.

Parameters:

key - The lookup key.

Returns:

The value, which may be empty but never null.

Throws:

java.lang.IllegalArgumentException - If the value is missing, null or has the wrong type. Never null.