com.programix.value
Class ValueMap

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

All Implemented Interfaces:

ThreadSafe, Serializable

public class ValueMap
extends Object
implements Serializable, ThreadSafe

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.
Double	getDoubleNumber(String key) Returns the value stored under the specified required key as an Double.
Double	getDoubleNumber(String key, Double defaultValue) Returns the value stored under the specified optional key as an 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.
Float	getFloatNumber(String key) Returns the value stored under the specified required key as an Float.
Float	getFloatNumber(String key, Float defaultValue) Returns the value stored under the specified optional key as an 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<String,Value>	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.
<T> T	getObject(String key, Class<T> type) Returns the value stored under the specified required key as an Object.
<T> T	getObject(String key, Class<T> type, T 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() Returns a single-line textual approximation of values currently stored.
String	toStringMultiLine() Returns a multi-line textual approximation of values currently stored as they would be written by writeTo(BufferedWriter).
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 <T> T getObject(String key,
                       Class<T> 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 <T> T getObject(String key,
                       Class<T> type,
                       T 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;
 }
 

getDoubleNumber

public Double getDoubleNumber(String key)
                       throws ValueException,
                              ValueMapRequiredKeyException

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

 return getRequired(key).getDoubleNumber();
 

Throws:

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

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

getDoubleNumber

public Double getDoubleNumber(String key,
                              Double defaultValue)

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

 try {
     return getDoubleNumber(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;
 }
 

getFloatNumber

public Float getFloatNumber(String key)
                     throws ValueException,
                            ValueMapRequiredKeyException

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

 return getRequired(key).getFloatNumber();
 

Throws:

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

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

getFloatNumber

public Float getFloatNumber(String key,
                            Float defaultValue)

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

 try {
     return getFloatNumber(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,
                                 DateTime defaultValue)

Returns the value stored under the specified optional key as a DateTime (defaulting to the local VM's 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;
 }
 

getDateTime

public DateTime getDateTime(String key,
                            TimeZone tz)
                     throws ValueException,
                            ValueMapRequiredKeyException

Returns the value stored under the specified required key as a DateTime (defaulting to the specified 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(tz);
 

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,
                            TimeZone tz,
                            DateTime defaultValue)

Returns the value stored under the specified optional key as a DateTime (defaulting to the specified 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, tz);
 } catch ( ValueMapRequiredKeyException x ) {
     return defaultValue;
 } catch ( ValueException x ) {
     return defaultValue;
 }
 

getPlainDate

public PlainDate getPlainDate(String key)
                       throws ValueException,
                              ValueMapRequiredKeyException

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

 return getRequired(key).getPlainDate();
 

Throws:

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

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

getPlainDate

public PlainDate getPlainDate(String key,
                              PlainDate defaultValue)

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

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

getBytes

public byte[] getBytes(String key)
                throws ValueMapRequiredKeyException

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

 return getRequired(key).getBytes();
 

Throws:

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

getBytes

public byte[] getBytes(String key,
                       byte[] defaultValue)

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

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

getBytesAsStream

public InputStream getBytesAsStream(String key)
                             throws ValueMapRequiredKeyException

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

 return getRequired(key).getBytesAsStream();
 

Throws:

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

getBytesAsStream

public InputStream getBytesAsStream(String key,
                                    InputStream defaultValue)

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

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

getOrderedKeys

public String[] getOrderedKeys()

Returns all the keys in the map in insertion order.

getMapView

public Map<String,Value> getMapView()

Returns a read-only view of all the mappings as a Map.

getProperties

public Properties getProperties()

Returns a copy of all the mappings as a Properties. The Properties object returned is a snapshot of the mappings as of the time this method is called—there is no linkage between this ValueMap and the newly created Properties object. All keys in this map are already restricted to being only String's. All values in this map are interpreted using getString(key) to create the String to be placed into the Properties instance returned.

getNestedValueMap

public 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). The Value's are shared (not copied) as most implementations of Value are immutable (if you have mutable Value's in your map you may need to be careful). If no keys match the prefix, then an empty ValueMap (with zero entries) is returned.

For example, consider starting with the following file to populate a ValueMap:

 solar.system.Mercury.diameter=0.38
 solar.system.Venus.diameter=0.95
 solar.system.Earth.diameter=1.00
 solar.system.Mars.diameter=0.53
 solar.system.Jupiter.diameter=11.2
 solar.system.Mercury.mass=0.06
 solar.system.Venus.mass=0.82
 solar.system.Earth.mass=1.00
 solar.system.Mars.mass=0.11
 solar.system.Jupiter.mass=318
 solar.system.Mercury.moon.count=0
 solar.system.Venus.moon.count=0
 solar.system.Earth.moon.count=1
 solar.system.Mars.moon.count=2
 solar.system.Jupiter.moon.count=63
 country.usa.full.name=United States
 country.usa.capital=Washington, DC
 country.can.full.name=Canada
 country.can.capital=Ottawa
 country.gbr.full.name=United Kingdom
 country.gbr.capital=London
 country.swe.full.name=Sweden
 country.swe.capital=Stockholm
 country.nor.full.name=Norway
 country.nor.capital=Oslo
 country.che.full.name=Switzerland
 country.che.capital=Bern
 

The new ValueMap created by:

 ValueMap countryMap = map.getNestedValueMap("country.");
 

would be:

 usa.full.name=United States
 usa.capital=Washington, DC
 can.full.name=Canada
 can.capital=Ottawa
 gbr.full.name=United Kingdom
 gbr.capital=London
 swe.full.name=Sweden
 swe.capital=Stockholm
 nor.full.name=Norway
 nor.capital=Oslo
 che.full.name=Switzerland
 che.capital=Bern
 

from that map, if someone did this:

 ValueMap usaMap = countryMap.getNestedValueMap("usa.");
 

the result would be:

 full.name=United States
 capital=Washington, DC
 

Going back to the original, the new ValueMap created by:

 ValueMap solarMap = map.getNestedValueMap("solar.system.");
 

would be:

 Mercury.diameter=0.38
 Venus.diameter=0.95
 Earth.diameter=1.00
 Mars.diameter=0.53
 Jupiter.diameter=11.2
 Mercury.mass=0.06
 Venus.mass=0.82
 Earth.mass=1.00
 Mars.mass=0.11
 Jupiter.mass=318
 Mercury.moon.count=0
 Venus.moon.count=0
 Earth.moon.count=1
 Mars.moon.count=2
 Jupiter.moon.count=63
 

from that map, if someone did this:

 ValueMap marsMap = solarMap.getNestedValueMap("Mars.");
 

the result would be:

 diameter=0.53
 mass=0.11
 moon.count=2
 

Parameters:

keyPrefix - specifies the subset of keys to match. Matched keys must start with this prefix and then must have at least one remaining character.

toString

public String toString()

Returns a single-line textual approximation of values currently stored. To get in a multi-line format, call toStringMultiLine(). The returned string looks something like:

   "{key1=value1, key2=value2, key3=, key4=value4}"
 

Overrides:

toString in class Object

toStringMultiLine

public String toStringMultiLine()

Returns a multi-line textual approximation of values currently stored as they would be written by writeTo(BufferedWriter). To get in a single-line format, call toString().

writeTo

public void writeTo(BufferedWriter out)
             throws ValueMapException

Writes the contents of the ValueMap out to the specified stream as text in key=value format. Note that not all values can be properly represented in String form. Note also that the stream is flushed and closed by this method.

Parameters:

out - destination for the key=value pairs.

Throws:

ValueMapException - if there are any troubles writing out to the stream.

writeTo

public void writeTo(Writer out)
             throws ValueMapException

Throws:

ValueMapException

writeTo

public void writeTo(OutputStream out)
             throws ValueMapException

Throws:

ValueMapException

writeTo

public void writeTo(File file)
             throws ValueMapException

Throws:

ValueMapException

writeToFile

public void writeToFile(String filename)
                 throws ValueMapException

Throws:

ValueMapException

createFrom

public static ValueMap createFrom(Map<?,?> map)

Copies the entries from the specified Map into a new ValueMap. Each key in the map is passed to the String.valueOf(Object) method to generate the string-based key needed by ValueMap. Each value is simply passed to create(Object obj) method on ValueFactory.

Parameters:

map - source of key/value pairs

Returns:

a new instance with copies of the data in the map.

Throws:

ValueMapException

createFrom

public static ValueMap createFrom(BufferedReader in)
                           throws ValueMapException

Creates a mapping from the specified data source. Stream is read until the end, at which point the stream is closed. Even on an exception condition, the stream is closed.

Parameters:

in - source of data; always closed by this method.

Returns:

a new mapping derived from the data in the stream.

Throws:

ValueMapException - if there are problems reading from the stream, or if an line it improperly formatted.

createFrom

public static ValueMap createFrom(Reader rawIn)
                           throws ValueMapException

Creates a mapping from the specified data source. Stream is read until the end, at which point the stream is closed. Even on an exception condition, the stream is closed.

Parameters:

rawIn - source of data; always closed by this method.

Returns:

a new mapping derived from the data in the stream.

Throws:

ValueMapException - if there are problems reading from the stream, or if an line it improperly formatted.

createFrom

public static ValueMap createFrom(InputStream rawIn)
                           throws ValueMapException

Throws:

ValueMapException

createFrom

public static ValueMap createFrom(File source)
                           throws ValueMapException

Throws:

ValueMapException

createFromFile

public static ValueMap createFromFile(String sourceFilename)
                               throws ValueMapException

Throws:

ValueMapException

createFrom

public static ValueMap createFrom(URL source)
                           throws ValueMapException

Throws:

ValueMapException

createFromResource

public static ValueMap createFromResource(String resourceLocation,
                                          Class<?> searchStartPoint)
                                   throws ValueMapException

Throws:

ValueMapException

createFromResource

public static ValueMap createFromResource(String resourceLocation)
                                   throws ValueMapException

Throws:

ValueMapException