commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1439101 - in /commons/proper/configuration/trunk/src: main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
Date Sun, 27 Jan 2013 15:38:17 GMT
Author: oheger
Date: Sun Jan 27 15:38:17 2013
New Revision: 1439101

URL: http://svn.apache.org/viewvc?rev=1439101&view=rev
Log:
Added a class which provides a Configuration wrapper over a ConfigurationBuilder.

Added:
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
  (with props)
    commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
  (with props)

Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java?rev=1439101&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
(added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
Sun Jan 27 15:38:17 2013
@@ -0,0 +1,332 @@
+/*
+ * 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.configuration.builder;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+
+import org.apache.commons.configuration.Configuration;
+import org.apache.commons.configuration.ConfigurationRuntimeException;
+import org.apache.commons.configuration.ConfigurationUtils;
+import org.apache.commons.configuration.event.EventSource;
+
+/**
+ * <p>
+ * A class that allows the creation of configuration objects wrapping a
+ * {@link ConfigurationBuilder}.
+ * </p>
+ * <p>
+ * Using this class special {@code Configuration} proxies can be created that
+ * delegate all method invocations to another {@code Configuration} obtained
+ * from a {@code ConfigurationBuilder}. For instance, if there is a
+ * configuration {@code c} wrapping the builder {@code builder}, the call
+ * {@code c.getString(myKey)} is transformed to
+ * {@code builder.getConfiguration().getString(myKey)}.
+ * </p>
+ * <p>
+ * There are multiple use cases for such a constellation. One example is that
+ * client code can continue working with {@code Configuration} objects while
+ * under the hood builders are used. Another example is that dynamic
+ * configurations can be realized in a transparent way: a client holds a single
+ * configuration (proxy) object, but the underlying builder may return a
+ * different data object on each call.
+ * </p>
+ *
+ * @version $Id$
+ * @since 2.0
+ */
+public class BuilderConfigurationWrapperFactory
+{
+    /** The current {@code EventSourceSupport} value. */
+    private final EventSourceSupport eventSourceSupport;
+
+    /**
+     * Creates a new instance of {@code BuilderConfigurationWrapperFactory} and
+     * sets the property for supporting the {@code EventSource} interface.
+     *
+     * @param evSrcSupport the level of {@code EventSource} support
+     */
+    public BuilderConfigurationWrapperFactory(EventSourceSupport evSrcSupport)
+    {
+        eventSourceSupport = evSrcSupport;
+    }
+
+    /**
+     * Creates a new instance of {@code BuilderConfigurationWrapperFactory}
+     * setting the default {@code EventSourceSupport} <em>NONE</em>.
+     */
+    public BuilderConfigurationWrapperFactory()
+    {
+        this(EventSourceSupport.NONE);
+    }
+
+    /**
+     * Creates a wrapper {@code Configuration} on top of the specified
+     * {@code ConfigurationBuilder}. This implementation delegates to
+     * {@link #createBuilderConfigurationWrapper(Class, ConfigurationBuilder, EventSourceSupport)}
+     * .
+     *
+     * @param <T> the type of the configuration objects returned by this method
+     * @param ifcClass the class of the configuration objects returned by this
+     *        method; this must be an interface class and must not be
+     *        <b>null</b>
+     * @param builder the wrapped {@code ConfigurationBuilder} (must not be
+     *        <b>null</b>)
+     * @param evSrcSupport the level of {@code EventSource} support
+     * @throws IllegalArgumentException if a required parameter is missing
+     * @throws ConfigurationRuntimeException if an error occurs when creating
+     *         the result {@code Configuration}
+     */
+    public <T extends Configuration> T createBuilderConfigurationWrapper(
+            Class<T> ifcClass, ConfigurationBuilder<? extends T> builder)
+    {
+        return createBuilderConfigurationWrapper(ifcClass, builder,
+                getEventSourceSupport());
+    }
+
+    /**
+     * Returns the level of {@code EventSource} support used when generating
+     * {@code Configuration} objects.
+     *
+     * @return the level of {@code EventSource} support
+     */
+    public EventSourceSupport getEventSourceSupport()
+    {
+        return eventSourceSupport;
+    }
+
+    /**
+     * Returns a {@code Configuration} object which wraps the specified
+     * {@code ConfigurationBuilder}. Each access of the configuration is
+     * delegated to a corresponding call on the {@code Configuration} object
+     * managed by the builder. This is a convenience method which allows
+     * creating wrapper configurations without having to instantiate this class.
+     *
+     * @param <T> the type of the configuration objects returned by this method
+     * @param ifcClass the class of the configuration objects returned by this
+     *        method; this must be an interface class and must not be
+     *        <b>null</b>
+     * @param builder the wrapped {@code ConfigurationBuilder} (must not be
+     *        <b>null</b>)
+     * @param evSrcSupport the level of {@code EventSource} support
+     * @throws IllegalArgumentException if a required parameter is missing
+     * @throws ConfigurationRuntimeException if an error occurs when creating
+     *         the result {@code Configuration}
+     */
+    public static <T extends Configuration> T createBuilderConfigurationWrapper(
+            Class<T> ifcClass, ConfigurationBuilder<? extends T> builder,
+            EventSourceSupport evSrcSupport)
+    {
+        if (ifcClass == null)
+        {
+            throw new IllegalArgumentException(
+                    "Interface class must not be null!");
+        }
+        if (builder == null)
+        {
+            throw new IllegalArgumentException("Builder must not be null!");
+        }
+
+        return ifcClass.cast(Proxy.newProxyInstance(
+                BuilderConfigurationWrapperFactory.class.getClassLoader(),
+                fetchSupportedInterfaces(ifcClass, evSrcSupport),
+                new BuilderConfigurationWrapperInvocationHandler(builder,
+                        evSrcSupport)));
+    }
+
+    /**
+     * Returns an array with the classes the generated proxy has to support.
+     *
+     * @param ifcClass the class of the configuration objects returned by this
+     *        method; this must be an interface class and must not be
+     *        <b>null</b>
+     * @param evSrcSupport the level of {@code EventSource} support
+     * @return an array with the interface classes to implement
+     */
+    private static Class<?>[] fetchSupportedInterfaces(Class<?> ifcClass,
+            EventSourceSupport evSrcSupport)
+    {
+        if (EventSourceSupport.NONE == evSrcSupport)
+        {
+            return new Class<?>[] {
+                ifcClass
+            };
+        }
+
+        Class<?>[] result = new Class<?>[2];
+        result[0] = EventSource.class;
+        result[1] = ifcClass;
+        return result;
+    }
+
+    /**
+     * <p>
+     * An enumeration class with different options for supporting the
+     * {@code EventSource} interface in generated {@code Configuration} proxies.
+     * </p>
+     * <p>
+     * Using literals of this class it is possible to specify that a
+     * {@code Configuration} object returned by
+     * {@code BuilderConfigurationWrapperFactory} also implements the
+     * {@code EventSource} interface and how this implementation should work.
+     * See the documentation of the single constants for more details
+     * </p>
+     */
+    public static enum EventSourceSupport
+    {
+        /**
+         * No support of the {@code EventSource} interface. If this option is
+         * set, {@code Configuration} objects generated by
+         * {@code BuilderConfigurationWrapperFactory} do not implement the
+         * {@code EventSource} interface.
+         */
+        NONE,
+
+        /**
+         * Dummy support of the {@code EventSource} interface. This option
+         * causes {@code Configuration} objects generated by
+         * {@code BuilderConfigurationWrapperFactory} to implement the
+         * {@code EventSource} interface, however, this implementation consists
+         * only of empty dummy methods without real functionality.
+         */
+        DUMMY,
+
+        /**
+         * {@code EventSource} support is implemented by delegating to the
+         * associated {@code ConfigurationBuilder} object. If this option is
+         * used, generated {@code Configuration} objects provide a fully
+         * functional implementation of {@code EventSource} by delegating to the
+         * builder. The builder must implement the {@code EventSource}
+         * interface, otherwise an exception is thrown.
+         */
+        BUILDER,
+
+        /**
+         * {@code EventSource} support is implemented by delegating to the
+         * associated {@code ConfigurationBuilder} object if it supports this
+         * interface. Otherwise, a dummy implementation is used.
+         */
+        BUILDER_OPTIONAL
+    }
+
+    /**
+     * A specialized {@code InvocationHandler} implementation for wrapper
+     * configurations. Here the logic of accessing a wrapped builder is
+     * implemented.
+     */
+    private static class BuilderConfigurationWrapperInvocationHandler implements
+            InvocationHandler
+    {
+        /** The wrapped builder. */
+        private final ConfigurationBuilder<? extends Configuration> builder;
+
+        /** The level of {@code EventSource} support. */
+        private final EventSourceSupport eventSourceSupport;
+
+        /**
+         * Creates a new instance of
+         * {@code BuilderConfigurationWrapperInvocationHandler}.
+         *
+         * @param wrappedBuilder the wrapped builder
+         * @param evSrcSupport the level of {@code EventSource} support
+         */
+        public BuilderConfigurationWrapperInvocationHandler(
+                ConfigurationBuilder<? extends Configuration> wrappedBuilder,
+                EventSourceSupport evSrcSupport)
+        {
+            builder = wrappedBuilder;
+            eventSourceSupport = evSrcSupport;
+        }
+
+        /**
+         * Handles method invocations. This implementation handles methods of
+         * two different interfaces:
+         * <ul>
+         * <li>Methods from the {@code EventSource} interface are handled
+         * according to the current support level.</li>
+         * <li>Other method calls are delegated to the builder's configuration
+         * object.</li>
+         * </ul>
+         *
+         * @param proxy the proxy object
+         * @param method the method to be invoked
+         * @param args method arguments
+         * @return the return value of the method
+         * @throws Throwable if an error occurs
+         */
+        public Object invoke(Object proxy, Method method, Object[] args)
+                throws Throwable
+        {
+            if (EventSource.class.equals(method.getDeclaringClass()))
+            {
+                return handleEventSourceInvocation(method, args);
+            }
+            else
+            {
+                return handleConfigurationInvocation(method, args);
+            }
+        }
+
+        /**
+         * Handles a method invocation on the associated builder's configuration
+         * object.
+         *
+         * @param method the method to be invoked
+         * @param args method arguments
+         * @return the return value of the method
+         * @throws Exception if an error occurs
+         */
+        private Object handleConfigurationInvocation(Method method,
+                Object[] args) throws Exception
+        {
+            return method.invoke(builder.getConfiguration(), args);
+        }
+
+        /**
+         * Handles a method invocation on the {@code EventSource} interface.
+         * This method evaluates the current {@code EventSourceSupport} object
+         * in order to find the appropriate target for the invocation.
+         *
+         * @param method the method to be invoked
+         * @param args method arguments
+         * @return the return value of the method
+         * @throws Exception if an error occurs
+         */
+        private Object handleEventSourceInvocation(Method method, Object[] args)
+                throws Exception
+        {
+            Object src;
+            boolean mockIfUnsupported;
+            if (EventSourceSupport.DUMMY == eventSourceSupport)
+            {
+                src = this;
+                mockIfUnsupported = true;
+            }
+            else
+            {
+                src = builder;
+                mockIfUnsupported =
+                        EventSourceSupport.BUILDER_OPTIONAL == eventSourceSupport;
+            }
+
+            Object target =
+                    ConfigurationUtils.asEventSource(src, mockIfUnsupported);
+            return method.invoke(target, args);
+        }
+    }
+}

Propchange: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/BuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java?rev=1439101&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
(added)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
Sun Jan 27 15:38:17 2013
@@ -0,0 +1,238 @@
+/*
+ * 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.configuration.builder;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+import org.apache.commons.configuration.BaseHierarchicalConfiguration;
+import org.apache.commons.configuration.Configuration;
+import org.apache.commons.configuration.ConfigurationException;
+import org.apache.commons.configuration.ConfigurationRuntimeException;
+import org.apache.commons.configuration.HierarchicalConfiguration;
+import org.apache.commons.configuration.builder.BuilderConfigurationWrapperFactory.EventSourceSupport;
+import org.apache.commons.configuration.event.ConfigurationListener;
+import org.apache.commons.configuration.event.EventSource;
+import org.easymock.EasyMock;
+import org.junit.Test;
+
+/**
+ * Test class for {@code BuilderConfigurationWrapperFactory}.
+ *
+ * @version $Id$
+ */
+public class TestBuilderConfigurationWrapperFactory
+{
+    /**
+     * Tests the default event source support level.
+     */
+    @Test
+    public void testDefaultEventSourceSupport()
+    {
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory();
+        assertEquals("Wrong result", EventSourceSupport.NONE,
+                factory.getEventSourceSupport());
+    }
+
+    /**
+     * Returns a mock builder which always returns the specified configuration.
+     *
+     * @param conf the builder's result configuration
+     * @return the mock builder
+     */
+    private ConfigurationBuilder<BaseHierarchicalConfiguration> createBuilderMock(
+            BaseHierarchicalConfiguration conf)
+    {
+        @SuppressWarnings("unchecked")
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                EasyMock.createMock(ConfigurationBuilder.class);
+        try
+        {
+            EasyMock.expect(builder.getConfiguration()).andReturn(conf)
+                    .anyTimes();
+        }
+        catch (ConfigurationException e)
+        {
+            // Cannot happen
+            fail("Unexpected exception: " + e);
+        }
+        return builder;
+    }
+
+    /**
+     * Tests whether the returned configuration correctly wraps the builder.
+     */
+    @Test
+    public void testConfigurationBuilderWrapper()
+    {
+        BaseHierarchicalConfiguration conf =
+                new BaseHierarchicalConfiguration();
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                createBuilderMock(conf);
+        EasyMock.replay(builder);
+        conf.addProperty("test1", "value1");
+        conf.addProperty("test2", "42");
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory();
+        HierarchicalConfiguration wrapper =
+                factory.createBuilderConfigurationWrapper(
+                        HierarchicalConfiguration.class, builder);
+        assertEquals("Wrong value (1)", "value1", wrapper.getString("test1"));
+        assertEquals("Wrong value (2)", 42, wrapper.getInt("test2"));
+        assertSame("Wrong root node", conf.getRootNode(), wrapper.getRootNode());
+    }
+
+    /**
+     * Tests the factory if support for EventSource is disabled.
+     */
+    @Test
+    public void testEventSourceSupportNone()
+    {
+        BaseHierarchicalConfiguration conf =
+                new BaseHierarchicalConfiguration();
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                createBuilderMock(conf);
+        EasyMock.replay(builder);
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory();
+        HierarchicalConfiguration wrapper =
+                factory.createBuilderConfigurationWrapper(
+                        HierarchicalConfiguration.class, builder);
+        assertFalse("EventSource support", wrapper instanceof EventSource);
+    }
+
+    /**
+     * Tests the EventSource support level 'dummy'.
+     */
+    @Test
+    public void testEventSourceSupportDummy()
+    {
+        BaseHierarchicalConfiguration conf =
+                new BaseHierarchicalConfiguration();
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                createBuilderMock(conf);
+        EasyMock.replay(builder);
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory(EventSourceSupport.DUMMY);
+        EventSource src =
+                (EventSource) factory.createBuilderConfigurationWrapper(
+                        HierarchicalConfiguration.class, builder);
+        src.addConfigurationListener(null);
+    }
+
+    /**
+     * Tests EventSource support level 'builder'.
+     */
+    @Test(expected = ConfigurationRuntimeException.class)
+    public void testEventSourceSupportBuilder()
+    {
+        BaseHierarchicalConfiguration conf =
+                new BaseHierarchicalConfiguration();
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                createBuilderMock(conf);
+        EasyMock.replay(builder);
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory(
+                        EventSourceSupport.BUILDER);
+        EventSource src =
+                (EventSource) factory.createBuilderConfigurationWrapper(
+                        HierarchicalConfiguration.class, builder);
+        src.addConfigurationListener(null);
+    }
+
+    /**
+     * Tests whether EventSource methods can be delegated to the builder.
+     */
+    @Test
+    public void testEventSourceSupportBuilderOptionalSupported()
+    {
+        BuilderWithEventSource builder =
+                EasyMock.createMock(BuilderWithEventSource.class);
+        ConfigurationListener l =
+                EasyMock.createMock(ConfigurationListener.class);
+        builder.addConfigurationListener(l);
+        EasyMock.expect(builder.removeConfigurationListener(l)).andReturn(
+                Boolean.TRUE);
+        EasyMock.replay(builder, l);
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory(
+                        EventSourceSupport.BUILDER_OPTIONAL);
+        EventSource src =
+                (EventSource) factory.createBuilderConfigurationWrapper(
+                        Configuration.class, builder);
+        src.addConfigurationListener(l);
+        assertTrue("Wrong result", src.removeConfigurationListener(l));
+        EasyMock.verify(builder);
+    }
+
+    /**
+     * Tests EventSource support level 'builder optional' if the builder does
+     * not provide support.
+     */
+    @Test
+    public void testEventSourceSupportBuilderOptionalNotSupported()
+    {
+        BaseHierarchicalConfiguration conf =
+                new BaseHierarchicalConfiguration();
+        ConfigurationBuilder<BaseHierarchicalConfiguration> builder =
+                createBuilderMock(conf);
+        EasyMock.replay(builder);
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory(
+                        EventSourceSupport.BUILDER_OPTIONAL);
+        EventSource src =
+                (EventSource) factory.createBuilderConfigurationWrapper(
+                        HierarchicalConfiguration.class, builder);
+        src.addErrorListener(null);
+    }
+
+    /**
+     * Tries to create a wrapper without passing an interface class.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testCreateBuilderConfigurationWrapperNoClass()
+    {
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory(
+                        EventSourceSupport.BUILDER_OPTIONAL);
+        factory.createBuilderConfigurationWrapper(null,
+                EasyMock.createMock(BuilderWithEventSource.class));
+    }
+
+    /**
+     * Tries to create a wrapper without passing a builder.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testCreateBuilderConfigurationWrapperNoBuilder()
+    {
+        BuilderConfigurationWrapperFactory factory =
+                new BuilderConfigurationWrapperFactory();
+        factory.createBuilderConfigurationWrapper(Configuration.class, null);
+    }
+
+    /**
+     * A combined interface needed for mock generation.
+     */
+    private static interface BuilderWithEventSource extends
+            ConfigurationBuilder<Configuration>, EventSource
+    {
+    }
+}

Propchange: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestBuilderConfigurationWrapperFactory.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message