org.apache.commons.configuration
Class PropertyConverter

java.lang.Object
  extended by org.apache.commons.configuration.PropertyConverter

public final class PropertyConverter
extends java.lang.Object

A utility class to convert the configuration properties into any type.

Since:
1.1
Version:
$Revision: 662269 $, $Date: 2008-06-01 21:30:02 +0200 (So, 01 Jun 2008) $
Author:
Emmanuel Bourg

Field Summary
private static java.lang.Class[] CONSTR_ARGS
          Constant for the argument classes of the Number constructor that takes a String.
private static java.lang.String HEX_PREFIX
          Constant for the prefix of hex numbers.
private static int HEX_RADIX
          Constant for the radix of hex numbers.
private static java.lang.String INTERNET_ADDRESS_CLASSNAME
          The fully qualified name of javax.mail.internet.InternetAddress
private static float JAVA_VERSION_1_5
          Constant for the Java version 1.5.
(package private) static char LIST_ESC_CHAR
          Constant for the list delimiter as char.
(package private) static java.lang.String LIST_ESCAPE
          Constant for the list delimiter escaping character as string.
 
Constructor Summary
private PropertyConverter()
          Private constructor prevents instances from being created.
 
Method Summary
static java.lang.String escapeDelimiters(java.lang.String s, char delimiter)
          Escapes the delimiters that might be contained in the given string.
static java.lang.Object interpolate(java.lang.Object value, AbstractConfiguration config)
          Performs interpolation of the specified value.
(package private) static boolean isEnum(java.lang.Class cls)
          Calls Class.isEnum() on Java 5, returns false on older JRE.
static java.util.List split(java.lang.String s, char delimiter)
          Split a string on the specified delimiter always trimming the elements.
static java.util.List split(java.lang.String s, char delimiter, boolean trim)
          Split a string on the specified delimiter.
(package private) static java.lang.Object to(java.lang.Class cls, java.lang.Object value, java.lang.Object[] params)
          Converts the specified value to the target class.
static java.math.BigDecimal toBigDecimal(java.lang.Object value)
          Convert the specified object into a BigDecimal.
static java.math.BigInteger toBigInteger(java.lang.Object value)
          Convert the specified object into a BigInteger.
static java.lang.Boolean toBoolean(java.lang.Object value)
          Convert the specified object into a Boolean.
static java.lang.Byte toByte(java.lang.Object value)
          Convert the specified object into a Byte.
static java.util.Calendar toCalendar(java.lang.Object value, java.lang.String format)
          Convert the specified object into a Calendar.
static java.awt.Color toColor(java.lang.Object value)
          Convert the specified object into a Color.
static java.util.Date toDate(java.lang.Object value, java.lang.String format)
          Convert the specified object into a Date.
static java.lang.Double toDouble(java.lang.Object value)
          Convert the specified object into a Double.
(package private) static java.lang.Object toEnum(java.lang.Object value, java.lang.Class cls)
          Convert the specified value into a Java 5 enum.
static java.lang.Float toFloat(java.lang.Object value)
          Convert the specified object into a Float.
(package private) static java.net.InetAddress toInetAddress(java.lang.Object value)
          Convert the specified value into an internet address.
static java.lang.Integer toInteger(java.lang.Object value)
          Convert the specified object into an Integer.
(package private) static java.lang.Object toInternetAddress(java.lang.Object value)
          Convert the specified value into an email address.
static java.util.Iterator toIterator(java.lang.Object value, char delimiter)
          Return an iterator over the simple values of a composite value.
static java.util.Locale toLocale(java.lang.Object value)
          Convert the specified object into a Locale.
static java.lang.Long toLong(java.lang.Object value)
          Convert the specified object into a Long.
(package private) static java.lang.Number toNumber(java.lang.Object value, java.lang.Class targetClass)
          Tries to convert the specified object into a number object.
static java.lang.Short toShort(java.lang.Object value)
          Convert the specified object into a Short.
static java.net.URL toURL(java.lang.Object value)
          Convert the specified object into an URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LIST_ESC_CHAR

static final char LIST_ESC_CHAR
Constant for the list delimiter as char.

See Also:
Constant Field Values

LIST_ESCAPE

static final java.lang.String LIST_ESCAPE
Constant for the list delimiter escaping character as string.


HEX_PREFIX

private static final java.lang.String HEX_PREFIX
Constant for the prefix of hex numbers.

See Also:
Constant Field Values

HEX_RADIX

private static final int HEX_RADIX
Constant for the radix of hex numbers.

See Also:
Constant Field Values

JAVA_VERSION_1_5

private static final float JAVA_VERSION_1_5
Constant for the Java version 1.5.

See Also:
Constant Field Values

CONSTR_ARGS

private static final java.lang.Class[] CONSTR_ARGS
Constant for the argument classes of the Number constructor that takes a String.


INTERNET_ADDRESS_CLASSNAME

private static final java.lang.String INTERNET_ADDRESS_CLASSNAME
The fully qualified name of javax.mail.internet.InternetAddress

See Also:
Constant Field Values
Constructor Detail

PropertyConverter

private PropertyConverter()
Private constructor prevents instances from being created.

Method Detail

to

static java.lang.Object to(java.lang.Class cls,
                           java.lang.Object value,
                           java.lang.Object[] params)
                    throws ConversionException
Converts the specified value to the target class. If the class is a primitive type (Integer.TYPE, Boolean.TYPE, etc) the value returned will use the wrapper type (Integer.class, Boolean.class, etc).

Parameters:
cls - the target class of the converted value
value - the value to convert
params - optional parameters used for the conversion
Returns:
the converted value
Throws:
ConversionException - if the value is not compatible with the requested type
Since:
1.5

toBoolean

