org.apache.commons.configuration

Class ConfigurationUtils

public final class ConfigurationUtils extends Object

Miscellaneous utility methods for configurations.

Version: $Revision: 503227 $, $Date: 2007-02-03 17:19:15 +0100 (Sa, 03 Feb 2007) $

Author: Herve Quiroz Oliver Heger Emmanuel Bourg

See Also: Utility methods to convert configurations.

Field Summary
static Loglog
The logger.
static StringMETHOD_CLONE
Constant for the name of the clone() method.
static StringPROTOCOL_FILE
Constant for the file URL protocol.
static StringRESOURCE_PATH_SEPARATOR
Constant for the resource path separator.
Constructor Summary
ConfigurationUtils()
Private constructor.
Method Summary
static voidappend(Configuration source, Configuration target)
Append all properties from the source configuration to the target configuration.
static Objectclone(Object obj)
An internally used helper method for cloning objects.
static ConfigurationcloneConfiguration(Configuration config)
Clones the given configuration object if this is possible.
static FileconstructFile(String basePath, String fileName)
Helper method for constructing a file object from a base path and a file name.
static HierarchicalConfigurationconvertToHierarchical(Configuration conf)
Converts the passed in configuration to a hierarchical one.
static voidcopy(Configuration source, Configuration target)
Copy all properties from the source configuration to the target configuration.
static voiddump(Configuration configuration, PrintStream out)
Dump the configuration key/value mappings to some ouput stream.
static voiddump(Configuration configuration, PrintWriter out)
Dump the configuration key/value mappings to some writer.
static voidenableRuntimeExceptions(Configuration src)
Enables runtime exceptions for the specified configuration object.
static FilefileFromURL(URL url)
Tries to convert the specified URL to a file object.
static StringgetBasePath(URL url)
Return the path without the file name, for example http://xyz.net/foo/bar.xml results in http://xyz.net/foo/
static FilegetFile(String basePath, String fileName)
Tries to convert the specified base path and file name into a file object.
static StringgetFileName(URL url)
Extract the file name from the specified URL.
static URLgetURL(String basePath, String file)
Constructs a URL from a base path and a file name.
static URLlocate(String name)
Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.
static URLlocate(String base, String name)
Return the location of the specified resource by searching the user home directory, the current classpath and the system classpath.
static URLlocateFromClasspath(String resourceName)
Tries to find a resource with the given name in the classpath.
static StringtoString(Configuration configuration)
Get a string representation of the key/value mappings of a configuration.

Field Detail

log

private static Log log
The logger.

METHOD_CLONE

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

PROTOCOL_FILE

static final String PROTOCOL_FILE
Constant for the file URL protocol.

RESOURCE_PATH_SEPARATOR

static final String RESOURCE_PATH_SEPARATOR
Constant for the resource path separator.

Constructor Detail

ConfigurationUtils

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

Method Detail

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.

Parameters: source the source configuration target the target configuration

Since: 1.1

clone

static Object clone(Object obj)
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: CloneNotSupportedException if the object cannot be cloned

cloneConfiguration

public static Configuration cloneConfiguration(Configuration config)
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

constructFile

static File constructFile(String basePath, 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

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

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 won't work well on hierarchical configurations because it is not able to copy information about the properties' structure. So when dealing with hierarchical configuration objects their clone() methods should be used.

Parameters: source the source configuration target the target configuration

Since: 1.1

dump

public static void dump(Configuration configuration, 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, PrintWriter out)
Dump the configuration key/value mappings to some writer.

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

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

fileFromURL

public static File fileFromURL(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

getBasePath

static String getBasePath(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

getFile

public static File getFile(String basePath, 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)

getFileName

static String getFileName(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

getURL

public static URL getURL(String basePath, String file)
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: MalformedURLException if URLs are invalid

locate

public static URL locate(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 URL locate(String base, 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 URL locateFromClasspath(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

toString

public static 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