commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1545824 - in /commons/proper/configuration/trunk/src: main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java
Date Tue, 26 Nov 2013 20:34:07 GMT
Author: oheger
Date: Tue Nov 26 20:34:06 2013
New Revision: 1545824

URL: http://svn.apache.org/r1545824
Log:
Extracted functionality related to default values to a separate class.

The new class DefaultParametersManager is now responsible for managing and
applying DefaultParametersHandler objects.

Added:
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java
    commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java

Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java?rev=1545824&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java
(added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/DefaultParametersManager.java
Tue Nov 26 20:34:06 2013
@@ -0,0 +1,275 @@
+/*
+ * 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.util.Collection;
+import java.util.LinkedList;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+import org.apache.commons.configuration.builder.fluent.FileBasedBuilderParameters;
+import org.apache.commons.configuration.builder.fluent.PropertiesBuilderParameters;
+import org.apache.commons.configuration.builder.fluent.XMLBuilderParameters;
+
+/**
+ * <p>
+ * A class for managing a set of {@link DefaultParametersHandler} objects.
+ * </p>
+ * <p>
+ * This class provides functionality for registering and removing
+ * {@code DefaultParametersHandler} objects for arbitrary parameters classes.
+ * The handlers registered at an instance can then be applied on a passed in
+ * parameters object, so that it gets initialized with the provided default
+ * values.
+ * </p>
+ * <p>
+ * Usage of this class is as follows: First the {@code DefaultParametersHandler}
+ * objects to be supported must be registered using one of the
+ * {@code registerDefaultHandler()} methods. After that arbitrary parameters
+ * objects can be passed to the {@code initializeParameters()} method. This
+ * causes all {@code DefaultParametersHandler} objects supporting this
+ * parameters class to be invoked on this object.
+ * </p>
+ * <p>
+ * Implementation note: This class is thread-safe.
+ * </p>
+ *
+ * @version $Id: $
+ * @since 2.0
+ */
+public class DefaultParametersManager
+{
+    /** A collection with the registered default handlers. */
+    private final Collection<DefaultHandlerData> defaultHandlers;
+
+    /**
+     * Creates a new instance of {@code DefaultParametersManager}.
+     */
+    public DefaultParametersManager()
+    {
+        defaultHandlers = new CopyOnWriteArrayList<DefaultHandlerData>();
+    }
+
+    /**
+     * Registers the specified {@code DefaultParametersHandler} object for the
+     * given parameters class. This means that this handler object is invoked
+     * every time a parameters object of the specified class or one of its
+     * subclasses is initialized. The handler can set arbitrary default values
+     * for the properties supported by this parameters object. If there are
+     * multiple handlers registered supporting a specific parameters class, they
+     * are invoked in the order in which they were registered. So handlers
+     * registered later may override the values set by handlers registered
+     * earlier.
+     *
+     * @param <T> the type of the parameters supported by this handler
+     * @param paramsClass the parameters class supported by this handler (must
+     *        not be <b>null</b>)
+     * @param handler the {@code DefaultParametersHandler} to be registered
+     *        (must not be <b>null</b>)
+     * @throws IllegalArgumentException if a required parameter is missing
+     */
+    public <T> void registerDefaultsHandler(Class<T> paramsClass,
+            DefaultParametersHandler<? super T> handler)
+    {
+        registerDefaultsHandler(paramsClass, handler, null);
+    }
+
+    /**
+     * Registers the specified {@code DefaultParametersHandler} object for the
+     * given parameters class and start class in the inheritance hierarchy. This
+     * method works like
+     * {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}, but
+     * the defaults handler is only executed on parameter objects that are
+     * instances of the specified start class. Parameter classes do not stand in
+     * a real inheritance hierarchy; however, there is a logic hierarchy defined
+     * by the methods supported by the different parameter objects. A properties
+     * parameter object for instance supports all methods defined for a
+     * file-based parameter object. So one can argue that
+     * {@link FileBasedBuilderParameters} is a base interface of
+     * {@link PropertiesBuilderParameters} (although, for technical reasons,
+     * this relation is not reflected in the Java classes). A
+     * {@link DefaultParametersHandler} object defined for a base interface can
+     * also deal with parameter objects "derived" from this base interface (i.e.
+     * supporting a super set of the methods defined by the base interface). Now
+     * there may be the use case that there is an implementation of
+     * {@code DefaultParametersHandler} for a base interface (e.g.
+     * {@code FileBasedBuilderParameters}), but it should only process specific
+     * derived interfaces (say {@code PropertiesBuilderParameters}, but not
+     * {@link XMLBuilderParameters}). This can be achieved by passing in
+     * {@code PropertiesBuilderParameters} as start class. In this case,
+     * {@code DefaultParametersManager} ensures that the handler is only called
+     * on parameter objects having both the start class and the actual type
+     * supported by the handler as base interfaces. The passed in start class
+     * can be <b>null</b>; then the parameter class supported by the handler
is
+     * used (which is the default behavior of the
+     * {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}
+     * method).
+     *
+     * @param <T> the type of the parameters supported by this handler
+     * @param paramsClass the parameters class supported by this handler (must
+     *        not be <b>null</b>)
+     * @param handler the {@code DefaultParametersHandler} to be registered
+     *        (must not be <b>null</b>)
+     * @param startClass an optional start class in the hierarchy of parameter
+     *        objects for which this handler should be applied
+     * @throws IllegalArgumentException if a required parameter is missing
+     */
+    public <T> void registerDefaultsHandler(Class<T> paramsClass,
+            DefaultParametersHandler<? super T> handler, Class<?> startClass)
+    {
+        if (paramsClass == null)
+        {
+            throw new IllegalArgumentException(
+                    "Parameters class must not be null!");
+        }
+        if (handler == null)
+        {
+            throw new IllegalArgumentException(
+                    "DefaultParametersHandler must not be null!");
+        }
+        defaultHandlers.add(new DefaultHandlerData(handler, paramsClass,
+                startClass));
+    }
+
+    /**
+     * Removes the specified {@code DefaultParametersHandler} from this
+     * instance. If this handler has been registered multiple times for
+     * different start classes, all occurrences are removed.
+     *
+     * @param handler the {@code DefaultParametersHandler} to be removed
+     */
+    public void unregisterDefaultsHandler(DefaultParametersHandler<?> handler)
+    {
+        unregisterDefaultsHandler(handler, null);
+    }
+
+    /**
+     * Removes the specified {@code DefaultParametersHandler} from this instance
+     * if it is in combination with the given start class. If this handler has
+     * been registered multiple times for different start classes, only
+     * occurrences for the given start class are removed. The {@code startClass}
+     * parameter can be <b>null</b>, then all occurrences of the handler are
+     * removed.
+     *
+     * @param handler the {@code DefaultParametersHandler} to be removed
+     * @param startClass the start class for which this handler is to be removed
+     */
+    public void unregisterDefaultsHandler(DefaultParametersHandler<?> handler,
+            Class<?> startClass)
+    {
+        Collection<DefaultHandlerData> toRemove =
+                new LinkedList<DefaultHandlerData>();
+        for (DefaultHandlerData dhd : defaultHandlers)
+        {
+            if (dhd.isOccurrence(handler, startClass))
+            {
+                toRemove.add(dhd);
+            }
+        }
+
+        defaultHandlers.removeAll(toRemove);
+    }
+
+    /**
+     * Initializes the passed in {@code BuilderParameters} object by applying
+     * all matching {@link DefaultParametersHandler} objects registered at this
+     * instance. Using this method the passed in parameters object can be
+     * populated with default values.
+     *
+     * @param params the parameters object to be initialized (may be
+     *        <b>null</b>, then this method has no effect)
+     */
+    public void initializeParameters(BuilderParameters params)
+    {
+        if (params != null)
+        {
+            for (DefaultHandlerData dhd : defaultHandlers)
+            {
+                dhd.applyHandlerIfMatching(params);
+            }
+        }
+    }
+
+    /**
+     * A data class storing information about {@code DefaultParametersHandler}
+     * objects added to a {@code Parameters} object. Using this class it is
+     * possible to find out which default handlers apply for a given parameters
+     * object and to invoke them.
+     */
+    private static class DefaultHandlerData
+    {
+        /** The handler object. */
+        private final DefaultParametersHandler<?> handler;
+
+        /** The class supported by this handler. */
+        private final Class<?> parameterClass;
+
+        /** The start class for applying this handler. */
+        private final Class<?> startClass;
+
+        /**
+         * Creates a new instance of {@code DefaultHandlerData}.
+         *
+         * @param h the {@code DefaultParametersHandler}
+         * @param cls the handler's data class
+         * @param startCls the start class
+         */
+        public DefaultHandlerData(DefaultParametersHandler<?> h, Class<?> cls,
+                Class<?> startCls)
+        {
+            handler = h;
+            parameterClass = cls;
+            startClass = startCls;
+        }
+
+        /**
+         * Checks whether the managed {@code DefaultParametersHandler} can be
+         * applied to the given parameters object. If this is the case, it is
+         * executed on this object and can initialize it with default values.
+         *
+         * @param obj the parameters object to be initialized
+         */
+        @SuppressWarnings("unchecked")
+        // There are explicit isInstance() checks, so there won't be
+        // ClassCastExceptions
+        public void applyHandlerIfMatching(BuilderParameters obj)
+        {
+            if (parameterClass.isInstance(obj)
+                    && (startClass == null || startClass.isInstance(obj)))
+            {
+                @SuppressWarnings("rawtypes")
+                DefaultParametersHandler handlerUntyped = handler;
+                handlerUntyped.initializeDefaults(obj);
+            }
+        }
+
+        /**
+         * Tests whether this instance refers to the specified occurrence of a
+         * {@code DefaultParametersHandler}.
+         *
+         * @param h the handler to be checked
+         * @param startCls the start class
+         * @return <b>true</b> if this instance refers to this occurrence,
+         *         <b>false</b> otherwise
+         */
+        public boolean isOccurrence(DefaultParametersHandler<?> h,
+                Class<?> startCls)
+        {
+            return h == handler
+                    && (startCls == null || startCls.equals(startClass));
+        }
+    }
+}

Added: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java?rev=1545824&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java
(added)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestDefaultParametersManager.java
Tue Nov 26 20:34:06 2013
@@ -0,0 +1,269 @@
+/*
+ * 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.assertNull;
+import static org.junit.Assert.assertSame;
+
+import java.util.Map;
+
+import org.apache.commons.configuration.builder.fluent.FileBasedBuilderParameters;
+import org.apache.commons.configuration.builder.fluent.Parameters;
+import org.apache.commons.configuration.builder.fluent.PropertiesBuilderParameters;
+import org.apache.commons.configuration.builder.fluent.XMLBuilderParameters;
+import org.apache.commons.configuration.convert.ListDelimiterHandler;
+import org.apache.commons.configuration.tree.ExpressionEngine;
+import org.easymock.EasyMock;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+/**
+ * Test class for {@code DefaultParametersManager}.
+ *
+ * @version $Id: $
+ */
+public class TestDefaultParametersManager
+{
+    /** Constant for the default encoding. */
+    private static final String DEF_ENCODING = "UTF-8";
+
+    /** A test list delimiter handler. */
+    private static ListDelimiterHandler listHandler;
+
+    /** An object for creating new parameters objects. */
+    private Parameters parameters;
+
+    /** The manager to be tested. */
+    private DefaultParametersManager manager;
+
+    @BeforeClass
+    public static void setUpBeforeClass() throws Exception
+    {
+        listHandler = EasyMock.createMock(ListDelimiterHandler.class);
+    }
+
+    @Before
+    public void setUp() throws Exception
+    {
+        parameters = new Parameters();
+        manager = new DefaultParametersManager();
+    }
+
+    /**
+     * Tries to register a default handler without a class.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testRegisterDefaultsHandlerNoClass()
+    {
+        manager.registerDefaultsHandler(null, new FileBasedDefaultsHandler());
+    }
+
+    /**
+     * Tries to register a null default handler.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testRegisterDefaultsHandlerNoHandler()
+    {
+        manager.registerDefaultsHandler(BasicBuilderProperties.class, null);
+    }
+
+    /**
+     * Checks whether the expected default values have been set on a parameters
+     * object.
+     *
+     * @param map the map with parameters
+     */
+    private static void checkDefaultValues(Map<String, Object> map)
+    {
+        assertEquals("Wrong delimiter handler", listHandler,
+                map.get("listDelimiterHandler"));
+        assertEquals("Wrong exception flag value", Boolean.TRUE,
+                map.get("throwExceptionOnMissing"));
+        FileBasedBuilderParametersImpl fbparams =
+                FileBasedBuilderParametersImpl.fromParameters(map);
+        assertEquals("Wrong encoding", DEF_ENCODING, fbparams.getFileHandler()
+                .getEncoding());
+    }
+
+    /**
+     * Checks that no default values have been set on a parameters object.
+     *
+     * @param map the map with parameters
+     */
+    private static void checkNoDefaultValues(Map<String, Object> map)
+    {
+        assertFalse("Got base properties",
+                map.containsKey("throwExceptionOnMissing"));
+        FileBasedBuilderParametersImpl fbParams =
+                FileBasedBuilderParametersImpl.fromParameters(map, true);
+        assertNull("Got an encoding", fbParams.getFileHandler().getEncoding());
+    }
+
+    /**
+     * Tests whether default values are set for newly created parameters
+     * objects.
+     */
+    @Test
+    public void testApplyDefaults()
+    {
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                new FileBasedDefaultsHandler());
+        FileBasedBuilderParameters params = parameters.fileBased();
+        manager.initializeParameters(params);
+        Map<String, Object> map = params.getParameters();
+        checkDefaultValues(map);
+    }
+
+    /**
+     * Tests whether default values are also applied when a sub parameters class
+     * is created.
+     */
+    @Test
+    public void testApplyDefaultsOnSubClass()
+    {
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                new FileBasedDefaultsHandler());
+        XMLBuilderParameters params = parameters.xml();
+        manager.initializeParameters(params);
+        Map<String, Object> map = params.getParameters();
+        checkDefaultValues(map);
+    }
+
+    /**
+     * Tests that default values are only applied if the start class provided at
+     * registration time matches.
+     */
+    @Test
+    public void testApplyDefaultsStartClass()
+    {
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                new FileBasedDefaultsHandler(), XMLBuilderParameters.class);
+        XMLBuilderParameters paramsXml = parameters.xml();
+        manager.initializeParameters(paramsXml);
+        Map<String, Object> map = paramsXml.getParameters();
+        checkDefaultValues(map);
+        PropertiesBuilderParameters paramsProps = parameters.properties();
+        manager.initializeParameters(paramsProps);
+        map = paramsProps.getParameters();
+        checkNoDefaultValues(map);
+    }
+
+    /**
+     * Tests whether multiple handlers can be registered for the same classes
+     * and whether they are called in the correct order.
+     */
+    @Test
+    public void testApplyDefaultsMultipleHandlers()
+    {
+        final ExpressionEngine engine =
+                EasyMock.createMock(ExpressionEngine.class);
+        manager.registerDefaultsHandler(XMLBuilderParameters.class,
+                new DefaultParametersHandler<XMLBuilderParameters>()
+                {
+                    public void initializeDefaults(
+                            XMLBuilderParameters parameters)
+                    {
+                        parameters
+                                .setThrowExceptionOnMissing(false)
+                                .setListDelimiterHandler(
+                                        EasyMock.createMock(ListDelimiterHandler.class))
+                                .setExpressionEngine(engine);
+                    }
+                });
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                new FileBasedDefaultsHandler());
+        XMLBuilderParameters params = parameters.xml();
+        manager.initializeParameters(params);
+        Map<String, Object> map = params.getParameters();
+        checkDefaultValues(map);
+        assertSame("Expression engine not set", engine,
+                map.get("expressionEngine"));
+    }
+
+    /**
+     * Tests whether initializeParameters() ignores null input. (We can only
+     * test that no exception is thrown.)
+     */
+    @Test
+    public void testInitializeParametersNull()
+    {
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                new FileBasedDefaultsHandler());
+        manager.initializeParameters(null);
+    }
+
+    /**
+     * Tests whether all occurrences of a given defaults handler can be removed.
+     */
+    @Test
+    public void testUnregisterDefaultsHandlerAll()
+    {
+        FileBasedDefaultsHandler handler = new FileBasedDefaultsHandler();
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                handler, XMLBuilderParameters.class);
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                handler, PropertiesBuilderParameters.class);
+        manager.unregisterDefaultsHandler(handler);
+
+        XMLBuilderParameters paramsXml = parameters.xml();
+        manager.initializeParameters(paramsXml);
+        checkNoDefaultValues(paramsXml.getParameters());
+        PropertiesBuilderParameters paramsProps = parameters.properties();
+        manager.initializeParameters(paramsProps);
+        checkNoDefaultValues(paramsProps.getParameters());
+    }
+
+    /**
+     * Tests whether a specific occurrence of a defaults handler can be removed.
+     */
+    @Test
+    public void testUnregisterDefaultsHandlerSpecific()
+    {
+        FileBasedDefaultsHandler handler = new FileBasedDefaultsHandler();
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                handler, XMLBuilderParameters.class);
+        manager.registerDefaultsHandler(FileBasedBuilderParameters.class,
+                handler, PropertiesBuilderParameters.class);
+        manager.unregisterDefaultsHandler(handler,
+                PropertiesBuilderParameters.class);
+        XMLBuilderParameters paramsXml = parameters.xml();
+        manager.initializeParameters(paramsXml);
+        checkDefaultValues(paramsXml.getParameters());
+        PropertiesBuilderParameters paramsProps = parameters.properties();
+        manager.initializeParameters(paramsProps);
+        checkNoDefaultValues(paramsProps.getParameters());
+    }
+
+    /**
+     * A test defaults handler implementation for testing the initialization of
+     * parameters objects with default values. This class sets some hard-coded
+     * default values.
+     */
+    private static class FileBasedDefaultsHandler implements
+            DefaultParametersHandler<FileBasedBuilderParameters>
+    {
+        public void initializeDefaults(FileBasedBuilderParameters parameters)
+        {
+            parameters.setThrowExceptionOnMissing(true)
+                    .setEncoding(DEF_ENCODING)
+                    .setListDelimiterHandler(listHandler);
+        }
+    }
+}



Mime
View raw message