com.norconex.commons.lang.map
Class Properties

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.TreeMap<String,List<String>>
          extended by com.norconex.commons.lang.map.Properties
All Implemented Interfaces:
Serializable, Cloneable, Map<String,List<String>>, NavigableMap<String,List<String>>, SortedMap<String,List<String>>
Direct Known Subclasses:
QueryString

public class Properties
extends TreeMap<String,List<String>>

This class is a enhanced version of Properties that enforces the use of String keys and values, but offers many convenience methods for storing and retrieving multiple values of different types (e.g. Integer, Locale, File, etc). While it does not extend Properties, it offers similar load and store method and can be used as a replacement for it in many cases (e.g. works great with configuration files).

It can also be used as a string-based multi-value map with helpful methods. This works great in a few scenarios, like easily accessing or manipulating URL query string values. It extends TreeMap so that keys are always sorted, either by the String natural order, or by supplying a comparator.

To insert values, there are set methods and add methods. The set methods will replace any value(s) already present under the given key. It is essentially the same behavior as Map.put(Object, Object). The add method will add the new value(s) to the list of already existing ones (if any).

Upon encountering a problem in parsing the data to its target format, a PropertiesException is thrown.

Author:
Pascal Essiembre
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
 
Field Summary
static String DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER
          Default delimiter when storing/loading multi-values to/from .properties files.
 
Constructor Summary
Properties()
          Create a new instance with case-sensitive keys.
Properties(boolean caseSensitiveKeys)
          Creates a new instance.
Properties(Map<?,?> defaults)
          Creates a new Properties initializing it with values from the given Map.
Properties(Map<?,?> defaults, boolean caseSensitiveKeys)
          Creates a new Properties initializing it with values from the given Map.
 
