/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.configuration2;

import java.io.PrintStream;
import java.io.PrintWriter;
import java.io.StringWriter;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.Iterator;

import org.apache.commons.configuration2.event.ConfigurationErrorEvent;
import org.apache.commons.configuration2.event.Event;
import org.apache.commons.configuration2.event.EventListener;
import org.apache.commons.configuration2.event.EventSource;
import org.apache.commons.configuration2.event.EventType;
import org.apache.commons.configuration2.ex.ConfigurationRuntimeException;
import org.apache.commons.configuration2.sync.NoOpSynchronizer;
import org.apache.commons.configuration2.sync.Synchronizer;
import org.apache.commons.configuration2.tree.ExpressionEngine;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

Miscellaneous utility methods for configurations.
See Also:
Utility methods to convert configurations./**
 * Miscellaneous utility methods for configurations.
 *
 * @see ConfigurationConverter Utility methods to convert configurations.
 *
 */
public final class ConfigurationUtils
{
    
Constant for the name of the clone() method./** Constant for the name of the clone() method.*/
    private static final String METHOD_CLONE = "clone";

    
An array with interfaces to be implemented by a proxy for an immutable
configuration.
/**
     * An array with interfaces to be implemented by a proxy for an immutable
     * configuration.
     */
    private static final Class<?>[] IMMUTABLE_CONFIG_IFCS = {
        ImmutableConfiguration.class
    };

    
An array with interfaces to be implemented by a proxy for an immutable
hierarchical configuration.
/**
     * An array with interfaces to be implemented by a proxy for an immutable
     * hierarchical configuration.
     */
    private static final Class<?>[] IMMUTABLE_HIERARCHICAL_CONFIG_IFCS = {
        ImmutableHierarchicalConfiguration.class
    };
    
A dummy event source that is returned by asEventSource() if a mock object has to be returned. It provides empty dummy implementations for all interface methods. /**
     * A dummy event source that is returned by {@code asEventSource()} if a
     * mock object has to be returned. It provides empty dummy implementations
     * for all interface methods.
     */
    private static final EventSource DUMMY_EVENT_SOURCE = new EventSource()
    {

        @Override
        public <T extends Event> void addEventListener(final EventType<T> eventType,
                final EventListener<? super T> listener)
        {
        }

        @Override
        public <T extends Event> boolean removeEventListener(
                final EventType<T> eventType, final EventListener<? super T> listener)
        {
            return false;
        }
    };

    
The logger./** The logger.*/
    private static final Log LOG = LogFactory.getLog(ConfigurationUtils.class);

    
Private constructor. Prevents instances from being created.
/**
     * Private constructor. Prevents instances from being created.
     */
    private ConfigurationUtils()
    {
        // to prevent instantiation...
    }

    
Dump the configuration key/value mappings to some ouput stream.
Params:
configuration – the configuration
out – the output stream to dump the configuration to
Since:
2.2/**
     * Dump the configuration key/value mappings to some ouput stream.
     *
     * @param configuration the configuration
     * @param out the output stream to dump the configuration to
     * @since 2.2
     */
    public static void dump(final ImmutableConfiguration configuration, final PrintStream out)
    {
        dump(configuration, new PrintWriter(out));
    }

    
Dump the configuration key/value mappings to some ouput stream.
This version of the method exists only for backwards compatibility reason.
Params:
configuration – the configuration
out – the output stream to dump the configuration to/**
     * Dump the configuration key/value mappings to some ouput stream.
     * This version of the method exists only for backwards compatibility reason.
     *
     * @param configuration the configuration
     * @param out the output stream to dump the configuration to
     */
    public static void dump(final Configuration configuration, final PrintStream out)
    {
        dump((ImmutableConfiguration) configuration, out);
    }

    
Dump the configuration key/value mappings to some writer.
Params:
configuration – the configuration
out – the writer to dump the configuration to
Since:
2.2/**
     * Dump the configuration key/value mappings to some writer.
     *
     * @param configuration the configuration
     * @param out the writer to dump the configuration to
     * @since 2.2
     */
    public static void dump(final ImmutableConfiguration configuration, final PrintWriter out)
    {
        for (final Iterator<String> keys = configuration.getKeys(); keys.hasNext();)
        {
            final String key = keys.next();
            final Object value = configuration.getProperty(key);
            out.print(key);
            out.print("=");
            out.print(value);

            if (keys.hasNext())
            {
                out.println();
            }
        }

        out.flush();
    }

    
Dump the configuration key/value mappings to some writer.
This version of the method exists only for backwards compatibility reason.
Params:
configuration – the configuration
out – the writer to dump the configuration to/**
     * Dump the configuration key/value mappings to some writer.
     * This version of the method exists only for backwards compatibility reason.
     *
     * @param configuration the configuration
     * @param out the writer to dump the configuration to
     */
    public static void dump(final Configuration configuration, final PrintWriter out)
    {
        dump((ImmutableConfiguration) configuration, out);
    }

    
Get a string representation of the key/value mappings of a
configuration.
Params:
configuration – the configuration
Returns:
a string representation of the configuration
Since:
2.2/**
     * Get a string representation of the key/value mappings of a
     * configuration.
     *
     * @param configuration the configuration
     * @return a string representation of the configuration
     * @since 2.2
     */
    public static String toString(final ImmutableConfiguration configuration)
    {
        final StringWriter writer = new StringWriter();
        dump(configuration, new PrintWriter(writer));
        return writer.toString();
    }

    
Get a string representation of the key/value mappings of a
configuration.
This version of the method exists only for backwards compatibility reason.
Params:
configuration – the configuration
Returns:
a string representation of the configuration/**
     * Get a string representation of the key/value mappings of a
     * configuration.
     * This version of the method exists only for backwards compatibility reason.
     *
     * @param configuration the configuration
     * @return a string representation of the configuration
     */
    public static String toString(final Configuration configuration)
    {
        return toString((ImmutableConfiguration) configuration);
    }

    
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.
Params:
source – the source configuration
target – the target configuration
Since:
2.2/**
     * <p>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.</p>
     * <p><em>Note:</em> This method is not able to handle some specifics of
     * configurations derived from {@code AbstractConfiguration} (e.g.
     * list delimiters). For a full support of all of these features the
     * {@code copy()} method of {@code AbstractConfiguration} should
     * be used. In a future release this method might become deprecated.</p>
     *
     * @param source the source configuration
     * @param target the target configuration
     * @since 2.2
     */
    public static void copy(final ImmutableConfiguration source, final Configuration target)
    {
        for (final Iterator<String> keys = source.getKeys(); keys.hasNext();)
        {
            final String key = keys.next();
            target.setProperty(key, source.getProperty(key));
        }
    }

    
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.
Params:
source – the source configuration
target – the target configuration
Since:
1.1/**
     * <p>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.</p>
     * <p><em>Note:</em> This method is not able to handle some specifics of
     * configurations derived from {@code AbstractConfiguration} (e.g.
     * list delimiters). For a full support of all of these features the
     * {@code copy()} method of {@code AbstractConfiguration} should
     * be used. In a future release this method might become deprecated.</p>
     *
     * @param source the source configuration
     * @param target the target configuration
     * @since 1.1
     */
    public static void copy(final Configuration source, final Configuration target)
    {
        copy((ImmutableConfiguration) source, 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.
Params:
source – the source configuration
target – the target configuration
Since:
2.2/**
     * <p>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.</p>
     * <p><em>Note:</em> This method is not able to handle some specifics of
     * configurations derived from {@code AbstractConfiguration} (e.g.
     * list delimiters). For a full support of all of these features the
     * {@code copy()} method of {@code AbstractConfiguration} should
     * be used. In a future release this method might become deprecated.</p>
     *
     * @param source the source configuration
     * @param target the target configuration
     * @since 2.2
     */
    public static void append(final ImmutableConfiguration source, final Configuration target)
    {
        for (final Iterator<String> keys = source.getKeys(); keys.hasNext();)
        {
            final String key = keys.next();
            target.addProperty(key, source.getProperty(key));
        }
    }

    
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.
Params:
source – the source configuration
target – the target configuration
Since:
1.1/**
     * <p>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.</p>
     * <p><em>Note:</em> This method is not able to handle some specifics of
     * configurations derived from {@code AbstractConfiguration} (e.g.
     * list delimiters). For a full support of all of these features the
     * {@code copy()} method of {@code AbstractConfiguration} should
     * be used. In a future release this method might become deprecated.</p>
     *
     * @param source the source configuration
     * @param target the target configuration
     * @since 1.1
     */
    public static void append(final Configuration source, final Configuration target)
    {
        append((ImmutableConfiguration) source, target);
    }

    
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.
Params:
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/**
     * 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.
     *
     * @param conf the configuration to convert
     * @return the new hierarchical configuration (the result is <b>null</b> if
     * and only if the passed in configuration is <b>null</b>)
     * @since 1.3
     */
    public static HierarchicalConfiguration<?> convertToHierarchical(
            final Configuration conf)
    {
        return convertToHierarchical(conf, null);
    }

    
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.
Params:
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/**
     * Converts the passed in {@code Configuration} object to a
     * hierarchical one using the specified {@code 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
     * {@code 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 <b>null</b> can be passed in for the
     * {@code ExpressionEngine}; then the default expression engine is
     * used. If the passed in configuration is already hierarchical, it is
     * directly returned. (However, the {@code ExpressionEngine} is set if
     * it is not <b>null</b>.) Otherwise all properties are copied into a new
     * hierarchical configuration.
     *
     * @param conf the configuration to convert
     * @param engine the {@code ExpressionEngine} for the hierarchical
     *        configuration or <b>null</b> for the default
     * @return the new hierarchical configuration (the result is <b>null</b> if
     *         and only if the passed in configuration is <b>null</b>)
     * @since 1.6
     */
    public static HierarchicalConfiguration<?> convertToHierarchical(
            final Configuration conf, final ExpressionEngine engine)
    {
        if (conf == null)
        {
            return null;
        }

        if (conf instanceof HierarchicalConfiguration)
        {
            final HierarchicalConfiguration<?> hc = (HierarchicalConfiguration<?>) conf;
            if (engine != null)
            {
                hc.setExpressionEngine(engine);
            }

            return hc;
        }
        final BaseHierarchicalConfiguration hc = new BaseHierarchicalConfiguration();
        if (engine != null)
        {
            hc.setExpressionEngine(engine);
        }

        // Per default, a DisabledListDelimiterHandler is set.
        // So list delimiters in property values are not an issue.
        hc.copy(conf);
        return hc;
    }

    
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. 
Params:
config – the configuration object to be cloned (can be null)
Throws:
ConfigurationRuntimeException – if cloning is not supported for
this object
Returns:
the cloned configuration (null if the argument was
null, too)
Since:
1.3/**
     * Clones the given configuration object if this is possible. If the passed
     * in configuration object implements the {@code Cloneable}
     * interface, its {@code clone()} method will be invoked. Otherwise
     * an exception will be thrown.
     *
     * @param config the configuration object to be cloned (can be <b>null</b>)
     * @return the cloned configuration (<b>null</b> if the argument was
     * <b>null</b>, too)
     * @throws ConfigurationRuntimeException if cloning is not supported for
     * this object
     * @since 1.3
     */
    public static Configuration cloneConfiguration(final Configuration config)
            throws ConfigurationRuntimeException
    {
        if (config == null)
        {
            return null;
        }
        try
        {
            return (Configuration) clone(config);
        }
        catch (final CloneNotSupportedException cnex)
        {
            throw new ConfigurationRuntimeException(cnex);
        }
    }

    
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. 
Params:
obj – the object to be cloned
Returns:
the result of the cloning attempt
Since:
2.0/**
     * 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 {@code Cloneable} interface. If this is the case, the
     * {@code 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.
     *
     * @param obj the object to be cloned
     * @return the result of the cloning attempt
     * @since 2.0
     */
    public static Object cloneIfPossible(final Object obj)
    {
        try
        {
            return clone(obj);
        }
        catch (final Exception ex)
        {
            return 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. 
Params:
obj – the object to be cloned
Throws:
CloneNotSupportedException – if the object cannot be cloned
Returns:
the cloned object/**
     * 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 {@code Cloneable} interface. If
     * this is the case, the {@code clone()} method is invoked by
     * reflection. Errors that occur during the cloning process are re-thrown as
     * runtime exceptions.
     *
     * @param obj the object to be cloned
     * @return the cloned object
     * @throws CloneNotSupportedException if the object cannot be cloned
     */
    static Object clone(final Object obj) throws CloneNotSupportedException
    {
        if (obj instanceof Cloneable)
        {
            try
            {
                final Method m = obj.getClass().getMethod(METHOD_CLONE);
                return m.invoke(obj);
            }
            catch (final NoSuchMethodException nmex)
            {
                throw new CloneNotSupportedException(
                        "No clone() method found for class"
                                + obj.getClass().getName());
            }
            catch (final IllegalAccessException iaex)
            {
                throw new ConfigurationRuntimeException(iaex);
            }
            catch (final InvocationTargetException itex)
            {
                throw new ConfigurationRuntimeException(itex);
            }
        }
        throw new CloneNotSupportedException(obj.getClass().getName()
                + " does not implement Cloneable");
    }

    
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. 
Params:
sync – the Synchronizer object to be cloned
Throws:
ConfigurationRuntimeException – if no clone can be created
IllegalArgumentException – if null is passed in
Returns:
the clone of this Synchronizer/**
     * Creates a clone of the specified {@code Synchronizer}. This method can be
     * called by {@code clone()} implementations in configuration classes that
     * also need to copy the {@code Synchronizer} object. This method can handle
     * some well-known {@code Synchronizer} implementations directly. For other
     * classes, it uses the following algorithm:
     * <ul>
     * <li>If the class of the {@code Synchronizer} has a standard constructor,
     * a new instance is created using reflection.</li>
     * <li>If this is not possible, it is tried whether the object can be
     * cloned.</li>
     * </ul>
     * If all attempts fail, a {@code ConfigurationRuntimeException} is thrown.
     *
     * @param sync the {@code Synchronizer} object to be cloned
     * @return the clone of this {@code Synchronizer}
     * @throws ConfigurationRuntimeException if no clone can be created
     * @throws IllegalArgumentException if <b>null</b> is passed in
     */
    public static Synchronizer cloneSynchronizer(final Synchronizer sync)
    {
        if (sync == null)
        {
            throw new IllegalArgumentException("Synchronizer must not be null!");
        }
        if (NoOpSynchronizer.INSTANCE == sync)
        {
            return sync;
        }

        try
        {
            return sync.getClass().newInstance();
        }
        catch (final Exception ex)
        {
            LOG.info("Cannot create new instance of " + sync.getClass());
        }

        try
        {
            return (Synchronizer) clone(sync);
        }
        catch (final CloneNotSupportedException cnex)
        {
            throw new ConfigurationRuntimeException(
                    "Cannot clone Synchronizer " + sync);
        }
    }

    
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. 
Params:
src – the configuration, for which runtime exceptions are to be enabled; this configuration must implement EventSource/**
     * 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. {@code DatabaseConfiguration} or
     * {@code JNDIConfiguration}. Per default such errors are simply
     * logged and then ignored. This implementation will register a special
     * {@link EventListener} that throws a runtime
     * exception (namely a {@code ConfigurationRuntimeException}) on
     * each received error event.
     *
     * @param src the configuration, for which runtime exceptions are to be
     * enabled; this configuration must implement {@link EventSource}
     */
    public static void enableRuntimeExceptions(final Configuration src)
    {
        if (!(src instanceof EventSource))
        {
            throw new IllegalArgumentException(
                    "Configuration must implement EventSource!");
        }
        ((EventSource) src).addEventListener(ConfigurationErrorEvent.ANY,
                event -> {
                    // Throw a runtime exception
                    throw new ConfigurationRuntimeException(event
                            .getCause());
                });
    }

    
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.
Params:
clsName – the name of the class to be loaded
Throws:
ClassNotFoundException – if the class cannot be resolved
Returns:
the loaded class
Since:
2.0/**
     * 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.
     *
     * @param clsName the name of the class to be loaded
     * @return the loaded class
     * @throws ClassNotFoundException if the class cannot be resolved
     * @since 2.0
     */
    public static Class<?> loadClass(final String clsName)
            throws ClassNotFoundException
    {
        if (LOG.isDebugEnabled())
        {
            LOG.debug("Loading class " + clsName);
        }

        final ClassLoader cl = Thread.currentThread().getContextClassLoader();
        try
        {
            if (cl != null)
            {
                return cl.loadClass(clsName);
            }
        }
        catch (final ClassNotFoundException cnfex)
        {
            LOG.info("Could not load class " + clsName
                    + " using CCL. Falling back to default CL.", cnfex);
        }

        return ConfigurationUtils.class.getClassLoader().loadClass(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. 
Params:
clsName – the name of the class to be loaded
Throws:
ConfigurationRuntimeException – if the class cannot be resolved
Returns:
the loaded class
Since:
2.0/**
     * Loads the class with the specified name re-throwing
     * {@code ClassNotFoundException} exceptions as runtime exceptions. This
     * method works like {@link #loadClass(String)}. However, checked exceptions
     * are caught and re-thrown as {@code ConfigurationRuntimeException}.
     *
     * @param clsName the name of the class to be loaded
     * @return the loaded class
     * @throws ConfigurationRuntimeException if the class cannot be resolved
     * @since 2.0
     */
    public static Class<?> loadClassNoEx(final String clsName)
    {
        try
        {
            return loadClass(clsName);
        }
        catch (final ClassNotFoundException cnfex)
        {
            throw new ConfigurationRuntimeException("Cannot load class "
                    + clsName, cnfex);
        }
    }

    
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. 
Params:
c – the Configuration to be wrapped (must not be null)
Throws:
NullPointerException – if the passed in Configuration is null
Returns:
an ImmutableConfiguration view on the specified Configuration object
Since:
2.0/**
     * Creates an {@code ImmutableConfiguration} from the given
     * {@code Configuration} object. This method creates a proxy object wrapping
     * the original configuration and making it available under the
     * {@code ImmutableConfiguration} interface. Through this interface the
     * configuration cannot be manipulated. It is also not possible to cast the
     * returned object back to a {@code Configuration} instance to circumvent
     * this protection.
     *
     * @param c the {@code Configuration} to be wrapped (must not be
     *        <b>null</b>)
     * @return an {@code ImmutableConfiguration} view on the specified
     *         {@code Configuration} object
     * @throws NullPointerException if the passed in {@code Configuration} is
     *         <b>null</b>
     * @since 2.0
     */
    public static ImmutableConfiguration unmodifiableConfiguration(
            final Configuration c)
    {
        return createUnmodifiableConfiguration(IMMUTABLE_CONFIG_IFCS, 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. 
Params:
c – the HierarchicalConfiguration to be wrapped (must not be null)
Throws:
NullPointerException – if the passed in HierarchicalConfiguration is null
Returns:
an ImmutableHierarchicalConfiguration view on the specified HierarchicalConfiguration object
Since:
2.0/**
     * Creates an {@code ImmutableHierarchicalConfiguration} from the given
     * {@code HierarchicalConfiguration} object. This method works exactly like
     * the method with the same name, but it operates on hierarchical
     * configurations.
     *
     * @param c the {@code HierarchicalConfiguration} to be wrapped (must not be
     *        <b>null</b>)
     * @return an {@code ImmutableHierarchicalConfiguration} view on the
     *         specified {@code HierarchicalConfiguration} object
     * @throws NullPointerException if the passed in
     *         {@code HierarchicalConfiguration} is <b>null</b>
     * @since 2.0
     */
    public static ImmutableHierarchicalConfiguration unmodifiableConfiguration(
            final HierarchicalConfiguration<?> c)
    {
        return (ImmutableHierarchicalConfiguration) createUnmodifiableConfiguration(
                IMMUTABLE_HIERARCHICAL_CONFIG_IFCS, c);
    }

    
Helper method for creating a proxy for an unmodifiable configuration. The
interfaces the proxy should implement are passed as argument.
Params:
ifcs – an array with the interface classes the proxy must implement
c – the configuration object to be wrapped
Throws:
NullPointerException – if the configuration is null
Returns:
a proxy object for an immutable configuration/**
     * Helper method for creating a proxy for an unmodifiable configuration. The
     * interfaces the proxy should implement are passed as argument.
     *
     * @param ifcs an array with the interface classes the proxy must implement
     * @param c the configuration object to be wrapped
     * @return a proxy object for an immutable configuration
     * @throws NullPointerException if the configuration is <b>null</b>
     */
    private static ImmutableConfiguration createUnmodifiableConfiguration(
            final Class<?>[] ifcs, final Configuration c)
    {
        return (ImmutableConfiguration) Proxy.newProxyInstance(
                ConfigurationUtils.class.getClassLoader(), ifcs,
                new ImmutableConfigurationInvocationHandler(c));
    }

    
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. 
Params:
obj – the object to be cast as EventSource
mockIfUnsupported – a flag whether a mock object should be returned
       if necessary
Throws:
ConfigurationRuntimeException – if the object cannot be cast to EventSource and the mock flag is false
Returns:
an EventSource
Since:
2.0/**
     * Casts the specified object to an {@code EventSource} if possible. The
     * boolean argument determines the method's behavior if the object does not
     * implement the {@code EventSource} event: if set to <b>false</b>, a
     * {@code ConfigurationRuntimeException} is thrown; if set to <b>true</b>, a
     * dummy {@code EventSource} is returned; on this object all methods can be
     * called, but they do not have any effect.
     *
     * @param obj the object to be cast as {@code EventSource}
     * @param mockIfUnsupported a flag whether a mock object should be returned
     *        if necessary
     * @return an {@code EventSource}
     * @throws ConfigurationRuntimeException if the object cannot be cast to
     *         {@code EventSource} and the mock flag is <b>false</b>
     * @since 2.0
     */
    public static EventSource asEventSource(final Object obj,
            final boolean mockIfUnsupported)
    {
        if (obj instanceof EventSource)
        {
            return (EventSource) obj;
        }

        if (!mockIfUnsupported)
        {
            throw new ConfigurationRuntimeException(
                    "Cannot cast to EventSource: " + obj);
        }
        return DUMMY_EVENT_SOURCE;
    }
}