com.programix.value
Class ValueMap

java.lang.Object
  com.programix.value.ValueMap

All Implemented Interfaces:

Serializable

public class ValueMap
extends Object
implements Serializable

Maps String keys to Value values with an iteration order matching the insertion order.

Many of the methods on this class declare that they might throw a ValueException or a ValueMapException or a subclass of ValueMapException, ValueMapRequiredKeyException. All three of these exceptions are subclasses of RuntimeException so they do not have to be explicitly caught (aka "can-catch" exceptions or "unchecked" exceptions).

ValueMap's can be populated directly from files (and other stream sources) when those files are in a format very similar to that which Properties reads, specifically:

• The 'key' and the 'value' are delimited by the first = found on the line and that delimiter is not included in the text of the key or in the text of the value. If any more ='s are present, they are retained as part of the value—only the first = gets special consideration.
• The 'key' is from the beginning of the line up to the first occurrence of = character.
• The 'value' is from the first = until the end of the line.
• If = is the last non-whitespace character on the line, then the value is a zero-length String.
• Both the 'key' and the 'value' have all their leading and trailing whitespace trimmed before being stored. It is not possible to have a key or a value that has leading whitespace or trailing whitespace.
• Blank lines (and lines of only whitespace) are ignored.
• Lines whose first non-whitespace character is # are treated as ignorable comments.

Author:

Paul Hyde

See Also:

Serialized Form

Constructor Summary

ValueMap()
Creates a mapping that locks on this instance of ValueMap.

ValueMap(Object lock)
Creates a mapping which synchronizes on the specified lock object.

Method Summary

