org.apache.commons.configuration
Class ConfigurationUtils

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

public final class ConfigurationUtils
extends java.lang.Object

Miscellaneous utility methods for configurations.

Version:
$Revision: 720600 $, $Date: 2008-11-25 22:20:01 +0100 (Di, 25 Nov 2008) $
Author:
Herve Quiroz, Oliver Heger, Emmanuel Bourg
See Also:
Utility methods to convert configurations.

Field Summary
private static float JAVA_1_4
          Constant for Java version 1.4.
private static org.apache.commons.logging.Log log
          The logger.
private static java.lang.String METHOD_CLONE
          Constant for the name of the clone() method.
(package private) static java.lang.String PROTOCOL_FILE
          Constant for the file URL protocol.
(package private) static java.lang.String RESOURCE_PATH_SEPARATOR
          Constant for the resource path separator.
 
Constructor Summary
private ConfigurationUtils()
          Private constructor.
 
Method Summary
static void append(Configuration source, Configuration target)
          Append all properties from the source configuration to the target configuration.
(package private) static java.lang.Object clone(java.lang.Object obj)
          An internally used helper method for cloning objects.
static Configuration cloneConfiguration(Configuration config)
          Clones the given configuration object if this is possible.
(package private) static java.io.File constructFile(java.lang.String basePath, java.lang.String fileName)
          Helper method for constructing a file object from a base path and a file name.
static HierarchicalConfiguration convertToHierarchical(Configuration conf)
          Converts the passed in configuration to a hierarchical one.
static HierarchicalConfiguration convertToHierarchical(Configuration conf, ExpressionEngine engine)
          Converts the passed in Configuration object to a hierarchical one using the specified ExpressionEngine.
static void copy(Configuration source, Configuration target)
          Copy all properties from the source configuration to the target configuration.
static void dump(Configuration configuration, java.io.PrintStream out)
          Dump the configuration key/value mappings to some ouput stream.
static void dump(Configuration configuration, java.io.PrintWriter out)
          Dump the configuration key/value mappings to some writer.
static void enableRuntimeExceptions(Configuration src)
          Enables runtime exceptions for the specified configuration object.
static java.io.File fileFromURL(java.net.URL url)
          Tries to convert the specified URL to a file object.
(package private) static java.lang.String getBasePath(java.net.URL url)
          Return the path without the file name, for example http://xyz.net/foo/bar.xml results in http://xyz.net/foo/
static java.io.File getFile(java.lang.String basePath, java.lang.String fileName)
          Tries to convert the specified base path and file name into a file object.
(package private) static java.lang.String getFileName(java.net.URL url)
          Extract the file name from the specified URL.
static java.net.URL getURL(java.lang.String basePath, java.lang.String file)
          Constructs a URL from a base path and a file name.
static java.net.URL locate(java.lang.String name)
          Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.
static java.net.URL locate(java.lang.String base, java.lang.String name)
          Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.
(package private) static java.net.URL locateFromClasspath(java.lang.String resourceName)
          Tries to find a resource with the given name in the classpath.
static java.lang.String toString(Configuration configuration)
          Get a string representation of the key/value mappings of a configuration.
(package private) static java.net.URL toURL(java.io.File file)
          Convert the specified file into an URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROTOCOL_FILE

static final java.lang.String PROTOCOL_FILE
Constant for the file URL protocol.

See Also:
Constant Field Values

RESOURCE_PATH_SEPARATOR

static final java.lang.String RESOURCE_PATH_SEPARATOR
Constant for the resource path separator.

See Also:
Constant Field Values

METHOD_CLONE

private static final java.lang.String METHOD_CLONE
Constant for the name of the clone() method.

See Also:
Constant Field Values

JAVA_1_4

private static final float JAVA_1_4
Constant for Java version 1.4.

See Also:
Constant Field Values

log

private static org.apache.commons.logging.Log log
The logger.

Constructor Detail

ConfigurationUtils

private ConfigurationUtils()
Private constructor. Prevents instances from being created.