public static java.lang.Boolean toBoolean(java.lang.Object value)
                                   throws ConversionException
Convert the specified object into a Boolean. Internally the org.apache.commons.lang.BooleanUtils class from the Commons Lang project is used to perform this conversion. This class accepts some more tokens for the boolean value of true, e.g. yes and on. Please refer to the documentation of this class for more details.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a boolean

toByte

public static java.lang.Byte toByte(java.lang.Object value)
                             throws ConversionException
Convert the specified object into a Byte.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a byte

toShort

public static java.lang.Short toShort(java.lang.Object value)
                               throws ConversionException
Convert the specified object into a Short.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a short

toInteger

public static java.lang.Integer toInteger(java.lang.Object value)
                                   throws ConversionException
Convert the specified object into an Integer.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to an integer

toLong

public static java.lang.Long toLong(java.lang.Object value)
                             throws ConversionException
Convert the specified object into a Long.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Long

toFloat

public static java.lang.Float toFloat(java.lang.Object value)
                               throws ConversionException
Convert the specified object into a Float.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Float

toDouble

public static java.lang.Double toDouble(java.lang.Object value)
                                 throws ConversionException
Convert the specified object into a Double.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Double

toBigInteger

public static java.math.BigInteger toBigInteger(java.lang.Object value)
                                         throws ConversionException
Convert the specified object into a BigInteger.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a BigInteger

toBigDecimal

public static java.math.BigDecimal toBigDecimal(java.lang.Object value)
                                         throws ConversionException
Convert the specified object into a BigDecimal.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a BigDecimal

toNumber

static java.lang.Number toNumber(java.lang.Object value,
                                 java.lang.Class targetClass)
                          throws ConversionException
Tries to convert the specified object into a number object. This method is used by the conversion methods for number types. Note that the return value is not in always of the specified target class, but only if a new object has to be created.

Parameters:
value - the value to be converted (must not be null)
targetClass - the target class of the conversion (must be derived from java.lang.Number)
Returns:
the converted number
Throws:
ConversionException - if the object cannot be converted

toURL

public static java.net.URL toURL(java.lang.Object value)
                          throws ConversionException
Convert the specified object into an URL.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to an URL

toLocale

public static java.util.Locale toLocale(java.lang.Object value)
                                 throws ConversionException
Convert the specified object into a Locale.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Locale

split

public static java.util.List split(java.lang.String s,
                                   char delimiter,
                                   boolean trim)
Split a string on the specified delimiter. To be removed when commons-lang has a better replacement available (Tokenizer?). todo: replace with a commons-lang equivalent

Parameters:
s - the string to split
delimiter - the delimiter
trim - a flag whether the single elements should be trimmed
Returns:
a list with the single tokens

split

public static java.util.List split(java.lang.String s,
                                   char delimiter)
Split a string on the specified delimiter always trimming the elements. This is a shortcut for split(s, delimiter, true).

Parameters:
s - the string to split
delimiter - the delimiter
Returns:
a list with the single tokens

escapeDelimiters

public static java.lang.String escapeDelimiters(java.lang.String s,
                                                char delimiter)
Escapes the delimiters that might be contained in the given string. This method ensures that list delimiter characters that are part of a property's value are correctly escaped when a configuration is saved to a file. Otherwise when loaded again the property will be treated as a list property. A single backslash will also be escaped.

Parameters:
s - the string with the value
delimiter - the list delimiter to use
Returns:
the correctly esaped string

toColor

public static java.awt.Color toColor(java.lang.Object value)
                              throws ConversionException
Convert the specified object into a Color. If the value is a String, the format allowed is (#)?[0-9A-F]{6}([0-9A-F]{2})?. Examples:

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Color

toInetAddress

static java.net.InetAddress toInetAddress(java.lang.Object value)
                                   throws ConversionException
Convert the specified value into an internet address.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a InetAddress
Since:
1.5

toInternetAddress

static java.lang.Object toInternetAddress(java.lang.Object value)
                                   throws ConversionException
Convert the specified value into an email address.

Parameters:
value - the value to convert
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to an email address
Since:
1.5

isEnum

static boolean isEnum(java.lang.Class cls)
Calls Class.isEnum() on Java 5, returns false on older JRE.


toEnum

static java.lang.Object toEnum(java.lang.Object value,
                               java.lang.Class cls)
                        throws ConversionException
Convert the specified value into a Java 5 enum.

Parameters:
value - the value to convert
cls - the type of the enumeration
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to an enumeration
Since:
1.5

toDate

public static java.util.Date toDate(java.lang.Object value,
                                    java.lang.String format)
                             throws ConversionException
Convert the specified object into a Date.

Parameters:
value - the value to convert
format - the DateFormat pattern to parse String values
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Calendar

toCalendar

public static java.util.Calendar toCalendar(java.lang.Object value,
                                            java.lang.String format)
                                     throws ConversionException
Convert the specified object into a Calendar.

Parameters:
value - the value to convert
format - the DateFormat pattern to parse String values
Returns:
the converted value
Throws:
ConversionException - thrown if the value cannot be converted to a Calendar

toIterator

public static java.util.Iterator toIterator(java.lang.Object value,
                                            char delimiter)
Return an iterator over the simple values of a composite value. The value specified is handled depending on its type:

Parameters:
value - the value to "split"
delimiter - the delimiter for String values
Returns:
an iterator for accessing the single values

interpolate

public static java.lang.Object interpolate(java.lang.Object value,
                                           AbstractConfiguration config)
Performs interpolation of the specified value. This method checks if the given value contains variables of the form ${...}. If this is the case, all occurrances will be substituted by their current values.

Parameters:
value - the value to be interpolated
config - the current configuration object
Returns:
the interpolated value