Method Summary
 void addBigDecimal(String key, BigDecimal... values)
           
 void addBoolean(String key, boolean... values)
           
 void addClass(String key, Class<?>... values)
           
 void addDate(String key, Date... values)
           
 void addDouble(String key, double... values)
           
 void addFile(String key, File... values)
           
 void addFloat(String key, float... values)
           
 void addInt(String key, int... values)
           
 void addLocale(String key, Locale... values)
           
 void addLong(String key, long... values)
           
 void addString(String key, String... values)
          Adds one or multiple string values.
 List<String> get(Object key)
           
 BigDecimal getBigDecimal(String key)
           
 BigDecimal getBigDecimal(String key, BigDecimal defaultValue)
           
 List<BigDecimal> getBigDecimals(String key)
           
 boolean getBoolean(String key)
           
 boolean getBoolean(String key, boolean defaultValue)
           
 List<Boolean> getBooleans(String key)
           
 Class<?> getClass(String key)
          Gets a class, assuming key value is a fully qualified class name available in the classloader.
 Class<?> getClass(String key, Class<?> defaultValue)
          Gets a class, assuming key value is a fully qualified class name available in the classloader.
 List<Class<?>> getClasses(String key)
           
 Date getDate(String key)
           
 Date getDate(String key, Date defaultValue)
           
 List<Date> getDates(String key)
           
 double getDouble(String key)
           
 double getDouble(String key, double defaultValue)
           
 List<Double> getDoubles(String key)
           
 File getFile(String key)
          Gets a file, assuming key value is a file system path.
 File getFile(String key, File defaultValue)
          Gets a file, assuming key value is a file system path.
 List<File> getFiles(String key)
           
 float getFloat(String key)
           
 float getFloat(String key, float defaultValue)
           
 List<Float> getFloats(String key)
           
 int getInt(String key)
           
 int getInt(String key, int defaultValue)
           
 List<Integer> getInts(String key)
           
 Locale getLocale(String key)
           
 Locale getLocale(String key, Locale defaultValue)
           
 List<Locale> getLocales(String key)
           
 long getLong(String key)
           
 long getLong(String key, long defaultValue)
           
 List<Long> getLongs(String key)
           
 String getString(String key)
           
 String getString(String key, String defaultValue)
           
 List<String> getStrings(String key)
           
 void load(InputStream inStream)
          Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.
 void load(InputStream inStream, String delimiter)
          Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.
 void load(Reader reader)
          Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.
 void load(Reader reader, String delimiter)
          Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.
 void loadFromString(String str)
          Reads a property list (key and element pairs) from the input string.
 void loadFromXML(InputStream in)
          Loads all of the properties represented by the XML document on the specified input stream into this instance.
 void loadFromXML(InputStream in, String delimiter)
          Loads all of the properties represented by the XML document on the specified input stream into this instance.
 List<String> remove(Object key)
           
 void setBigDecimal(String key, BigDecimal... values)
           
 void setBigDecimal(String key, BigDecimal value)
           
 void setBoolean(String key, boolean... values)
           
 void setBoolean(String key, boolean value)
           
 void setClass(String key, Class<?>... values)
           
 void setDate(String key, Date... values)
           
 void setDouble(String key, double... values)
           
 void setFile(String key, File... values)
           
 void setFloat(String key, float... values)
           
 void setInt(String key, int... values)
           
 void setLocale(String key, Locale... values)
           
 void setLong(String key, long... values)
           
 void setString(String key, String... values)
          Sets one or multiple string values.
 void store(OutputStream out, String comments)
          Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(InputStream) method.
 void store(OutputStream out, String comments, String delimiter)
          Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(InputStream, String) method.
 void store(Writer writer, String comments)
          Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(Reader) method.
 void store(Writer writer, String comments, String delimiter)
          Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(Reader, String) method.
 String storeToString(String comments)
          Writes this property list (key and element pairs) in this Properties table to the output stream in a format suitable for loading into a Properties table using the load method.
 void storeToXML(OutputStream os, String comment)
          Emits an XML document representing all of the properties contained in this Map, using the specified encoding.
 void storeToXML(OutputStream os, String comment, String encoding)
          Emits an XML document representing all of the properties contained in this Map, using the specified encoding.
 void storeToXML(OutputStream os, String comment, String encoding, String delimiter)
          Emits an XML document representing all of the properties contained in this Map, using the specified encoding.
 
Methods inherited from class java.util.TreeMap
ceilingEntry, ceilingKey, clear, clone, comparator, containsKey, containsValue, descendingKeySet, descendingMap, entrySet, firstEntry, firstKey, floorEntry, floorKey, headMap, headMap, higherEntry, higherKey, keySet, lastEntry, lastKey, lowerEntry, lowerKey, navigableKeySet, pollFirstEntry, pollLastEntry, put, putAll, size, subMap, subMap, tailMap, tailMap, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, isEmpty, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode, isEmpty
 

Field Detail

DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER

public static final String DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER
Default delimiter when storing/loading multi-values to/from .properties files.

See Also:
Constant Field Values
Constructor Detail

Properties

public Properties()
Create a new instance with case-sensitive keys.

See Also:
TreeMap.TreeMap()

Properties

public Properties(boolean caseSensitiveKeys)
Creates a new instance.

