Class ConfigurationUtils
- java.lang.Object
-
- org.apache.commons.configuration2.ConfigurationUtils
-
public final class ConfigurationUtils extends java.lang.Object
Miscellaneous utility methods for configurations.
-
-
Field Summary
Fields Modifier and Type Field Description private static EventSource
DUMMY_EVENT_SOURCE
A dummy event source that is returned byasEventSource()
if a mock object has to be returned.private static java.lang.Class<?>[]
IMMUTABLE_CONFIG_IFCS
An array with interfaces to be implemented by a proxy for an immutable configuration.private static java.lang.Class<?>[]
IMMUTABLE_HIERARCHICAL_CONFIG_IFCS
An array with interfaces to be implemented by a proxy for an immutable hierarchical configuration.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.
-
Constructor Summary
Constructors Modifier Constructor Description private
ConfigurationUtils()
Private constructor.
-
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(java.lang.Object obj, boolean mockIfUnsupported)
Casts the specified object to anEventSource
if possible.(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.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 specifiedSynchronizer
.static HierarchicalConfiguration<?>
convertToHierarchical(Configuration conf)
Converts the passed in configuration to a hierarchical one.static HierarchicalConfiguration<?>
convertToHierarchical(Configuration conf, ExpressionEngine engine)
Converts the passed inConfiguration
object to a hierarchical one using the specifiedExpressionEngine
.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.private static ImmutableConfiguration
createUnmodifiableConfiguration(java.lang.Class<?>[] ifcs, Configuration c)
Helper method for creating a proxy for an unmodifiable 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-throwingClassNotFoundException
exceptions as runtime exceptions.static java.lang.String
toString(Configuration configuration)
Gets a string representation of the key/value mappings of a configuration.static java.lang.String
toString(ImmutableConfiguration configuration)
Gets a string representation of the key/value mappings of a configuration.static ImmutableConfiguration
unmodifiableConfiguration(Configuration c)
Creates anImmutableConfiguration
from the givenConfiguration
object.static ImmutableHierarchicalConfiguration
unmodifiableConfiguration(HierarchicalConfiguration<?> c)
Creates anImmutableHierarchicalConfiguration
from the givenHierarchicalConfiguration
object.
-
-
-
Field Detail
-
METHOD_CLONE
private static final java.lang.String METHOD_CLONE
Constant for the name of the clone() method.- See Also:
- Constant Field Values
-
IMMUTABLE_CONFIG_IFCS
private static final java.lang.Class<?>[] IMMUTABLE_CONFIG_IFCS
An array with interfaces to be implemented by a proxy for an immutable configuration.
-
IMMUTABLE_HIERARCHICAL_CONFIG_IFCS
private static final java.lang.Class<?>[] IMMUTABLE_HIERARCHICAL_CONFIG_IFCS
An array with interfaces to be implemented by a proxy for an immutable hierarchical configuration.
-
DUMMY_EVENT_SOURCE
private static final EventSource DUMMY_EVENT_SOURCE
A dummy event source that is returned byasEventSource()
if a mock object has to be returned. It provides empty dummy implementations for all interface methods.
-
LOG
private static final org.apache.commons.logging.Log LOG
The logger.
-
-
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.
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 thecopy()
method ofAbstractConfiguration
should be used. In a future release this method might become deprecated.- Parameters:
source
- the source configurationtarget
- 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 thecopy()
method ofAbstractConfiguration
should be used. In a future release this method might become deprecated.- Parameters:
source
- the source configurationtarget
- the target configuration- Since:
- 2.2
-
asEventSource
public static EventSource asEventSource(java.lang.Object obj, boolean mockIfUnsupported)
Casts the specified object to anEventSource
if possible. The boolean argument determines the method's behavior if the object does not implement theEventSource
event: if set to false, aConfigurationRuntimeException
is thrown; if set to true, a dummyEventSource
is returned; on this object all methods can be called, but they do not have any effect.- Parameters:
obj
- the object to be cast asEventSource
mockIfUnsupported
- a flag whether a mock object should be returned if necessary- Returns:
- an
EventSource
- Throws:
ConfigurationRuntimeException
- if the object cannot be cast toEventSource
and the mock flag is false- Since:
- 2.0
-
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 theCloneable
interface. If this is the case, theclone()
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
-
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 theCloneable
interface, itsclone()
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 theCloneable
interface. If this is the case, theclone()
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 specifiedSynchronizer
. This method can be called byclone()
implementations in configuration classes that also need to copy theSynchronizer
object. This method can handle some well-knownSynchronizer
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.
ConfigurationRuntimeException
is thrown.- Parameters:
sync
- theSynchronizer
object to be cloned- Returns:
- the clone of this
Synchronizer
- Throws:
ConfigurationRuntimeException
- if no clone can be createdjava.lang.IllegalArgumentException
- if null is passed in
- If the class of the
-
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 inConfiguration
object to a hierarchical one using the specifiedExpressionEngine
. 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 itsExpressionEngine
. 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 theExpressionEngine
; then the default expression engine is used. If the passed in configuration is already hierarchical, it is directly returned. (However, theExpressionEngine
is set if it is not null.) Otherwise all properties are copied into a new hierarchical configuration.- Parameters:
conf
- the configuration to convertengine
- theExpressionEngine
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
-
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 thecopy()
method ofAbstractConfiguration
should be used. In a future release this method might become deprecated.- Parameters:
source
- the source configurationtarget
- the target configuration- Since:
- 1.1
-
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 thecopy()
method ofAbstractConfiguration
should be used. In a future release this method might become deprecated.- Parameters:
source
- the source configurationtarget
- the target configuration- Since:
- 2.2
-
createUnmodifiableConfiguration
private static ImmutableConfiguration createUnmodifiableConfiguration(java.lang.Class<?>[] ifcs, Configuration c)
Helper method for creating a proxy for an unmodifiable configuration. The interfaces the proxy should implement are passed as argument.- Parameters:
ifcs
- an array with the interface classes the proxy must implementc
- the configuration object to be wrapped- Returns:
- a proxy object for an immutable configuration
- Throws:
java.lang.NullPointerException
- if the configuration is null
-
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 configurationout
- 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. This version of the method exists only for backwards compatibility reason.- Parameters:
configuration
- the configurationout
- the writer to dump the configuration to
-
dump
public static void dump(ImmutableConfiguration configuration, java.io.PrintStream out)
Dump the configuration key/value mappings to some ouput stream.- Parameters:
configuration
- the configurationout
- the output stream to dump the configuration to- Since:
- 2.2
-
dump
public static void dump(ImmutableConfiguration configuration, java.io.PrintWriter out)
Dump the configuration key/value mappings to some writer.- Parameters:
configuration
- the configurationout
- the writer to dump the configuration to- Since:
- 2.2
-
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
orJNDIConfiguration
. Per default such errors are simply logged and then ignored. This implementation will register a specialEventListener
that throws a runtime exception (namely aConfigurationRuntimeException
) on each received error event.- Parameters:
src
- the configuration, for which runtime exceptions are to be enabled; this configuration must implementEventSource
-
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-throwingClassNotFoundException
exceptions as runtime exceptions. This method works likeloadClass(String)
. However, checked exceptions are caught and re-thrown asConfigurationRuntimeException
.- 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
-
toString
public static java.lang.String toString(Configuration configuration)
Gets 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
-
toString
public static java.lang.String toString(ImmutableConfiguration configuration)
Gets 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
-
unmodifiableConfiguration
public static ImmutableConfiguration unmodifiableConfiguration(Configuration c)
Creates anImmutableConfiguration
from the givenConfiguration
object. This method creates a proxy object wrapping the original configuration and making it available under theImmutableConfiguration
interface. Through this interface the configuration cannot be manipulated. It is also not possible to cast the returned object back to aConfiguration
instance to circumvent this protection.- Parameters:
c
- theConfiguration
to be wrapped (must not be null)- Returns:
- an
ImmutableConfiguration
view on the specifiedConfiguration
object - Throws:
java.lang.NullPointerException
- if the passed inConfiguration
is null- Since:
- 2.0
-
unmodifiableConfiguration
public static ImmutableHierarchicalConfiguration unmodifiableConfiguration(HierarchicalConfiguration<?> c)
Creates anImmutableHierarchicalConfiguration
from the givenHierarchicalConfiguration
object. This method works exactly like the method with the same name, but it operates on hierarchical configurations.- Parameters:
c
- theHierarchicalConfiguration
to be wrapped (must not be null)- Returns:
- an
ImmutableHierarchicalConfiguration
view on the specifiedHierarchicalConfiguration
object - Throws:
java.lang.NullPointerException
- if the passed inHierarchicalConfiguration
is null- Since:
- 2.0
-
-