Package org.apache.commons.configuration2

## Class ConfigurationUtils

- java.lang.Object
- - org.apache.commons.configuration2.ConfigurationUtils

-     public final class ConfigurationUtils
      extends Object

  Miscellaneous utility methods for configurations.
  See Also:
    `Utility methods to convert configurations.`

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `append​(Configuration source, Configuration target)` | Append all properties from the source configuration to the target configuration.
    `static void` | `append​(ImmutableConfiguration source, Configuration target)` | Append all properties from the source configuration to the target configuration.
    `static EventSource` | `asEventSource​(Object obj, boolean mockIfUnsupported)` | Casts the specified object to an `EventSource` if possible.
    `static Configuration` | `cloneConfiguration​(Configuration config)` | Clones the given configuration object if this is possible.
    `static Object` | `cloneIfPossible​(Object obj)` | Returns a clone of the passed in object if cloning is supported or the object itself if not.
    `static Synchronizer` | `cloneSynchronizer​(Synchronizer sync)` | Creates a clone of the specified `Synchronizer`.
    `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` | `copy​(ImmutableConfiguration 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 void` | `dump​(ImmutableConfiguration configuration, PrintStream out)` | Dump the configuration key/value mappings to some ouput stream.
    `static void` | `dump​(ImmutableConfiguration configuration, 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 Class<?>` | `loadClass​(String clsName)` | Loads the class with the given name.
    `static Class<?>` | `loadClassNoEx​(String clsName)` | Loads the class with the specified name re-throwing `ClassNotFoundException` exceptions as runtime exceptions.
    `static String` | `toString​(Configuration configuration)` | Get a string representation of the key/value mappings of a configuration.
    `static String` | `toString​(ImmutableConfiguration configuration)` | Get a string representation of the key/value mappings of a configuration.
    `static ImmutableConfiguration` | `unmodifiableConfiguration​(Configuration c)` | Creates an `ImmutableConfiguration` from the given `Configuration` object.
    `static ImmutableHierarchicalConfiguration` | `unmodifiableConfiguration​(HierarchicalConfiguration<?> c)` | Creates an `ImmutableHierarchicalConfiguration` from the given `HierarchicalConfiguration` object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### dump

          public static void dump​(ImmutableConfiguration 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
      Since:
        2.2

    - #### dump

          public static void dump​(Configuration configuration,
                                  PrintStream out)

      Dump the configuration key/value mappings to some ouput stream. This version of the method exists only for backwards compatibility reason.
      Parameters:
        `configuration` - the configuration
        `out` - the output stream to dump the configuration to

    - #### dump

          public static void dump​(ImmutableConfiguration configuration,
                                  PrintWriter out)

      Dump the configuration key/value mappings to some writer.
      Parameters:
        `configuration` - the configuration
        `out` - the writer to dump the configuration to
      Since:
        2.2

    - #### dump

          public static void dump​(Configuration configuration,
                                  PrintWriter out)

      Dump the configuration key/value mappings to some writer. This version of the method exists only for backwards compatibility reason.
      Parameters:
        `configuration` - the configuration
        `out` - the writer to dump the configuration to

    - #### toString

          public static String toString​(ImmutableConfiguration configuration)

      Get a string representation of the key/value mappings of a configuration.
      Parameters:
        `configuration` - the configuration
      Returns:
        a string representation of the configuration
      Since:
        2.2

    - #### toString

          public static String toString​(Configuration configuration)

      Get a string representation of the key/value mappings of a configuration. This version of the method exists only for backwards compatibility reason.
      Parameters:
        `configuration` - the configuration
      Returns:
        a string representation of the configuration

    - #### copy

          public static void copy​(ImmutableConfiguration 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:
        2.2

    - #### 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​(ImmutableConfiguration 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:
        2.2

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

    - #### cloneIfPossible

          public static Object cloneIfPossible​(Object obj)

      Returns a clone of the passed in object if cloning is supported or the object itself if not. This method checks whether the passed in object implements the `Cloneable` interface. If this is the case, the `clone()` method is invoked. Otherwise, the object is directly returned. Errors that might occur during reflection calls are caught and also cause this method to return the original object.
      Parameters:
        `obj` - the object to be cloned
      Returns:
        the result of the cloning attempt
      Since:
        2.0

    - #### cloneSynchronizer

          public static Synchronizer cloneSynchronizer​(Synchronizer sync)

      Creates a clone of the specified `Synchronizer`. This method can be called by `clone()` implementations in configuration classes that also need to copy the `Synchronizer` object. This method can handle some well-known `Synchronizer` implementations directly. For other classes, it uses the following algorithm:
      - If the class of the `Synchronizer` has a standard constructor, a new instance is created using reflection.
      - If this is not possible, it is tried whether the object can be cloned.
      If all attempts fail, a `ConfigurationRuntimeException` is thrown.
      Parameters:
        `sync` - the `Synchronizer` object to be cloned
      Returns:
        the clone of this `Synchronizer`
      Throws:
        `ConfigurationRuntimeException` - if no clone can be created
        `IllegalArgumentException` - if null is passed in

    - #### 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 `EventListener` 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 implement `EventSource`

    - #### loadClass

          public static Class<?> loadClass​(String clsName)
                                    throws ClassNotFoundException

      Loads the class with the given name. This method is used whenever a class has to be loaded dynamically. It first tries the current thread's context class loader. If this fails, the class loader of this class is tried.
      Parameters:
        `clsName` - the name of the class to be loaded
      Returns:
        the loaded class
      Throws:
        `ClassNotFoundException` - if the class cannot be resolved
      Since:
        2.0

    - #### loadClassNoEx

          public static Class<?> loadClassNoEx​(String clsName)

      Loads the class with the specified name re-throwing `ClassNotFoundException` exceptions as runtime exceptions. This method works like `loadClass(String)`. However, checked exceptions are caught and re-thrown as `ConfigurationRuntimeException`.
      Parameters:
        `clsName` - the name of the class to be loaded
      Returns:
        the loaded class
      Throws:
        `ConfigurationRuntimeException` - if the class cannot be resolved
      Since:
        2.0

    - #### unmodifiableConfiguration

          public static ImmutableConfiguration unmodifiableConfiguration​(Configuration c)

      Creates an `ImmutableConfiguration` from the given `Configuration` object. This method creates a proxy object wrapping the original configuration and making it available under the `ImmutableConfiguration` interface. Through this interface the configuration cannot be manipulated. It is also not possible to cast the returned object back to a `Configuration` instance to circumvent this protection.
      Parameters:
        `c` - the `Configuration` to be wrapped (must not be null)
      Returns:
        an `ImmutableConfiguration` view on the specified `Configuration` object
      Throws:
        `NullPointerException` - if the passed in `Configuration` is null
      Since:
        2.0

    - #### unmodifiableConfiguration

          public static ImmutableHierarchicalConfiguration unmodifiableConfiguration​(HierarchicalConfiguration<?> c)

      Creates an `ImmutableHierarchicalConfiguration` from the given `HierarchicalConfiguration` object. This method works exactly like the method with the same name, but it operates on hierarchical configurations.
      Parameters:
        `c` - the `HierarchicalConfiguration` to be wrapped (must not be null)
      Returns:
        an `ImmutableHierarchicalConfiguration` view on the specified `HierarchicalConfiguration` object
      Throws:
        `NullPointerException` - if the passed in `HierarchicalConfiguration` is null
      Since:
        2.0

    - #### asEventSource

          public static EventSource asEventSource​(Object obj,
                                                  boolean mockIfUnsupported)

      Casts the specified object to an `EventSource` if possible. The boolean argument determines the method's behavior if the object does not implement the `EventSource` event: if set to false, a `ConfigurationRuntimeException` is thrown; if set to true, a dummy `EventSource` is returned; on this object all methods can be called, but they do not have any effect.
      Parameters:
        `obj` - the object to be cast as `EventSource`
        `mockIfUnsupported` - a flag whether a mock object should be returned if necessary
      Returns:
        an `EventSource`
      Throws:
        `ConfigurationRuntimeException` - if the object cannot be cast to `EventSource` and the mock flag is false
      Since:
        2.0