edu.emory.mathcs.util
Class PropertyUtils

java.lang.Object
  extended byedu.emory.mathcs.util.PropertyUtils

public class PropertyUtils
extends java.lang.Object

Property and string manipulation and macro expansion utilities. Particularly useful in processing configuration files. Macros enable configuration files to refer to system properties, context-dependent information, etc. Macro expansion routine takes a string and resolves macro occurrences within that string against specified macro templates. Macro references have the following form: $macro_name{parameter}. Upon finding a macro reference, resolver finds macro template for macro_name and uses it to resolve parameter into a value string. For instance, empty macro name is associated by default with a template that resolves system property names into their values. Thus, "${user.dir}" will be replaced by the value of the system property "user.dir", and "${/}" will be replaced by File.separator. As another example, "$trim{text}" will resolve by default to the trimmed text.

Macro references may be nested. However, this version is vulnerable to infinite recursion if expanded macros contain macro references themselves.

Importantly, the set of macro templates is not fixed: users of this class can supply their custom macro templates to the expand(String, Map) method.

Usage examples of macro expansion:


Nested Class Summary
static interface PropertyUtils.Macro
          Macro template that expands the specified parameter in the macro-specific way.
static class PropertyUtils.PropertyExpansionMacro
          Property expansion template that resolves property names into values using specified properties.
 
Field Summary
static PropertyUtils.Macro MACRO_ABSFILE
          Utility macro that converts file path to absolute file path.
static PropertyUtils.Macro MACRO_EXECUTABLE
          Utility macro which converts its argument to the native executable file name.
static PropertyUtils.Macro MACRO_FILE_TO_URL
          Utility macro which converts a file name into a URL.
static PropertyUtils.Macro MACRO_LIBNAME
          Utility macro which converts its argument to the native library file name using System.mapLibraryName(java.lang.String).
static PropertyUtils.Macro MACRO_LOWERCASE
          Utility macro which converts its argument to lower case.
static PropertyUtils.Macro MACRO_SYSTEM_PROPERTY
          Utility macro which resolves system properties specified by name.
static PropertyUtils.Macro MACRO_TRIM
          Utility macro which trims the specified argument, removing white spaces from the beginning and end of it.
static PropertyUtils.Macro MACRO_UPPERCASE
          Utility macro which converts its argument to upper case.
static PropertyUtils.Macro MACRO_URL_TO_FILE
          Utility macro that converts a file URL into a file path.
 
Constructor Summary
PropertyUtils()
           
 
Method Summary
static java.lang.String enumerate(java.util.Properties p)
          Iterates the properties and returns textual representaion
static java.lang.String escapeString(java.lang.String string)
           
static java.lang.String expand(java.lang.String value)
          Expands provided string resolving macro templates using values of default macros.
static java.lang.String expand(java.lang.String value, java.util.Map macros)
          Expands provided string resolving macro templates against supplied macros.
static java.lang.Boolean getBooleanProperty(java.util.Properties props, java.lang.String name)
           
static boolean getBooleanProperty(java.util.Properties props, java.lang.String name, boolean defVal)
           
static java.util.Map getDefaultMacros()
          Returns default macros used by the expand(java.lang.String) method.
static java.lang.Integer getIntegerProperty(java.util.Properties props, java.lang.String name)
           
static int getIntegerProperty(java.util.Properties props, java.lang.String name, int defVal)
           
static java.util.Set getKeysStartingWith(java.util.Properties props, java.lang.String prefix)
           
static java.util.Properties getPropertiesFromStream(java.io.InputStream is)
          Reads properties from the provided input stream.
static java.util.Properties getPropertiesFromString(java.lang.String propertiesString)
          Tokenizes the properties provided as a string and returns plain Properties
static java.lang.String getProperty(java.util.Properties props, java.lang.String name, java.lang.String defVal)
           
static void setBooleanProperty(java.util.Properties props, java.lang.String name, boolean val)
           
static void setIntegerProperty(java.util.Properties props, java.lang.String name, int val)
           
static void setOrRemoveProperty(java.util.Properties props, java.lang.String name, java.lang.String val)
           
static void setProperty(java.util.Properties props, java.lang.String name, java.lang.String val)
           
static java.net.URI[] string2uris(java.lang.String classpath)
           
static java.lang.String unescapeString(java.lang.String string)
           
static java.lang.String uris2string(java.net.URI[] classpath)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MACRO_SYSTEM_PROPERTY

public static final PropertyUtils.Macro MACRO_SYSTEM_PROPERTY
Utility macro which resolves system properties specified by name. The input to the macro has the following syntax:
 name[,defaultValue]
 
For instance: "temp.dir" and "temp.dir,/tmp" are both valid examples. Additionally, two special-purpose names are supported: "/" resolves to File.separator, and ":" resolves to File.pathSeparator. This allows to use shortcuts like "${/}" and "${:}" in configuration files.


MACRO_FILE_TO_URL

