org.xins.common.collections

Class MapStringUtils

java.lang.Object

org.xins.common.collections.MapStringUtils

public final class MapStringUtils
extends Object

Utility functions for dealing with Map<String, String> objects.

Since:

XINS 3.0.0

Version:

$Revision: 1.3 $ $Date: 2012/03/15 21:07:39 $

Author:

Ernst de Haan, Anthony Goubard

Method Summary

Methods

Modifier and Type	Method and Description
static Map<String,String>	createMapString(InputStream in) Constructs a Map<String, String> from the specified input stream.
static Map<String,String>	fromProperties(Properties properties) Converts the specified Properties object to a new Map<String, String> object.
static boolean	getBooleanProperty(Map<String,String> properties, String propertyName, boolean fallbackDefault) Gets the property with the specified name and converts it to a boolean.
static int	getIntProperty(Map<String,String> properties, String propertyName) Gets the property with the specified name and converts it to an int.
static String	getRequiredProperty(Map<String,String> properties, String name) Retrieves the specified property and throws a MissingRequiredPropertyException if it is not set.
String	getWithDefault(Map<String,String> properties, String key, String fallbackValue) Retrieves a property with the specified name, falling back to a default value if the property is not set.
static Properties	toProperties(Map<String,String> properties) Converts the specified Map<String, String> object to a new Properties object.
static String	toString(Map<String,String> properties) Returns the String representation of the specified Map<String, String>.
static String	toString(Map<String,String> properties, String valueIfEmpty) Serializes the specified MapMap<String, String> to a String.
static String	toString(Map<String,String> properties, String valueIfEmpty, String prefixIfNotEmpty, String suffix) Returns the String representation for the specified Map<String, String>.
static String	toString(Map<String,String> properties, String valueIfEmpty, String prefixIfNotEmpty, String suffix, int maxValueLength) Returns the String representation for the specified Map<String, String>.

Methods inherited from class java.lang.Object

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

Method Detail

getBooleanProperty

public static boolean getBooleanProperty(Map<String,String> properties,
                         String propertyName,
                         boolean fallbackDefault)
                                  throws IllegalArgumentException,
                                         InvalidPropertyValueException

Gets the property with the specified name and converts it to a boolean.

Parameters:

properties - the set of properties to read from, cannot be null.

propertyName - the name of the property to read, cannot be null.

fallbackDefault - the fallback default value, returned if the value of the property is either null or "" (an empty string).

Returns:

the value of the property.

Throws:

IllegalArgumentException - if properties == null || propertyName == null.

InvalidPropertyValueException - if the value of the property is neither null nor "" (an empty string), nor "true" nor "false".

getIntProperty

public static int getIntProperty(Map<String,String> properties,
                 String propertyName)
                          throws IllegalArgumentException,
                                 MissingRequiredPropertyException,
                                 InvalidPropertyValueException

Gets the property with the specified name and converts it to an int.

Parameters:

properties - the set of properties to read from, cannot be null.

propertyName - the name of the property to read, cannot be null.

Returns:

the value of the property, as an int.

Throws:

IllegalArgumentException - if properties == null || propertyName == null.

MissingRequiredPropertyException - if the specified property is not set, or if it is set to an empty string.

InvalidPropertyValueException - if the conversion to an int failed.

getRequiredProperty

public static String getRequiredProperty(Map<String,String> properties,
                         String name)
                                  throws IllegalArgumentException,
                                         MissingRequiredPropertyException

Retrieves the specified property and throws a MissingRequiredPropertyException if it is not set.

Parameters:

properties - the set of properties to retrieve a specific proeprty from, cannot be null.

name - the name of the property, cannot be null.

Returns:

the value of the property, guaranteed not to be null and guaranteed to contain at least one character.

Throws:

IllegalArgumentException - if properties == null || name == null.

MissingRequiredPropertyException - if the value of the property is either null or an empty string.

getWithDefault

public String getWithDefault(Map<String,String> properties,
                    String key,
                    String fallbackValue)
                      throws IllegalArgumentException

