Package org.apache.commons.configuration2

Class ConfigurationUtils

java.lang.Object

org.apache.commons.configuration2.ConfigurationUtils

public final class ConfigurationUtils
extends java.lang.Object

Miscellaneous utility methods for configurations.

Version:

$Id: ConfigurationUtils.java 1785888 2017-03-07 21:05:35Z oheger $

Author:

Herve Quiroz, Emmanuel Bourg

See Also:

Utility methods to convert configurations.

Method Summary

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(java.lang.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 java.lang.Object	cloneIfPossible(java.lang.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, 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	dump(ImmutableConfiguration configuration, java.io.PrintStream out)	Dump the configuration key/value mappings to some ouput stream.
static void	dump(ImmutableConfiguration 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.lang.Class<?>	loadClass(java.lang.String clsName)	Loads the class with the given name.
static java.lang.Class<?>	loadClassNoEx(java.lang.String clsName)	Loads the class with the specified name re-throwing ClassNotFoundException exceptions as runtime exceptions.
static java.lang.String	toString(Configuration configuration)	Get a string representation of the key/value mappings of a configuration.
static java.lang.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,
                        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

Since:

2.2

dump

public static void dump(Configuration configuration,
                        java.io.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,
                        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

Since:

2.2

dump

public static void dump(Configuration configuration,
                        java.io.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 java.lang.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 java.lang.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 java.lang.Object cloneIfPossible(java.lang.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

java.lang.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 java.lang.Class<?> loadClass(java.lang.String clsName)
                                    throws java.lang.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:

java.lang.ClassNotFoundException - if the class cannot be resolved

Since:

2.0

loadClassNoEx

public static java.lang.Class<?> loadClassNoEx(java.lang.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:

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

java.lang.NullPointerException - if the passed in HierarchicalConfiguration is null

Since:

2.0

asEventSource

public static EventSource asEventSource(java.lang.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