boolean	containsAnyKeyWithPrefix(String prefix) Returns true if there are currently any keys that start with the specified prefix.
boolean	containsKey(String key) Returns true if a Value is currently stored for the specified key.
static ValueMap	createFrom(BufferedReader in) Creates a mapping from the specified data source.
static ValueMap	createFrom(File source)
static ValueMap	createFrom(InputStream rawIn)
static ValueMap	createFrom(Map map) Copies the entries from the specified Map into a new ValueMap.
static ValueMap	createFrom(Reader rawIn) Creates a mapping from the specified data source.
static ValueMap	createFrom(URL source)
static ValueMap	createFromFile(String sourceFilename)
static ValueMap	createFromResource(String resourceLocation)
static ValueMap	createFromResource(String resourceLocation, Class searchStartPoint)
boolean	doesNotContainKey(String key) Returns true if the specified key is not present in this map.
Value	get(String key) Retrieves the Value mapped to the specified key or null if there is no such key.
BigDecimal	getBigDecimal(String key) Returns the value stored under the specified required key as a BigDecimal.
BigDecimal	getBigDecimal(String key, BigDecimal defaultValue) Returns the value stored under the specified optional key as a BigDecimal.
byte[]	getBytes(String key) Returns the value stored under the specified required key as a byte[].
byte[]	getBytes(String key, byte[] defaultValue) Returns the value stored under the specified optional key as a byte[].
InputStream	getBytesAsStream(String key) Returns the value stored under the specified required key as an InputStream.
InputStream	getBytesAsStream(String key, InputStream defaultValue) Returns the value stored under the specified optional key as an InputStream.
DateTime	getDateTime(String key) Returns the value stored under the specified required key as a DateTime (defaulting to the UTC timezone if necessary).
DateTime	getDateTime(String key, DateTime defaultValue) Returns the value stored under the specified optional key as a DateTime (defaulting to the UTC timezone if necessary).
DateTime	getDateTime(String key, TimeZone tz) Returns the value stored under the specified required key as a DateTime (defaulting to the specified timezone if necessary).
DateTime	getDateTime(String key, TimeZone tz, DateTime defaultValue) Returns the value stored under the specified optional key as a DateTime (defaulting to the specified timezone if necessary).
DateTime	getDateTimeLocal(String key) Returns the value stored under the specified required key as a DateTime (defaulting to the local VM's timezone if necessary).
DateTime	getDateTimeLocal(String key, DateTime defaultValue) Returns the value stored under the specified optional key as a DateTime (defaulting to the local VM's timezone if necessary).
double	getDouble(String key) Returns the value stored under the specified required key as a double.
double	getDouble(String key, double defaultValue) Returns the value stored under the specified optional key as a double.
float	getFloat(String key) Returns the value stored under the specified required key as a float.
float	getFloat(String key, float defaultValue) Returns the value stored under the specified optional key as a float.
int	getInt(String key) Returns the value stored under the specified required key as an int.
int	getInt(String key, int defaultValue) Returns the value stored under the specified optional key as an int.
Integer	getIntegerNumber(String key) Returns the value stored under the specified required key as an Integer.
Integer	getIntegerNumber(String key, Integer defaultValue) Returns the value stored under the specified optional key as an Integer.
Object	getLockObject() Returns the object used for synchronization.
long	getLong(String key) Returns the value stored under the specified required key as a long.
long	getLong(String key, long defaultValue) Returns the value stored under the specified optional key as a long.
Long	getLongNumber(String key) Returns the value stored under the specified required key as a Long.
Long	getLongNumber(String key, Long defaultValue) Returns the value stored under the specified optional key as a Long.
Map	getMapView() Returns a read-only view of all the mappings as a Map.
ValueMap	getNestedValueMap(String keyPrefix) Returns a new ValueMap for all the key/value pairs with the specified key prefix (with the key prefix trimmed off).
Number	getNumber(String key) Returns the value stored under the specified required key as a Number.
Number	getNumber(String key, Number defaultValue) Returns the value stored under the specified optional key as a Number.
Object	getObject(String key, Class type) Returns the value stored under the specified required key as an Object.
Object	getObject(String key, Class type, Object defaultValue) Returns the value stored under the specified optional key as an Object.
Value	getOptional(String key, Value defaultValue) Returns the Value mapped to the specified key or if nothing is mapped to the key, defaultValue is returned.
String[]	getOrderedKeys() Returns all the keys in the map in insertion order.
PlainDate	getPlainDate(String key) Returns the value stored under the specified required key as a PlainDate.
PlainDate	getPlainDate(String key, PlainDate defaultValue) Returns the value stored under the specified optional key as a PlainDate.
Properties	getProperties() Returns a copy of all the mappings as a Properties.
Value	getRequired(String key) Returns the Value mapped to the specified key or if nothing is mapped to the key, ValueMapRequiredKeyException is thrown.
int	getSize() Returns the number of entries in this ValueMap.
String	getString(String key) Returns the value stored under the specified required key as a String.
String	getString(String key, String defaultValue) Returns the value stored under the specified optional key as a String.
TriState	getTriState(String key) Returns the value stored under the specified required key as a TriState.
TriState	getTriState(String key, TriState defaultValue) Returns the value stored under the specified optional key as a TriState.
boolean	isTrue(String key) Returns the value stored under the specified required key as a boolean.
boolean	isTrue(String key, boolean defaultValue) Returns the value stored under the specified optional key as a boolean.
Value	put(String key, int value) Stores (and possibly replaces) a key-value pair.
Value	put(String key, long value) Stores (and possibly replaces) a key-value pair.
Value	put(String key, Number value) Stores (and possibly replaces) a key-value pair.
Value	put(String key, Object value) Stores (and possibly replaces) a key-value pair.
Value	put(String key, String value) Stores (and possibly replaces) a key-value pair.
Value	put(String key, Value value) Stores (and possibly replaces) a key-value pair.
void	putAll(ValueMap source) Copies all of the key-value pairs from the specified source ValueMap into this ValueMap.
Value	putPair(String keyValuePair) Adds an entry to the map.
Value	remove(String key) Removes the key-value pair stored under the specified key.
String	toString()
void	writeTo(BufferedWriter out) Writes the contents of the ValueMap out to the specified stream as text in key=value format.
void	writeTo(File file)
void	writeTo(OutputStream out)
void	writeTo(Writer out)
void	writeToFile(String filename)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ValueMap

public ValueMap(Object lock)

Creates a mapping which synchronizes on the specified lock object.

Parameters:

lock - the object to synchronize on, or null to lock on this instance of ValueMap.

ValueMap

public ValueMap()

Creates a mapping that locks on this instance of ValueMap.

Method Detail

getLockObject

public Object getLockObject()

Returns the object used for synchronization. This may or may not be the instance of ValueMap.

getSize

public int getSize()

Returns the number of entries in this ValueMap.

put

public Value put(String key,
                 Value value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key. If the specified value reference is null, a Value will be created to wrap the null [specifically, ValueFactory.NULL_INSTANCE is stored].

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

put

public Value put(String key,
                 String value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key. If the specified value reference is null, a Value will be created to wrap the null [specifically, ValueFactory.NULL_INSTANCE is stored].

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

put

public Value put(String key,
                 Number value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key. If the specified value reference is null, a Value will be created to wrap the null [specifically, ValueFactory.NULL_INSTANCE is stored].

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

put

public Value put(String key,
                 int value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key.

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

put

public Value put(String key,
                 long value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key.

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

put

public Value put(String key,
                 Object value)
          throws ValueMapException

Stores (and possibly replaces) a key-value pair. If the Object passed in is actually a reference to a Value, then the passed parameter is NOT wrapped in a Value (no double-wrapping). If it is any other type, the ValueFactory is used to create a Value for storing.

Parameters:

key - the name to use for subsequent retrieval of the value. If key is null or a zero-length String, a ValueMapException is thrown. Leading and trailing whitespace on the key is NOT trimmed before storage (using keys with leading and trailing whitespace is highly discouraged anyway).

value - the value mapped to the specified key.

Returns:

old value stored under the key, or plain null if nothing was previously stored.

Throws:

ValueMapException - if key is null or a zero-length String.

putPair

public Value putPair(String keyValuePair)
              throws ValueMapException

Adds an entry to the map. Format of passed parameter is expected to be:

    key=value
 

String supplied is treated like a line in a source file as described in the general class description for this class.

Throws:

ValueMapException

putAll

public void putAll(ValueMap source)

Copies all of the key-value pairs from the specified source ValueMap into this ValueMap. Note that the values themselves are not cloned, but that the references are simply also stored into this ValueMap.

During the copy, the source's lock is held to prohibit modification to the source.

containsKey

public boolean containsKey(String key)

Returns true if a Value is currently stored for the specified key. Any leading or trailing whitespace is first trimmed off of the specified key.

doesNotContainKey

public boolean doesNotContainKey(String key)

Returns true if the specified key is not present in this map. Any leading or trailing whitespace is first trimmed off of the specified key. Equivalent to:

 return !containsKey(key);
 

containsAnyKeyWithPrefix

public boolean containsAnyKeyWithPrefix(String prefix)

Returns true if there are currently any keys that start with the specified prefix. Any leading or trailing whitespace is first trimmed off of the specified prefix.

remove

public Value remove(String key)

Removes the key-value pair stored under the specified key.

Parameters:

key - the key to use for lookup.

Returns:

the Value previously stored, or null if no match was found for the specified key.

get

public Value get(String key)

Retrieves the Value mapped to the specified key or null if there is no such key. This method does not alter the mapping.

Parameters:

key - the key to use for lookup.

Returns:

the Value mapped to the specified key, or null if nothing has been stored under the key.

getOptional

public Value getOptional(String key,
                         Value defaultValue)

Returns the Value mapped to the specified key or if nothing is mapped to the key, defaultValue is returned. This method never returns null and this method does not complain if the specified key is not found.

Parameters:

key - the key to use for lookup.

defaultValue - the Value to return is there is no mapping for the specified key.

Returns:

the Value mapped to the specified key, or defaultValue if nothing has been stored under the key. Never returns null (unless of course, the passed defaultValue is null!).

getRequired

public Value getRequired(String key)
                  throws ValueMapRequiredKeyException

Returns the Value mapped to the specified key or if nothing is mapped to the key, ValueMapRequiredKeyException is thrown. This method never returns null: either a Value is returned, or an exception is thrown if the specified key is not found. The containsKey(String key) method can be used to test before calling this method.

Parameters:

key - the required key to use for lookup.

Returns:

the Value mapped to the specified key. Never returns null.

Throws:

ValueMapRequiredKeyException - if the mapping does not have a value stored for the specified key.

getString

public String getString(String key)
                 throws ValueMapRequiredKeyException

Returns the value stored under the specified required key as a String. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. Equivalent to:

 return getRequired(key).getString();
 

Throws:

ValueMapRequiredKeyException

getString

public String getString(String key,
                        String defaultValue)

Returns the value stored under the specified optional key as a String. If the specified key does not exist, the specified defaultValue is returned. Equivalent to:

 if ( containsKey(key) ) {
     return get(key).getString();
 } else {
     return defaultValue;
 }
 

getObject

public Object getObject(String key,
                        Class type)
                 throws ValueMapRequiredKeyException,
                        ValueException

Returns the value stored under the specified required key as an Object. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the key does exist, but the Value stored under it encapsulates null or an object of a type that can not be cast into the specified type, a ValueException is thrown. Equivalent to:

 return getRequired(key).getObject();
 

Throws:

ValueMapRequiredKeyException

ValueException

getObject

public Object getObject(String key,
                        Class type,
                        Object defaultValue)

Returns the value stored under the specified optional key as an Object. If the specified key does not exist, the specified defaultValue is returned. If the key does exist, but the Value stored under it encapsulates null or an object of a type that can not be cast into the specified type, the specified defaultValue is returned. Equivalent to:

 if ( containsKey(key) ) {
     Value value = get(key);
     if ( value.isType(type) ) {
         return value.getObject();
     }
 }
 return defaultValue;
 

getNumber

public Number getNumber(String key)
                 throws ValueException,
                        ValueMapRequiredKeyException

Returns the value stored under the specified required key as a Number. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a Number, then ValueException is thrown. Equivalent to:

 return getRequired(key).getNumber();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getNumber() method on Value if the looked up value can't be interpreted as a Number.

getNumber

public Number getNumber(String key,
                        Number defaultValue)

Returns the value stored under the specified optional key as a Number. If the specified key does not exist or if the Value found can't be interpreted as a Number, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getNumber(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getBigDecimal

public BigDecimal getBigDecimal(String key)
                         throws ValueException,
                                ValueMapRequiredKeyException

Returns the value stored under the specified required key as a BigDecimal. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a BigDecimal, then ValueException is thrown. Equivalent to:

 return getRequired(key).getBigDecimal();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getBigDecimal() method on Value if the looked up value can't be interpreted as a BigDecimal.

getBigDecimal

public BigDecimal getBigDecimal(String key,
                                BigDecimal defaultValue)

Returns the value stored under the specified optional key as a BigDecimal. If the specified key does not exist or if the Value found can't be interpreted as a BigDecimal, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getBigDecimal(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getLong

public long getLong(String key)
             throws ValueException,
                    ValueMapRequiredKeyException

Returns the value stored under the specified required key as a long. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a long, the ValueException is thrown. Equivalent to:

 return getRequired(key).getLong();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getLong() method on Value if the looked up value can't be interpreted as a long.

getLong

public long getLong(String key,
                    long defaultValue)

Returns the value stored under the specified optional key as a long. If the specified key does not exist or if the Value found can't be interpreted as a long, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getLong(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getLongNumber

public Long getLongNumber(String key)
                   throws ValueException,
                          ValueMapRequiredKeyException

Returns the value stored under the specified required key as a Long. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a Long, the ValueException is thrown. Equivalent to:

 return getRequired(key).getLongNumber();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getLongNumber() method on Value if the looked up value can't be interpreted as a Long.

getLongNumber

public Long getLongNumber(String key,
                          Long defaultValue)

Returns the value stored under the specified optional key as a Long. If the specified key does not exist or if the Value found can't be interpreted as a Long, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getLongNumber(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getInt

public int getInt(String key)
           throws ValueException,
                  ValueMapRequiredKeyException

Returns the value stored under the specified required key as an int. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as an int, the ValueException is thrown. Equivalent to:

 return getRequired(key).getInt();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getInt() method on Value if the looked up value can't be interpreted as an int.

getInt

public int getInt(String key,
                  int defaultValue)

Returns the value stored under the specified optional key as an int. If the specified key does not exist or if the Value found can't be interpreted as an int, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getInt(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getIntegerNumber

public Integer getIntegerNumber(String key)
                         throws ValueException,
                                ValueMapRequiredKeyException

Returns the value stored under the specified required key as an Integer. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as an Integer, the ValueException is thrown. Equivalent to:

 return getRequired(key).getIntegerNumber();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getIntegerNumber() method on Value if the looked up value can't be interpreted as an Integer.

getIntegerNumber

public Integer getIntegerNumber(String key,
                                Integer defaultValue)

Returns the value stored under the specified optional key as an Integer. If the specified key does not exist or if the Value found can't be interpreted as an Integer, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getIntegerNumber(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getDouble

public double getDouble(String key)
                 throws ValueException,
                        ValueMapRequiredKeyException

Returns the value stored under the specified required key as a double. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a double, the ValueException is thrown. Equivalent to:

 return getRequired(key).getDouble();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getDouble() method on Value if the looked up value can't be interpreted as a double.

getDouble

public double getDouble(String key,
                        double defaultValue)

Returns the value stored under the specified optional key as a double. If the specified key does not exist or if the Value found can't be interpreted as a double, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getDouble(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getFloat

public float getFloat(String key)
               throws ValueException,
                      ValueMapRequiredKeyException

Returns the value stored under the specified required key as a float. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a float, the ValueException is thrown. Equivalent to:

 return getRequired(key).getFloat();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getFloat() method on Value if the looked up value can't be interpreted as a float.

getFloat

public float getFloat(String key,
                      float defaultValue)

Returns the value stored under the specified optional key as a float. If the specified key does not exist or if the Value found can't be interpreted as a float, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getFloat(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

isTrue

public boolean isTrue(String key)
               throws ValueMapRequiredKeyException

Returns the value stored under the specified required key as a boolean. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. Equivalent to:

 return getRequired(key).isTrue();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

isTrue

public boolean isTrue(String key,
                      boolean defaultValue)

Returns the value stored under the specified optional key as a boolean. If the specified key does not exist, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return isTrue(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 }
 

getTriState

public TriState getTriState(String key)
                     throws ValueMapRequiredKeyException

Returns the value stored under the specified required key as a TriState. If the specified key does not exist, a ValueMapRequiredKeyException is thrown. Equivalent to:

 return getRequired(key).getTriState();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

getTriState

public TriState getTriState(String key,
                            TriState defaultValue)

Returns the value stored under the specified optional key as a TriState. If the specified key does not exist, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getTriState(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 }
 

getDateTime

public DateTime getDateTime(String key)
                     throws ValueException,
                            ValueMapRequiredKeyException

Returns the value stored under the specified required key as a DateTime (defaulting to the UTC timezone if necessary). If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a DateTime, then ValueException is thrown. Equivalent to:

 return getRequired(key).getDateTime();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getDateTime() method on Value if the looked up value can't be interpreted as a DateTime.

getDateTime

public DateTime getDateTime(String key,
                            DateTime defaultValue)

Returns the value stored under the specified optional key as a DateTime (defaulting to the UTC timezone if necessary). If the specified key does not exist or if the Value found can't be interpreted as a DateTime, then the specified defaultValue is returned. Equivalent to (although it may be implemented more efficiently):

 try {
     return getDateTime(key);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getDateTimeLocal

public DateTime getDateTimeLocal(String key)
                          throws ValueException,
                                 ValueMapRequiredKeyException

Returns the value stored under the specified required key as a DateTime (defaulting to the local VM's timezone if necessary). If the specified key does not exist, a ValueMapRequiredKeyException is thrown. If the Value found can't be interpreted as a DateTime, then ValueException is thrown. Equivalent to:

 return getRequired(key).getDateTimeLocal();
 

Throws:

ValueMapRequiredKeyException - if the key is not present in this mapping.

ValueException - passed along from the getDateTime() method on Value if the looked up value can't be interpreted as a DateTime.

getDateTimeLocal

public DateTime getDateTimeLocal(String key,