Method Detail

dump

public static void dump(Configuration configuration,
                        java.io.PrintStream out)
Dump the configuration key/value mappings to some ouput stream.

Parameters:
configuration - the configuration
out - the output stream to dump the configuration to

dump

public static void dump(Configuration configuration,
                        java.io.PrintWriter out)
Dump the configuration key/value mappings to some writer.

Parameters:
configuration - the configuration
out - the writer to dump the configuration to

toString

public static java.lang.String toString(Configuration configuration)
Get a string representation of the key/value mappings of a configuration.

Parameters:
configuration - the configuration
Returns:
a string representation of the configuration

copy

public static void copy(Configuration source,
                        Configuration target)

Copy all properties from the source configuration to the target configuration. Properties in the target configuration are replaced with the properties with the same key in the source configuration.

Note: This method is not able to handle some specifics of configurations derived from AbstractConfiguration (e.g. list delimiters). For a full support of all of these features the copy() method of AbstractConfiguration should be used. In a future release this method might become deprecated.

Parameters:
source - the source configuration
target - the target configuration
Since:
1.1

append

public static void append(Configuration source,
                          Configuration target)

Append all properties from the source configuration to the target configuration. Properties in the source configuration are appended to the properties with the same key in the target configuration.

Note: This method is not able to handle some specifics of configurations derived from AbstractConfiguration (e.g. list delimiters). For a full support of all of these features the copy() method of AbstractConfiguration should be used. In a future release this method might become deprecated.

Parameters:
source - the source configuration
target - the target configuration
Since:
1.1

convertToHierarchical

public static HierarchicalConfiguration convertToHierarchical(Configuration conf)
Converts the passed in configuration to a hierarchical one. If the configuration is already hierarchical, it is directly returned. Otherwise all properties are copied into a new hierarchical configuration.

Parameters:
conf - the configuration to convert
Returns:
the new hierarchical configuration (the result is null if and only if the passed in configuration is null)
Since:
1.3

convertToHierarchical

public static HierarchicalConfiguration convertToHierarchical(Configuration conf,
                                                              ExpressionEngine engine)
Converts the passed in Configuration object to a hierarchical one using the specified ExpressionEngine. This conversion works by adding the keys found in the configuration to a newly created hierarchical configuration. When adding new keys to a hierarchical configuration the keys are interpreted by its ExpressionEngine. If they contain special characters (e.g. brackets) that are treated in a special way by the default expression engine, it may be necessary using a specific engine that can deal with such characters. Otherwise null can be passed in for the ExpressionEngine; then the default expression engine is used. If the passed in configuration is already hierarchical, it is directly returned. (However, the ExpressionEngine is set if it is not null.) Otherwise all properties are copied into a new hierarchical configuration.

Parameters:
conf - the configuration to convert
engine - the ExpressionEngine for the hierarchical configuration or null for the default
Returns:
the new hierarchical configuration (the result is null if and only if the passed in configuration is null)
Since:
1.6

cloneConfiguration

public static Configuration cloneConfiguration(Configuration config)
                                        throws ConfigurationRuntimeException
Clones the given configuration object if this is possible. If the passed in configuration object implements the Cloneable interface, its clone() method will be invoked. Otherwise an exception will be thrown.

Parameters:
config - the configuration object to be cloned (can be null)
Returns:
the cloned configuration (null if the argument was null, too)
Throws:
ConfigurationRuntimeException - if cloning is not supported for this object
Since:
1.3

clone

static java.lang.Object clone(java.lang.Object obj)
                       throws java.lang.CloneNotSupportedException
An internally used helper method for cloning objects. This implementation is not very sophisticated nor efficient. Maybe it can be replaced by an implementation from Commons Lang later. The method checks whether the passed in object implements the Cloneable interface. If this is the case, the clone() method is invoked by reflection. Errors that occur during the cloning process are re-thrown as runtime exceptions.

Parameters:
obj - the object to be cloned
Returns:
the cloned object
Throws:
java.lang.CloneNotSupportedException - if the object cannot be cloned