Parameters:
caseSensitiveKeys - getter methods taking a key as well as {remove(Object) will return all combined values or remove all keys where keys are equal, ignoring case, to the key supplied.
See Also:
TreeMap.TreeMap()

Properties

public Properties(Map<?,?> defaults)

Creates a new Properties initializing it with values from the given Map. ObjectUtils.toString(Object) is used to convert to convert keys and values to strings, with exception of values being arrays or collections. In such case, the entry is considered a mult-value one and each value will be converted to individual strings. null keys are ignored.

null values are converted to an empty string.

Changes to this instance won't be reflected in the given Map. Keys are case-sensitive.

Parameters:
defaults - the default values

Properties

public Properties(Map<?,?> defaults,
                  boolean caseSensitiveKeys)

Creates a new Properties initializing it with values from the given Map. ObjectUtils.toString(Object) is used to convert to convert keys and values to strings, with exception of values being arrays or collections. In such case, the entry is considered a mult-value one and each value will be converted to individual strings. null keys are ignored.

null values are converted to an empty string.

Changes to this instance won't be reflected in the given Map.

Parameters:
defaults - the default values
caseSensitiveKeys - getter methods taking a key as well as {remove(Object) will return all combined values or remove all keys where keys are equal, ignoring case, to the key supplied.
Method Detail

storeToString

public String storeToString(String comments)
                     throws IOException
Writes this property list (key and element pairs) in this Properties table to the output stream in a format suitable for loading into a Properties table using the load method. Otherwise, the same considerations as store(OutputStream, String) apply.

Parameters:
comments - a description of the property list.
Returns:
the properties as string
Throws:
IOException - problem storing to string

store

public void store(Writer writer,
                  String comments)
           throws IOException
Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(Reader) method. If a key only has one value, then this method behavior is the exact same as the store(Writer, String) method. Keys with multi-values are joined into a single string, using the default delimiter: DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER

Parameters:
writer - an output character stream writer.
comments - a description of the property list.
Throws:
IOException
See Also:
store(Writer, String)

store

public void store(Writer writer,
                  String comments,
                  String delimiter)
           throws IOException
Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(Reader, String) method. If a key only has one value, then this method behavior is the exact same as the store(Writer, String) method. Keys with multi-values are joined into a single string, using the delimiter provided.

Parameters:
writer - an output character stream writer.
comments - a description of the property list.
delimiter - string to used as a separator when joining multiple values for the same key.
Throws:
IOException
See Also:
store(Writer, String)

store

public void store(OutputStream out,
                  String comments)
           throws IOException
Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(InputStream) method. If a key only has one value, then this method behavior is the exact same as the store(OutputStream, String) method. Keys with multi-values are joined into a single string, using the default delimiter: DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER

Parameters:
out - an output stream.
comments - a description of the property list.
Throws:
IOException
See Also:
store(OutputStream, String)

store

public void store(OutputStream out,
                  String comments,
                  String delimiter)
           throws IOException
Writes this Map (key and element pairs) to the output character stream in a format suitable for using the load(InputStream, String) method. If a key only has one value, then this method behavior is the exact same as the store(OutputStream, String) method. Keys with multi-values are joined into a single string, using the delimiter provided.

Parameters:
out - an output stream.
comments - a description of the property list.
delimiter - delimiter string to used as a separator when joining multiple values for the same key.
Throws:
IOException
See Also:
store(OutputStream, String)

storeToXML

public void storeToXML(OutputStream os,
                       String comment)
                throws IOException
Emits an XML document representing all of the properties contained in this Map, using the specified encoding. If a key only has one value, then this method behavior is the exact same as the storeToXML(OutputStream, String, String) method, where the character encoding is "UTF-8". Keys with multi-values are joined into a single string, using the default delimiter: DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER

Parameters:
os - the output stream on which to emit the XML document.
comment - a description of the property list, or null if no comment is desired.
Throws:
IOException
See Also:
storeToXML(OutputStream, String, String)

storeToXML

public void storeToXML(OutputStream os,
                       String comment,
                       String encoding)
                throws IOException
Emits an XML document representing all of the properties contained in this Map, using the specified encoding. If a key only has one value, then this method behavior is the exact same as the storeToXML(OutputStream, String, String) method. Keys with multi-values are joined into a single string, using the default delimiter: DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER

Parameters:
os - the output stream on which to emit the XML document.
comment - a description of the property list, or null if no comment is desired.
encoding - character encoding
Throws:
IOException
See Also:
storeToXML(OutputStream, String, String)

storeToXML

public void storeToXML(OutputStream os,
                       String comment,
                       String encoding,
                       String delimiter)
                throws IOException
Emits an XML document representing all of the properties contained in this Map, using the specified encoding. If a key only has one value, then this method behavior is the exact same as the storeToXML(OutputStream, String, String) method. Keys with multi-values are joined into a single string, using the delimiter provided.

Parameters:
os - the output stream on which to emit the XML document.
comment - a description of the property list, or null if no comment is desired.
encoding - character encoding
delimiter - delimiter string to used as a separator when joining multiple values for the same key.
Throws:
IOException
See Also:
storeToXML(OutputStream, String, String)

load

public void load(Reader reader)
          throws IOException
Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format. If a key was stored with multiple values using a delimiter, this, method will split these values appropriately assuming the delimiter is DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER If the key value was stored as a single value, then this method behavior is the exact same as the load(Reader) method.

Parameters:
reader - the input character stream.
Throws:
IOException
See Also:
load(Reader)

load

public void load(Reader reader,
                 String delimiter)
          throws IOException
Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format. If a key was stored with multiple values using a delimiter, this method will split these values appropriately provided the supplied delimiter is the same. If the key value was stored as a single value, then this method behavior is the exact same as the load(Reader) method.

Parameters:
reader - the input character stream.
delimiter - delimiter string to used to parse a multi value key.
Throws:
IOException
See Also:
load(Reader)

load

public void load(InputStream inStream)
          throws IOException
Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format. If a key was stored with multiple values using a delimiter, this, method will split these values appropriately assuming the delimiter is DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER If the key value was stored as a single value, then this method behavior is the exact same as the load(InputStream) method.

Parameters:
inStream - the input stream.
Throws:
IOException
See Also:
load(InputStream)

load

public void load(InputStream inStream,
                 String delimiter)
          throws IOException
Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format. If a key was stored with multiple values using a delimiter, this method will split these values appropriately provided the supplied delimiter is the same. If the key value was stored as a single value, then this method behavior is the exact same as the load(InputStream) method.

Parameters:
inStream - the input stream.
delimiter - delimiter string to used to parse a multi value key.
Throws:
IOException
See Also:
load(InputStream)

loadFromXML

public void loadFromXML(InputStream in)
                 throws IOException
Loads all of the properties represented by the XML document on the specified input stream into this instance. If a key was stored with multiple values using a delimiter, method will split these values appropriately assuming the delimiter is DEFAULT_PROPERTIES_MULTIVALUE_DELIMITER If the key value was stored as a single value, then this method behavior is the exact same as the loadFromXML(InputStream) method.

Parameters:
in - in the input stream from which to read the XML document.
Throws:
IOException

loadFromXML

public void loadFromXML(InputStream in,
                        String delimiter)
                 throws IOException
Loads all of the properties represented by the XML document on the specified input stream into this instance. If a key was stored with multiple values using a delimiter, this method will split these values appropriately provided the supplied delimiter is the same. If the key value was stored as a single value, then this method behavior is the exact same as the loadFromXML(InputStream) method.

Parameters:
in - in the input stream from which to read the XML document.
delimiter - delimiter string to used to parse a multi value key.
Throws:
IOException

loadFromString

public void loadFromString(String str)
                    throws IOException
Reads a property list (key and element pairs) from the input string. Otherwise, the same considerations as load(InputStream) apply.

Parameters:
str - the string to load
Throws:
IOException - problem loading string

getString

public final String getString(String key)

getString

public final String getString(String key,
                              String defaultValue)

getStrings

public final List<String> getStrings(String key)

setString

public final void setString(String key,
                            String... values)
Sets one or multiple string values. Setting a string with a null value will set a blank string.

Parameters:
key - the key of the value to set
values - the values to set

addString

public final void addString(String key,
                            String... values)
Adds one or multiple string values. Setting a string with a null value will set a blank string.

Parameters:
key - the key of the value to set
values - the values to set

getInt

public final int getInt(String key)

getInt

public final int getInt(String key,
                        int defaultValue)

getInts

public final List<Integer> getInts(String key)

setInt

public final void setInt(String key,
                         int... values)

addInt

public final void addInt(String key,
                         int... values)

getDouble

public final double getDouble(String key)

getDouble

public final double getDouble(String key,
                              double defaultValue)

getDoubles

public final List<Double> getDoubles(String key)

setDouble

public final void setDouble(String key,
                            double... values)

addDouble

public final void addDouble(String key,
                            double... values)

getLong

public final long getLong(String key)

getLong

public final long getLong(String key,
                          long defaultValue)

getLongs

public final List<Long> getLongs(String key)

setLong

public final void setLong(String key,
                          long... values)

addLong

public final void addLong(String key,
                          long... values)

getFloat

public final float getFloat(String key)

getFloat

public final float getFloat(String key,
                            float defaultValue)

getFloats

public final List<Float> getFloats(String key)

setFloat

public final void setFloat(String key,
                           float... values)

addFloat

public final void addFloat(String key,
                           float... values)

getBigDecimal

public final BigDecimal getBigDecimal(String key)

getBigDecimal

public final BigDecimal getBigDecimal(String key,
                                      BigDecimal defaultValue)

setBigDecimal

public final void setBigDecimal(String key,
                                BigDecimal value)

getBigDecimals

public final List<BigDecimal> getBigDecimals(String key)

setBigDecimal

public final void setBigDecimal(String key,
                                BigDecimal... values)

addBigDecimal

public final void addBigDecimal(String key,
                                BigDecimal... values)

getDate

public final Date getDate(String key)

getDate

public final Date getDate(String key,
                          Date defaultValue)

getDates

public final List<Date> getDates(String key)

setDate

public final void setDate(String key,
                          Date... values)

addDate

public final void addDate(String key,
                          Date... values)

getBoolean

public final boolean getBoolean(String key)

getBoolean

public final boolean getBoolean(String key,
                                boolean defaultValue)

setBoolean

public final void setBoolean(String key,
                             boolean value)

getBooleans

public final List<Boolean> getBooleans(String key)

setBoolean

public final void setBoolean(String key,
                             boolean... values)

addBoolean

public final void addBoolean(String key,
                             boolean... values)

getLocale

public final Locale getLocale(String key)

getLocale

public final Locale getLocale(String key,
                              Locale defaultValue)

getLocales

public final List<Locale> getLocales(String key)

setLocale

public final void setLocale(String key,
                            Locale... values)

addLocale

public final void addLocale(String key,
                            Locale... values)

getFile

public final File getFile(String key)
Gets a file, assuming key value is a file system path.

Parameters:
key - properties key

getFile

public final File getFile(String key,
                          File defaultValue)
Gets a file, assuming key value is a file system path.

Parameters:
key - properties key
defaultValue - default file being returned if no file has been defined for the given key in the properties.

getFiles

public final List<File> getFiles(String key)

setFile

public final void setFile(String key,
                          File... values)

addFile

public final void addFile(String key,
                          File... values)

getClass

public final Class<?> getClass(String key)
Gets a class, assuming key value is a fully qualified class name available in the classloader.

Parameters:
key - properties key

getClass

public final Class<?> getClass(String key,
                               Class<?> defaultValue)
Gets a class, assuming key value is a fully qualified class name available in the classloader.

Parameters:
key - properties key
defaultValue - default file being returned if no class has been defined for the given key in the properties.

getClasses

public final List<Class<?>> getClasses(String key)

setClass

public final void setClass(String key,
                           Class<?>... values)

addClass

public final void addClass(String key,
                           Class<?>... values)

get

public final List<String> get(Object key)
Specified by:
get in interface Map<String,List<String>>
Overrides:
get in class TreeMap<String,List<String>>

remove

public final List<String> remove(Object key)
Specified by:
remove in interface Map<String,List<String>>
Overrides:
remove in class TreeMap<String,List<String>>


Copyright © 2008-2013 Norconex Inc.. All Rights Reserved.