Retrieves a property with the specified name, falling back to a default value if the property is not set.

Parameters:

properties - the set of properties to retrieve a property from, cannot be null.

key - the property key, cannot be null.

fallbackValue - the fallback default value, returned in case the property is not set in properties, cannot be null.

Returns:

the value of the property or the fallback value.

Throws:

IllegalArgumentException - if properties == null || key == null || fallbackValue == null.

createMapString

public static Map<String,String> createMapString(InputStream in)
                                          throws IllegalArgumentException,
                                                 IOException

Constructs a Map<String, String> from the specified input stream.

The parsing done is similar to the parsing done by the Properties.load(InputStream) method. Empty values will be ignored.

Parameters:

in - the input stream to read from, cannot be null.

Returns:

a Map instance that contains all the properties defined in the specified input stream.

Throws:

IllegalArgumentException - if in == null.

IOException - if there was an I/O error while reading from the stream.

toString

public static String toString(Map<String,String> properties)

Returns the String representation of the specified Map<String, String>. For each entry, both the key and the value are encoded using the URL encoding (see URLEncoding). The key and value are separated by a literal equals sign ('='). The entries are separated using an ampersand ('&').

If the value for an entry is either null or an empty string (""), then nothing is added to the String for that entry.

Parameters:

properties - the Map to serialize, cannot be null.

Returns:

the String representation of the specified Map<String, String>.

toString

public static String toString(Map<String,String> properties,
              String valueIfEmpty)

Serializes the specified MapMap<String, String> to a String. For each entry, both the key and the value are encoded using the URL encoding (see URLEncoding). The key and value are separated by a literal equals sign ('='). The entries are separated using an ampersand ('&').

If the value for an entry is either null or an empty string (""), then nothing is added to the String for that entry.

Parameters:

properties - the Map to serialize, can be null.

valueIfEmpty - the string to append to the buffer in case properties == null || properties.isEmpty().

Returns:

the String representation of the Map or the valueIfEmpty, never null. If all parameters are null then an empty String is returned.

toString

public static String toString(Map<String,String> properties,
              String valueIfEmpty,
              String prefixIfNotEmpty,
              String suffix)

Returns the String representation for the specified Map<String, String>.

Parameters:

properties - the Map to construct a String for, or null.

valueIfEmpty - the value to return if the specified set of properties is either null or empty, can be null.

prefixIfNotEmpty - the prefix to add to the value if the Map<String, String> is not empty, can be null.

suffix - the suffix to add to the value, can be null. The suffix will be added even if the Map<String, String> is empty.

Returns:

the String representation of the Map<String, String> with the different artifacts, never null. If all parameters are null then an empty String is returned.

toString

public static String toString(Map<String,String> properties,
              String valueIfEmpty,
              String prefixIfNotEmpty,
              String suffix,
              int maxValueLength)

Returns the String representation for the specified Map<String, String>.

Parameters:

properties - the Map to construct a String for, or null.

valueIfEmpty - the value to return if the specified set of properties is either null or empty, can be null.

prefixIfNotEmpty - the prefix to add to the value if the Map<String, String> is not empty, can be null.

suffix - the suffix to add to the value, can be null. The suffix will be added even if the Mapis empty.

maxValueLength - the maximum of characters to set for the value, if the value is longer than this limit '...' will be added after the limit. If the value is -1, no limit will be set.

Returns:

the String representation of the Map with the different artifacts, never null. If all parameters are null then an empty String is returned.

fromProperties

public static Map<String,String> fromProperties(Properties properties)
                                         throws IllegalArgumentException

Converts the specified Properties object to a new Map<String, String> object.

Parameters:

properties - the Properties object, cannot be null.

Returns:

a new Map object, never null.

Throws:

IllegalArgumentException - if properties == null.

toProperties

public static Properties toProperties(Map<String,String> properties)
                               throws IllegalArgumentException

Converts the specified Map<String, String> object to a new Properties object.

Parameters:

properties - the Map object, cannot be null.

Returns:

a new Properties object, never null.

Throws:

IllegalArgumentException - if properties == null.