    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.builder;
    018
    019import java.lang.reflect.InvocationHandler;
    020import java.lang.reflect.Method;
    021import java.lang.reflect.Proxy;
    022
    023import org.apache.commons.configuration2.ConfigurationUtils;
    024import org.apache.commons.configuration2.ImmutableConfiguration;
    025import org.apache.commons.configuration2.event.EventSource;
    026import org.apache.commons.configuration2.ex.ConfigurationException;
    027
    028/**
    029 * <p>
    030 * A class that allows the creation of configuration objects wrapping a {@link ConfigurationBuilder}.
    031 * </p>
    032 * <p>
    033 * Using this class special {@code ImmutableConfiguration} proxies can be created that delegate all method invocations
    034 * to another {@code ImmutableConfiguration} obtained from a {@code ConfigurationBuilder}. For instance, if there is a
    035 * configuration {@code c} wrapping the builder {@code builder}, the call {@code c.getString(myKey)} is transformed to
    036 * {@code builder.getConfiguration().getString(myKey)}.
    037 * </p>
    038 * <p>
    039 * There are multiple use cases for such a constellation. One example is that client code can continue working with
    040 * {@code ImmutableConfiguration} objects while under the hood builders are used. Another example is that dynamic
    041 * configurations can be realized in a transparent way: a client holds a single configuration (proxy) object, but the
    042 * underlying builder may return a different data object on each call.
    043 * </p>
    044 *
    045 * @since 2.0
    046 */
    047public class BuilderConfigurationWrapperFactory {
    048
    049    /**
    050     * A specialized {@code InvocationHandler} implementation for wrapper configurations. Here the logic of accessing a
    051     * wrapped builder is implemented.
    052     */
    053    private static final class BuilderConfigurationWrapperInvocationHandler implements InvocationHandler {
    054
    055        /** The wrapped builder. */
    056        private final ConfigurationBuilder<? extends ImmutableConfiguration> builder;
    057
    058        /** The level of {@code EventSource} support. */
    059        private final EventSourceSupport eventSourceSupport;
    060
    061        /**
    062         * Creates a new instance of {@code BuilderConfigurationWrapperInvocationHandler}.
    063         *
    064         * @param wrappedBuilder the wrapped builder
    065         * @param evSrcSupport the level of {@code EventSource} support
    066         */
    067        public BuilderConfigurationWrapperInvocationHandler(final ConfigurationBuilder<? extends ImmutableConfiguration> wrappedBuilder,
    068            final EventSourceSupport evSrcSupport) {
    069            builder = wrappedBuilder;
    070            eventSourceSupport = evSrcSupport;
    071        }
    072
    073        /**
    074         * Handles a method invocation on the associated builder's configuration object.
    075         *
    076         * @param method the method to be invoked
    077         * @param args method arguments
    078         * @return the return value of the method
    079         * @throws Exception if an error occurs
    080         */
    081        private Object handleConfigurationInvocation(final Method method, final Object[] args) throws ReflectiveOperationException, ConfigurationException {
    082            return method.invoke(builder.getConfiguration(), args);
    083        }
    084
    085        /**
    086         * Handles a method invocation on the {@code EventSource} interface. This method evaluates the current
    087         * {@code EventSourceSupport} object in order to find the appropriate target for the invocation.
    088         *
    089         * @param method the method to be invoked
    090         * @param args method arguments
    091         * @return the return value of the method
    092         * @throws ReflectiveOperationException if an error occurs
    093         */
    094        private Object handleEventSourceInvocation(final Method method, final Object... args) throws ReflectiveOperationException {
    095            return method.invoke(EventSourceSupport.DUMMY == eventSourceSupport ? ConfigurationUtils.asEventSource(this, true) : builder, args);
    096        }
    097
    098        /**
    099         * Handles method invocations. This implementation handles methods of two different interfaces:
    100         * <ul>
    101         * <li>Methods from the {@code EventSource} interface are handled according to the current support level.</li>
    102         * <li>Other method calls are delegated to the builder's configuration object.</li>
    103         * </ul>
    104         *
    105         * @param proxy the proxy object
    106         * @param method the method to be invoked
    107         * @param args method arguments
    108         * @return the return value of the method
    109         * @throws ReflectiveOperationException if an error occurs
    110         * @throws ConfigurationException if an error occurs
    111         */
    112        @Override
    113        public Object invoke(final Object proxy, final Method method, final Object[] args) throws ReflectiveOperationException, ConfigurationException {
    114            return EventSource.class.equals(method.getDeclaringClass()) ? handleEventSourceInvocation(method, args)
    115                : handleConfigurationInvocation(method, args);
    116        }
    117    }
    118
    119    /**
    120     * Enumerates options for supporting the {@code EventSource} interface in generated
    121     * {@code ImmutableConfiguration} proxies.
    122     * <p>
    123     * Using literals of this class it is possible to specify that a {@code ImmutableConfiguration} object returned by
    124     * {@code BuilderConfigurationWrapperFactory} also implements the {@code EventSource} interface and how this
    125     * implementation should work. See the documentation of the single constants for more details.
    126     * </p>
    127     */
    128    public enum EventSourceSupport {
    129
    130        /**
    131         * No support of the {@code EventSource} interface. If this option is set, {@code ImmutableConfiguration} objects
    132         * generated by {@code BuilderConfigurationWrapperFactory} do not implement the {@code EventSource} interface.
    133         */
    134        NONE,
    135
    136        /**
    137         * Dummy support of the {@code EventSource} interface. This option causes {@code ImmutableConfiguration} objects
    138         * generated by {@code BuilderConfigurationWrapperFactory} to implement the {@code EventSource} interface, however, this
    139         * implementation consists only of empty dummy methods without real functionality.
    140         */
    141        DUMMY,
    142
    143        /**
    144         * {@code EventSource} support is implemented by delegating to the associated {@code ConfigurationBuilder} object. If
    145         * this option is used, generated {@code ImmutableConfiguration} objects provide a fully functional implementation of
    146         * {@code EventSource} by delegating to the builder. Because the {@code ConfigurationBuilder} interface extends
    147         * {@code EventSource} this delegation is always possible.
    148         */
    149        BUILDER
    150    }
    151
    152    /**
    153     * Creates a {@code ImmutableConfiguration} object which wraps the specified {@code ConfigurationBuilder}. Each access
    154     * of the configuration is delegated to a corresponding call on the {@code ImmutableConfiguration} object managed by the
    155     * builder. This is a convenience method which allows creating wrapper configurations without having to instantiate this
    156     * class.
    157     *
    158     * @param <T> the type of the configuration objects returned by this method
    159     * @param ifcClass the class of the configuration objects returned by this method; this must be an interface class and
    160     *        must not be <strong>null</strong>
    161     * @param builder the wrapped {@code ConfigurationBuilder} (must not be <strong>null</strong>)
    162     * @param evSrcSupport the level of {@code EventSource} support
    163     * @return the wrapper configuration
    164     * @throws IllegalArgumentException if a required parameter is missing
    165     * @throws org.apache.commons.configuration2.ex.ConfigurationRuntimeException if an error occurs when creating the
    166     *         result {@code ImmutableConfiguration}
    167     */
    168    public static <T extends ImmutableConfiguration> T createBuilderConfigurationWrapper(final Class<T> ifcClass,
    169        final ConfigurationBuilder<? extends T> builder, final EventSourceSupport evSrcSupport) {
    170        if (ifcClass == null) {
    171            throw new IllegalArgumentException("Interface class must not be null!");
    172        }
    173        if (builder == null) {
    174            throw new IllegalArgumentException("Builder must not be null!");
    175        }
    176
    177        return ifcClass.cast(Proxy.newProxyInstance(BuilderConfigurationWrapperFactory.class.getClassLoader(), getSupportedInterfaces(ifcClass, evSrcSupport),
    178            new BuilderConfigurationWrapperInvocationHandler(builder, evSrcSupport)));
    179    }
    180
    181    /**
    182     * Gets an array with the classes the generated proxy has to support.
    183     *
    184     * @param ifcClass the class of the configuration objects returned by this method; this must be an interface class and
    185     *        must not be <strong>null</strong>
    186     * @param evSrcSupport the level of {@code EventSource} support
    187     * @return an array with the interface classes to implement
    188     */
    189    private static Class<?>[] getSupportedInterfaces(final Class<?> ifcClass, final EventSourceSupport evSrcSupport) {
    190        return EventSourceSupport.NONE == evSrcSupport ? new Class<?>[] {ifcClass} : new Class<?>[] {EventSource.class, ifcClass};
    191    }
    192
    193    /** The current {@code EventSourceSupport} value. */
    194    private final EventSourceSupport eventSourceSupport;
    195
    196    /**
    197     * Creates a new instance of {@code BuilderConfigurationWrapperFactory} setting the default {@code EventSourceSupport}
    198     * <em>NONE</em>.
    199     */
    200    public BuilderConfigurationWrapperFactory() {
    201        this(EventSourceSupport.NONE);
    202    }
    203
    204    /**
    205     * Creates a new instance of {@code BuilderConfigurationWrapperFactory} and sets the property for supporting the
    206     * {@code EventSource} interface.
    207     *
    208     * @param evSrcSupport the level of {@code EventSource} support
    209     */
    210    public BuilderConfigurationWrapperFactory(final EventSourceSupport evSrcSupport) {
    211        eventSourceSupport = evSrcSupport;
    212    }
    213
    214    /**
    215     * Creates a wrapper {@code ImmutableConfiguration} on top of the specified {@code ConfigurationBuilder}. This
    216     * implementation delegates to
    217     * {@link #createBuilderConfigurationWrapper(Class, ConfigurationBuilder, EventSourceSupport)}.
    218     *
    219     * @param <T> the type of the configuration objects returned by this method
    220     * @param ifcClass the class of the configuration objects returned by this method; this must be an interface class and
    221     *        must not be <strong>null</strong>
    222     * @param builder the wrapped {@code ConfigurationBuilder} (must not be <strong>null</strong>)
    223     * @return the wrapper configuration
    224     * @throws IllegalArgumentException if a required parameter is missing
    225     * @throws org.apache.commons.configuration2.ex.ConfigurationRuntimeException if an error occurs when creating the
    226     *         result {@code ImmutableConfiguration}
    227     */
    228    public <T extends ImmutableConfiguration> T createBuilderConfigurationWrapper(final Class<T> ifcClass, final ConfigurationBuilder<? extends T> builder) {
    229        return createBuilderConfigurationWrapper(ifcClass, builder, getEventSourceSupport());
    230    }
    231
    232    /**
    233     * Gets the level of {@code EventSource} support used when generating {@code ImmutableConfiguration} objects.
    234     *
    235     * @return the level of {@code EventSource} support
    236     */
    237    public EventSourceSupport getEventSourceSupport() {
    238        return eventSourceSupport;
    239    }
    240}