public static final PropertyUtils.Macro MACRO_FILE_TO_URL
Utility macro which converts a file name into a URL. This macro properly handles file names containing special characters such as ' ', '#', etc. Note that valid URLs cannot contain spaces and other reserved characters, which means that prepending "file:/" and replacing file separators by slashes is NOT a valid conversion technique. For instance:

$fileurl{C:\Documents and Settings}/file -> file:/C:/Documents%20and%20Settings/file


MACRO_URL_TO_FILE

public static final PropertyUtils.Macro MACRO_URL_TO_FILE
Utility macro that converts a file URL into a file path. The argument must be a properly constructed URI (with no special characters etc).


MACRO_ABSFILE

public static final PropertyUtils.Macro MACRO_ABSFILE
Utility macro that converts file path to absolute file path.


MACRO_TRIM

public static final PropertyUtils.Macro MACRO_TRIM
Utility macro which trims the specified argument, removing white spaces from the beginning and end of it.


MACRO_UPPERCASE

public static final PropertyUtils.Macro MACRO_UPPERCASE
Utility macro which converts its argument to upper case.


MACRO_LOWERCASE

public static final PropertyUtils.Macro MACRO_LOWERCASE
Utility macro which converts its argument to lower case.


MACRO_LIBNAME

public static final PropertyUtils.Macro MACRO_LIBNAME
Utility macro which converts its argument to the native library file name using System.mapLibraryName(java.lang.String).


MACRO_EXECUTABLE

public static final PropertyUtils.Macro MACRO_EXECUTABLE
Utility macro which converts its argument to the native executable file name. For instance, on Windows it will convert "program" to "program.exe".

Constructor Detail

PropertyUtils

public PropertyUtils()
Method Detail

getDefaultMacros

public static java.util.Map getDefaultMacros()
Returns default macros used by the expand(java.lang.String) method. Currently, it includes the following macros: "" (property expansion), "fileurl", "trim", "uppercase", "lowercase", "libname", "executable".

Returns:
default macros used by the expand(java.lang.String) method.

enumerate

public static final java.lang.String enumerate(java.util.Properties p)
Iterates the properties and returns textual representaion

Parameters:
p - input properties
Returns:
properties textual representation

getPropertiesFromString

public static final java.util.Properties getPropertiesFromString(java.lang.String propertiesString)
Tokenizes the properties provided as a string and returns plain Properties

Parameters:
propertiesString - Properties string. Format: key1=value1;key2=value3;key3=value3
Returns:
Properties!

getPropertiesFromStream

public static final java.util.Properties getPropertiesFromStream(java.io.InputStream is)
                                                          throws java.io.IOException
Reads properties from the provided input stream.

Parameters:
is - InputStream to read from
Returns:
properties read
Throws:
java.io.IOException - if I/O error occurs

getKeysStartingWith

public static java.util.Set getKeysStartingWith(java.util.Properties props,
                                                java.lang.String prefix)

escapeString

public static java.lang.String escapeString(java.lang.String string)

unescapeString

public static java.lang.String unescapeString(java.lang.String string)

expand

public static final java.lang.String expand(java.lang.String value)
                                     throws ExpansionException
Expands provided string resolving macro templates using values of default macros.

Throws:
ExpansionException

expand

public static final java.lang.String expand(java.lang.String value,
                                            java.util.Map macros)
                                     throws ExpansionException
Expands provided string resolving macro templates against supplied macros. The macros map should map macro names (strings) to macro objects (implementations of the PropertyUtils.Macro interface).

Throws:
ExpansionException

getProperty

public static java.lang.String getProperty(java.util.Properties props,
                                           java.lang.String name,
                                           java.lang.String defVal)

setProperty

public static void setProperty(java.util.Properties props,
                               java.lang.String name,
                               java.lang.String val)

setOrRemoveProperty

public static void setOrRemoveProperty(java.util.Properties props,
                                       java.lang.String name,
                                       java.lang.String val)

getBooleanProperty

public static java.lang.Boolean getBooleanProperty(java.util.Properties props,
                                                   java.lang.String name)

getBooleanProperty

public static boolean getBooleanProperty(java.util.Properties props,
                                         java.lang.String name,
                                         boolean defVal)

setBooleanProperty

public static void setBooleanProperty(java.util.Properties props,
                                      java.lang.String name,
                                      boolean val)

getIntegerProperty

public static java.lang.Integer getIntegerProperty(java.util.Properties props,
                                                   java.lang.String name)

getIntegerProperty

public static int getIntegerProperty(java.util.Properties props,
                                     java.lang.String name,
                                     int defVal)

setIntegerProperty

public static void setIntegerProperty(java.util.Properties props,
                                      java.lang.String name,
                                      int val)

uris2string

public static final java.lang.String uris2string(java.net.URI[] classpath)

string2uris

public static final java.net.URI[] string2uris(java.lang.String classpath)
                                        throws java.net.URISyntaxException
Throws:
java.net.URISyntaxException