getURL

public static java.net.URL getURL(java.lang.String basePath,
                                  java.lang.String file)
                           throws java.net.MalformedURLException
Constructs a URL from a base path and a file name. The file name can be absolute, relative or a full URL. If necessary the base path URL is applied.

Parameters:
basePath - the base path URL (can be null)
file - the file name
Returns:
the resulting URL
Throws:
java.net.MalformedURLException - if URLs are invalid

constructFile

static java.io.File constructFile(java.lang.String basePath,
                                  java.lang.String fileName)
Helper method for constructing a file object from a base path and a file name. This method is called if the base path passed to getURL() does not seem to be a valid URL.

Parameters:
basePath - the base path
fileName - the file name
Returns:
the resulting file

locate

public static java.net.URL locate(java.lang.String name)
Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.

Parameters:
name - the name of the resource
Returns:
the location of the resource

locate

public static java.net.URL locate(java.lang.String base,
                                  java.lang.String name)
Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.

Parameters:
base - the base path of the resource
name - the name of the resource
Returns:
the location of the resource

locateFromClasspath

static java.net.URL locateFromClasspath(java.lang.String resourceName)
Tries to find a resource with the given name in the classpath.

Parameters:
resourceName - the name of the resource
Returns:
the URL to the found resource or null if the resource cannot be found

getBasePath

static java.lang.String getBasePath(java.net.URL url)
Return the path without the file name, for example http://xyz.net/foo/bar.xml results in http://xyz.net/foo/

Parameters:
url - the URL from which to extract the path
Returns:
the path component of the passed in URL

getFileName

static java.lang.String getFileName(java.net.URL url)
Extract the file name from the specified URL.

Parameters:
url - the URL from which to extract the file name
Returns:
the extracted file name

getFile

public static java.io.File getFile(java.lang.String basePath,
                                   java.lang.String fileName)
Tries to convert the specified base path and file name into a file object. This method is called e.g. by the save() methods of file based configurations. The parameter strings can be relative files, absolute files and URLs as well. This implementation checks first whether the passed in file name is absolute. If this is the case, it is returned. Otherwise further checks are performed whether the base path and file name can be combined to a valid URL or a valid file name. Note: The test if the passed in file name is absolute is performed using java.io.File.isAbsolute(). If the file name starts with a slash, this method will return true on Unix, but false on Windows. So to ensure correct behavior for relative file names on all platforms you should never let relative paths start with a slash. E.g. in a configuration definition file do not use something like that:
 <properties fileName="/subdir/my.properties"/>
 
Under Windows this path would be resolved relative to the configuration definition file. Under Unix this would be treated as an absolute path name.

Parameters:
basePath - the base path
fileName - the file name
Returns:
the file object (null if no file can be obtained)

fileFromURL

public static java.io.File fileFromURL(java.net.URL url)
Tries to convert the specified URL to a file object. If this fails, null is returned.

Parameters:
url - the URL
Returns:
the resulting file object

toURL

static java.net.URL toURL(java.io.File file)
                   throws java.net.MalformedURLException
Convert the specified file into an URL. This method is equivalent to file.toURI().toURL() on Java 1.4 and above, and equivalent to file.toURL() on Java 1.3. This is to work around a bug in the JDK preventing the transformation of a file into an URL if the file name contains a '#' character. See the issue CONFIGURATION-300 for more details.

Parameters:
file - the file to be converted into an URL
Throws:
java.net.MalformedURLException

enableRuntimeExceptions

public static void enableRuntimeExceptions(Configuration src)
Enables runtime exceptions for the specified configuration object. This method can be used for configuration implementations that may face errors on normal property access, e.g. DatabaseConfiguration or JNDIConfiguration. Per default such errors are simply logged and then ignored. This implementation will register a special ConfigurationErrorListener that throws a runtime exception (namely a ConfigurationRuntimeException) on each received error event.

Parameters:
src - the configuration, for which runtime exceptions are to be enabled; this configuration must be derived from EventSource