public class MapExtractor
extends java.lang.Object
implements java.lang.Iterable<java.lang.Object>
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.
Constructor and Description |
---|
MapExtractor(java.util.Map<?,?> map,
java.lang.String displayName)
Create a new instance wrapping the specified map.
|
Modifier and Type | Method and 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.
|
public MapExtractor(java.util.Map<?,?> map, java.lang.String displayName)
The underlying map is not copied, and any mutations on it will also affect this object.
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".public boolean isEmpty()
public java.util.Map<?,?> getUnderlyingMap()
public java.lang.String getDisplayName()
public java.lang.String toString()
toString
in class java.lang.Object
public java.util.Iterator<java.lang.Object> iterator()
iterator
in interface java.lang.Iterable<java.lang.Object>
public MapExtractor put(java.lang.Object key, java.lang.Object value)
public void checkNoItemsRemaining() throws java.lang.IllegalArgumentException
java.lang.IllegalArgumentException
- If there are any unexpected items in this map that were not read.public <T> T get(java.lang.Object key, java.lang.Class<T> clazz, T defaultValue) throws java.lang.IllegalArgumentException
T
- The type of the value. This can be any type including an enumeration.key
- The lookup key.clazz
- The type for the value.defaultValue
- A default value of the appropriate type. Can be null.java.lang.IllegalArgumentException
public <T> T get(java.lang.Object key, T defaultValue) throws java.lang.IllegalArgumentException
T
- The type of the value. This can be any type including an enumeration.key
- The lookup key.defaultValue
- A default value of the appropriate type; since this is used to infer the type it cannot be
null.java.lang.IllegalArgumentException
public <T> T get(java.lang.Object key, java.lang.Class<T> clazz) throws java.lang.IllegalArgumentException
T
- The type of the value. This can be any type including an enumeration.key
- The lookup key.clazz
- The type for the value.java.lang.IllegalArgumentException
public MapExtractor getMap(java.lang.Object key, boolean emptyIfMissing) throws java.lang.IllegalArgumentException
Remember to call checkNoItemsRemaining()
on the returned map if required to detect invalid
items (e.g. for configuration).
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.java.lang.IllegalArgumentException
- If the value is missing (unless emptyIfMissing), null or has the wrong type.public <T> java.util.List<T> getList(java.lang.Object key, java.lang.Class<T> itemType, boolean emptyIfMissing) throws java.lang.IllegalArgumentException
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.
T
- The type of the items in this list.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.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.public java.util.List<MapExtractor> getListOfMaps(java.lang.Object key, boolean emptyOnMissingKeys) throws java.lang.IllegalArgumentException
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.java.lang.IllegalArgumentException
- If the value is missing (unless emptyIfMissing), null or has the wrong type or
item type.public java.util.List<MapExtractor> getListOfMaps(java.lang.Object key, boolean emptyOnMissingKeys, boolean singleEntryMapForNonMapValues) throws java.lang.IllegalArgumentException
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.java.lang.IllegalArgumentException
- If the value is missing (unless emptyIfMissing), null or has the wrong type or
item type.public java.lang.String getStringDisallowEmpty(java.lang.Object key) throws java.lang.IllegalArgumentException
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.
UsegetStringAllowEmpty(Object)
instead of this method if empty string values should be
permitted.key
- The lookup key.java.lang.IllegalArgumentException
- If the value is empty, missing, null or has the wrong type.public java.lang.String getStringDisallowEmpty(java.lang.Object key, java.lang.String defaultValue) throws java.lang.IllegalArgumentException
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.
UsegetStringAllowEmpty(Object, String)
instead of this method if empty string values should be
permitted.key
- The lookup key.defaultValue
- The return value if the key is missing; can be empty/null if desired.java.lang.IllegalArgumentException
- If the value exists but has the wrong type.public java.lang.String getStringAllowEmpty(java.lang.Object key, java.lang.String defaultValue) throws java.lang.IllegalArgumentException
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 callingget(Object, Class, Object)
for the String class.
Use getStringDisallowEmpty(Object, String)
instead of this method if empty string values should not be returned.key
- The lookup key.defaultValue
- The return value if the key is missing; can be empty/null if desired.java.lang.IllegalArgumentException
- If the value exists but has the wrong type.public java.lang.String getStringAllowEmpty(java.lang.Object key) throws java.lang.IllegalArgumentException
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 callingget(Object, Class)
for the String class.
Use getStringDisallowEmpty(Object)
instead of this method if empty string values should not be returned.key
- The lookup key.java.lang.IllegalArgumentException
- If the value is missing, null or has the wrong type.Submit a bug or feature
Copyright (c) 2013-2017 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG.