## org.apache.commons.configuration
Class ConfigurationUtils

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

    public final class ConfigurationUtils

extends Object

Miscellaneous utility methods for configurations.

Version:
  $Revision: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
Author:
  Herve Quiroz, Oliver Heger, Emmanuel Bourg
See Also:
  `Utility methods to convert configurations.`

Field Summary
`(package private) static String` `PROTOCOL_FILE` Constant for the file URL protocol.
`(package private) static String` `RESOURCE_PATH_SEPARATOR` Constant for the resource path separator.

Method Summary
`static void` `append(Configuration source, Configuration target)` Append all properties from the source configuration to the target configuration.
`(package private) static Object` `clone(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 File` `constructFile(String basePath, 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 void` `copy(Configuration source, Configuration target)` Copy all properties from the source configuration to the target configuration.
`static void` `dump(Configuration configuration, PrintStream out)` Dump the configuration key/value mappings to some ouput stream.
`static void` `dump(Configuration configuration, PrintWriter out)` Dump the configuration key/value mappings to some writer.
`static File` `fileFromURL(URL url)` Tries to convert the specified URL to a file object.
`(package private) 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/
`static File` `getFile(String basePath, String fileName)` Tries to convert the specified base path and file name into a file object.
`(package private) static String` `getFileName(URL url)` Extract the file name from the specified URL.
`static URL` `getURL(String basePath, String file)` Constructs a URL from a base path and a file name.
`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.
`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.
`(package private) static URL` `locateFromClasspath(String resourceName)` Tries to find a resource with the given name in the classpath.
`static String` `toString(Configuration configuration)` Get a string representation of the key/value mappings of a configuration.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PROTOCOL_FILE

    static final String PROTOCOL_FILE

  Constant for the file URL protocol.

  See Also:
    Constant Field Values

### RESOURCE_PATH_SEPARATOR

    static final String RESOURCE_PATH_SEPARATOR

  Constant for the resource path separator.

  See Also:
    Constant Field Values

Method Detail

### 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

### 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

### 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

### 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

### 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

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

### getURL

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

### 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

### 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

### 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

### 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

### 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.

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

### 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

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.