org.xins.common.collections
Class PropertyReaderUtils

java.lang.Object
  extended byorg.xins.common.collections.PropertyReaderUtils

public final class PropertyReaderUtils
extends Object

Utility functions for dealing with PropertyReader objects.

Since:
XINS 1.0.0
Version:
$Revision: 1.60 $ $Date: 2008/07/04 10:22:50 $
Author:
Ernst de Haan
See Also:
PropertyReader

Field Summary
static PropertyReader EMPTY_PROPERTY_READER
          An empty and unmodifiable PropertyReader instance.
 
Method Summary
static PropertyReader createPropertyReader(InputStream in)
          Constructs a PropertyReader from the specified input stream.
static boolean equals(PropertyReader pr, Object toCompare)
          Compares a PropertyReader instance with another object for equality.
static boolean getBooleanProperty(PropertyReader properties, String propertyName, boolean fallbackDefault)
          Gets the property with the specified name and converts it to a boolean.
static int getIntProperty(PropertyReader properties, String propertyName)
          Gets the property with the specified name and converts it to an int.
static String getRequiredProperty(PropertyReader properties, String name)
          Retrieves the specified property and throws a MissingRequiredPropertyException if it is not set.
 String getWithDefault(PropertyReader 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 int hashCode(PropertyReader pr)
          Computes a hash code value for the specified PropertyReader object.
static void serialize(PropertyReader properties, FastStringBuffer buffer, String valueIfEmpty)
          Deprecated. since XINS 2.0, use toString(PropertyReader, String)
static String toString(PropertyReader properties)
          Returns the String representation of the specified PropertyReader.
static String toString(PropertyReader properties, String valueIfEmpty)
          Serializes the specified PropertyReader to a String.
static String toString(PropertyReader properties, String valueIfEmpty, String prefixIfNotEmpty, String suffix)
          Returns the String representation for the specified PropertyReader.
static String toString(PropertyReader properties, String valueIfEmpty, String prefixIfNotEmpty, String suffix, int maxValueLength)
          Returns the String representation for the specified PropertyReader.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_PROPERTY_READER

public static final PropertyReader EMPTY_PROPERTY_READER
An empty and unmodifiable PropertyReader instance. This field is not null.

Since:
XINS 1.1.0
Method Detail

getBooleanProperty

public static boolean getBooleanProperty(PropertyReader 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(PropertyReader 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(PropertyReader 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(PropertyReader 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.
Since:
XINS 2.1

createPropertyReader

public static PropertyReader createPropertyReader(InputStream in)
                                           throws IllegalArgumentException,
                                                  IOException
Constructs a PropertyReader 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 PropertyReader 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.

serialize

public static void serialize(PropertyReader properties,
                             FastStringBuffer buffer,
                             String valueIfEmpty)
                      throws IllegalArgumentException
Deprecated. since XINS 2.0, use toString(PropertyReader, String)

Serializes the specified PropertyReader to a FastStringBuffer. 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 buffer for that entry.

Parameters:
properties - the PropertyReader to serialize, can be null.
buffer - the buffer to write the serialized data to, cannot be null.
valueIfEmpty - the string to append to the buffer in case properties == null || properties.size() == 0; if this argument is null, however, then nothing will be appended in the mentioned case.
Throws:
IllegalArgumentException - if properties == null || buffer == null.

toString

public static String toString(PropertyReader properties)
Returns the String representation of the specified PropertyReader. 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 PropertyReader to serialize, cannot be null.
Returns:
the String representation of the specified PropertyReader.
Since:
XINS 2.0.

toString

public static String toString(PropertyReader properties,
                              String valueIfEmpty)
Serializes the specified PropertyReader 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 PropertyReader to serialize, can be null.
valueIfEmpty - the string to append to the buffer in case properties == null || properties.size() == 0.
Returns:
the String representation of the PropertyReader or the valueIfEmpty, never null. If all parameters are null then an empty String is returned.

toString

public static String toString(PropertyReader properties,
                              String valueIfEmpty,
                              String prefixIfNotEmpty,
                              String suffix)
Returns the String representation for the specified PropertyReader.

Parameters:
properties - the PropertyReader 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 PropertyReader 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 PropertyReaderis empty.
Returns:
the String representation of the PropertyReader with the different artifacts, never null. If all parameters are null then an empty String is returned.
Since:
XINS 2.0

toString

public static String toString(PropertyReader properties,
                              String valueIfEmpty,
                              String prefixIfNotEmpty,
                              String suffix,
                              int maxValueLength)
Returns the String representation for the specified PropertyReader.

Parameters:
properties - the PropertyReader 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 PropertyReader 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 PropertyReaderis 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 PropertyReader with the different artifacts, never null. If all parameters are null then an empty String is returned.
Since:
XINS 2.0

equals

public static final boolean equals(PropertyReader pr,
                                   Object toCompare)
Compares a PropertyReader instance with another object for equality.

Parameters:
pr - the PropertyReader, can be null.
toCompare - the object to compare the PropertyReader with, can be null.
Returns:
true if the objects are considered to be equal, false if they are considered different.
Since:
XINS 2.1

hashCode

public static final int hashCode(PropertyReader pr)
                          throws NullPointerException
Computes a hash code value for the specified PropertyReader object.

Parameters:
pr - the PropertyReader instance to compute a hash code value for, cannot be null.
Returns:
the hash code value.
Throws:
NullPointerException - if pr == null.
Since:
XINS 2.1


See http://www.xins.org/.