Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.emory.mathcs.util
Class PropertyUtils

    java.lang.Object
      edu.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:

- `"${h2o.home}"` - the directory pointed to by the system property "h2o.home"
- `"${h2o.home}${/}services"` - the "services" subdirectory in the directory pointed to by the system property "h2o.home"
- `"$fileurl{${h2o.home}${/}services}"` - the "services" subdirectory in the directory pointed to by the system property "h2o.home", converted to an URL
- `"$fileurl{${h2o.home,${user.home}${/}.h2o}${/}services}"` - the "services" subdirectory in the directory pointed to by the system property "h2o.home" if set; otherwise, "services" directory in the ".h2o" subdirectory in the default user dir; converted to an URL

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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD