commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1397263 - in /commons/proper/configuration/trunk/src: main/java/org/apache/commons/configuration/builder/ test/java/org/apache/commons/configuration/builder/
Date Thu, 11 Oct 2012 19:45:49 GMT
Author: oheger
Date: Thu Oct 11 19:45:48 2012
New Revision: 1397263

URL: http://svn.apache.org/viewvc?rev=1397263&view=rev
Log:
Added ReloadingFileBasedConfigurationBuilder.

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

Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/ReloadingFileBasedConfigurationBuilder.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/ReloadingFileBasedConfigurationBuilder.java?rev=1397263&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/ReloadingFileBasedConfigurationBuilder.java
(added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/ReloadingFileBasedConfigurationBuilder.java
Thu Oct 11 19:45:48 2012
@@ -0,0 +1,228 @@
+/*
+ * 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.Map;
+
+import org.apache.commons.configuration.ConfigurationException;
+import org.apache.commons.configuration.FileBasedConfiguration;
+import org.apache.commons.configuration.io.FileHandler;
+import org.apache.commons.configuration.reloading.FileHandlerReloadingDetector;
+import org.apache.commons.configuration.reloading.ReloadingController;
+import org.apache.commons.configuration.reloading.ReloadingDetector;
+import org.apache.commons.configuration.reloading.ReloadingEvent;
+import org.apache.commons.configuration.reloading.ReloadingListener;
+
+/**
+ * <p>
+ * A specialized {@code ConfigurationBuilder} implementation which can handle
+ * configurations read from a {@link FileHandler} and supports reloading.
+ * </p>
+ * <p>
+ * This builder class exposes a {@link ReloadingController} object controlling
+ * reload operations on the file-based configuration produced as result object.
+ * For the {@code FileHandler} defining the location of the configuration a
+ * {@link FileHandlerReloadingDetector} is created and associated with the
+ * controller. So changes on the source file can be detected. When ever such a
+ * change occurs, the result object of this builder is reset. This means that
+ * the next time {@code getConfiguration()} is called a new
+ * {@code Configuration} object is created which is loaded from the modified
+ * file.
+ * </p>
+ * <p>
+ * Client code interested in notifications can register a listener at this
+ * builder to receive reset events. When such an event is received the new
+ * result object can be requested. This way client applications can be sure to
+ * work with an up-to-date configuration. It is also possible to register a
+ * listener directly at the {@code ReloadingController}.
+ * </p>
+ * <p>
+ * This builder does not actively trigger the {@code ReloadingController} to
+ * perform a reload check. This has to be done by an external component, e.g. a
+ * timer.
+ * </p>
+ *
+ * @version $Id$
+ * @since 2.0
+ * @param <T> the concrete type of {@code Configuration} objects created by this
+ *        builder
+ */
+public class ReloadingFileBasedConfigurationBuilder<T extends FileBasedConfiguration>
+        extends FileBasedConfigurationBuilder<T>
+{
+    /** The reloading controller associated with this object. */
+    private final ReloadingController reloadingController;
+
+    /**
+     * The reloading detector which does the actual reload check for the current
+     * result object. A new instance is created whenever a new result object
+     * (and thus a new current file handler) becomes available. The field must
+     * be volatile because it is accessed by the reloading controller probably
+     * from within another thread.
+     */
+    private volatile ReloadingDetector resultReloadingDetector;
+
+    /**
+     * Creates a new instance of {@code ReloadingFileBasedConfigurationBuilder}
+     * which produces result objects of the specified class and sets
+     * initialization parameters.
+     *
+     * @param resCls the result class (must not be <b>null</b>
+     * @param params a map with initialization parameters
+     * @throws IllegalArgumentException if the result class is <b>null</b>
+     */
+    public ReloadingFileBasedConfigurationBuilder(Class<T> resCls,
+            Map<String, Object> params)
+    {
+        super(resCls, params);
+        reloadingController = createReloadingController();
+    }
+
+    /**
+     * Creates a new instance of {@code ReloadingFileBasedConfigurationBuilder}
+     * which produces result objects of the specified class.
+     *
+     * @param resCls the result class (must not be <b>null</b>
+     * @throws IllegalArgumentException if the result class is <b>null</b>
+     */
+    public ReloadingFileBasedConfigurationBuilder(Class<T> resCls)
+    {
+        super(resCls);
+        reloadingController = createReloadingController();
+    }
+
+    /**
+     * Returns the {@code ReloadingController} associated with this builder.
+     * This controller is directly created. However, it becomes active (i.e.
+     * associated with a meaningful reloading detector) not before a result
+     * object was created.
+     *
+     * @return the {@code ReloadingController}
+     */
+    public ReloadingController getReloadingController()
+    {
+        return reloadingController;
+    }
+
+    /**
+     * Creates a {@code ReloadingDetector} which monitors the passed in
+     * {@code FileHandler}. This method is called each time a new result object
+     * is created with the current {@code FileHandler}. The
+     * {@code ReloadingDetector} associated with this builder's
+     * {@link ReloadingController} delegates to this object. This implementation
+     * returns a new {@code FileHandlerReloadingDetector} object. Note: This
+     * method is called from a synchronized block.
+     *
+     * @param handler the current {@code FileHandler}
+     * @param fbparams the object with parameters related to file-based builders
+     * @return a {@code ReloadingDetector} for this {@code FileHandler}
+     */
+    protected ReloadingDetector createReloadingDetector(FileHandler handler,
+            FileBasedBuilderParameters fbparams)
+    {
+        return new FileHandlerReloadingDetector(handler,
+                fbparams.getReloadingRefreshDelay());
+    }
+
+    /**
+     * {@inheritDoc} This implementation also takes care that a new
+     * {@code ReloadingDetector} for the new current {@code FileHandler} is
+     * created. Also, the reloading controller's reloading state has to be
+     * reset; after the creation of a new result object changes in the
+     * underlying configuration source have to be monitored again.
+     */
+    @Override
+    protected void initFileHandler(FileHandler handler)
+            throws ConfigurationException
+    {
+        super.initFileHandler(handler);
+
+        resultReloadingDetector =
+                createReloadingDetector(handler,
+                        FileBasedBuilderParameters.fromParameters(
+                                getParameters(), true));
+        getReloadingController().resetReloadingState();
+    }
+
+    /**
+     * Creates the {@code ReloadingController} associated with this object. The
+     * controller is assigned a specialized reloading detector which delegates
+     * to the detector for the current result object. (
+     * {@code FileHandlerReloadingDetector} does not support changing the file
+     * handler, and {@code ReloadingController} does not support changing the
+     * reloading detector; therefore, this level of indirection is needed to
+     * change the monitored file dynamically.)
+     *
+     * @return the new {@code ReloadingController}
+     */
+    private ReloadingController createReloadingController()
+    {
+        ReloadingDetector ctrlDetector = createReloadingDetectorForController();
+        ReloadingController ctrl = new ReloadingController(ctrlDetector);
+        ctrl.addReloadingListener(createReloadingListener());
+        return ctrl;
+    }
+
+    /**
+     * Creates a listener object to be registered at the associated reloading
+     * controller. This listener resets the builder's result object whenever a
+     * change in the monitored file is detected. This will trigger a builder
+     * reset event, and the next time {@code getConfiguration()} is called, a
+     * new result object is created.
+     *
+     * @return the listener for the associated {@code ReloadingController}
+     */
+    private ReloadingListener createReloadingListener()
+    {
+        return new ReloadingListener()
+        {
+            public void reloadingRequired(ReloadingEvent event)
+            {
+                resetResult();
+            }
+        };
+    }
+
+    /**
+     * Creates a {@code ReloadingDetector} wrapper to be passed to the
+     * associated {@code ReloadingController}. This detector wrapper simply
+     * delegates to the current {@code ReloadingDetector} if it is available.
+     *
+     * @return the wrapper {@code ReloadingDetector}
+     */
+    private ReloadingDetector createReloadingDetectorForController()
+    {
+        return new ReloadingDetector()
+        {
+            public void reloadingPerformed()
+            {
+                ReloadingDetector detector = resultReloadingDetector;
+                if (detector != null)
+                {
+                    detector.reloadingPerformed();
+                }
+            }
+
+            public boolean isReloadingRequired()
+            {
+                ReloadingDetector detector = resultReloadingDetector;
+                return (detector != null) ? detector.isReloadingRequired()
+                        : false;
+            }
+        };
+    }
+}

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

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

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

Added: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestReloadingFileBasedConfigurationBuilder.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestReloadingFileBasedConfigurationBuilder.java?rev=1397263&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestReloadingFileBasedConfigurationBuilder.java
(added)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestReloadingFileBasedConfigurationBuilder.java
Thu Oct 11 19:45:48 2012
@@ -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.assertNotSame;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.apache.commons.configuration.ConfigurationException;
+import org.apache.commons.configuration.PropertiesConfiguration;
+import org.apache.commons.configuration.io.FileHandler;
+import org.apache.commons.configuration.reloading.FileHandlerReloadingDetector;
+import org.apache.commons.configuration.reloading.ReloadingDetector;
+import org.easymock.EasyMock;
+import org.junit.Test;
+
+/**
+ * Test class for {@code ReloadingFileBasedConfigurationBuilder}.
+ *
+ * @version $Id$
+ */
+public class TestReloadingFileBasedConfigurationBuilder
+{
+    /**
+     * Tests whether a configuration can be created if no location is set. This
+     * tests also ensures that the super constructor is called correctly.
+     */
+    @Test
+    public void testGetConfigurationNoLocation() throws ConfigurationException
+    {
+        Map<String, Object> params = new HashMap<String, Object>();
+        params.put("throwExceptionOnMissing", Boolean.TRUE);
+        ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration> builder =
+                new ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration>(
+                        PropertiesConfiguration.class, params);
+        PropertiesConfiguration conf = builder.getConfiguration();
+        assertTrue("Property not set", conf.isThrowExceptionOnMissing());
+        assertTrue("Not empty", conf.isEmpty());
+    }
+
+    /**
+     * Tests whether a correct reloading detector is created.
+     */
+    @Test
+    public void testCreateReloadingDetector()
+    {
+        ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration> builder =
+                new ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration>(
+                        PropertiesConfiguration.class);
+        FileHandler handler = new FileHandler();
+        FileBasedBuilderParameters params = new FileBasedBuilderParameters();
+        long refreshDelay = 60000L;
+        params.setReloadingRefreshDelay(refreshDelay);
+        FileHandlerReloadingDetector detector =
+                (FileHandlerReloadingDetector) builder.createReloadingDetector(
+                        handler, params);
+        assertSame("Wrong file handler", handler, detector.getFileHandler());
+        assertEquals("Wrong refresh delay", refreshDelay,
+                detector.getRefreshDelay());
+    }
+
+    /**
+     * Tests the isReloadingRequired() implementation of the detector associated
+     * with the reloading controller.
+     */
+    @Test
+    public void testReloadingDetectorIsReloadingRequired()
+            throws ConfigurationException
+    {
+        ReloadingDetector detector =
+                EasyMock.createMock(ReloadingDetector.class);
+        EasyMock.expect(detector.isReloadingRequired()).andReturn(Boolean.TRUE);
+        EasyMock.expect(detector.isReloadingRequired())
+                .andReturn(Boolean.FALSE);
+        EasyMock.replay(detector);
+        ReloadingFileBasedConfigurationBuilderTestImpl builder =
+                new ReloadingFileBasedConfigurationBuilderTestImpl(detector);
+        builder.getConfiguration();
+        ReloadingDetector ctrlDetector =
+                builder.getReloadingController().getDetector();
+        assertTrue("Wrong result (1)", ctrlDetector.isReloadingRequired());
+        assertFalse("Wrong result (2)", ctrlDetector.isReloadingRequired());
+        assertSame("Wrong file handler", builder.getFileHandler(),
+                builder.getHandlerForDetector());
+        EasyMock.verify(detector);
+    }
+
+    /**
+     * Tests the reloadingPerformed() implementation of the detector associated
+     * with the reloading controller.
+     */
+    @Test
+    public void testReloadingDetectorReloadingPerformed()
+            throws ConfigurationException
+    {
+        ReloadingDetector detector =
+                EasyMock.createMock(ReloadingDetector.class);
+        detector.reloadingPerformed();
+        EasyMock.replay(detector);
+        ReloadingFileBasedConfigurationBuilderTestImpl builder =
+                new ReloadingFileBasedConfigurationBuilderTestImpl(detector);
+        builder.getConfiguration();
+        ReloadingDetector ctrlDetector =
+                builder.getReloadingController().getDetector();
+        ctrlDetector.reloadingPerformed();
+        EasyMock.verify(detector);
+    }
+
+    /**
+     * Tests the behavior of the reloading detector if no underlying detector is
+     * available.
+     */
+    @Test
+    public void testReloadingDetectorNoFileHandler()
+    {
+        ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration> builder =
+                new ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration>(
+                        PropertiesConfiguration.class);
+        ReloadingDetector ctrlDetector =
+                builder.getReloadingController().getDetector();
+        ctrlDetector.reloadingPerformed();
+        assertFalse("Wrong result", ctrlDetector.isReloadingRequired());
+    }
+
+    /**
+     * Tests whether the controller's reloading state is reset when a new result
+     * configuration is created.
+     */
+    @Test
+    public void testResetReloadingStateInGetConfiguration()
+            throws ConfigurationException
+    {
+        ReloadingDetector detector =
+                EasyMock.createMock(ReloadingDetector.class);
+        EasyMock.expect(detector.isReloadingRequired()).andReturn(Boolean.TRUE);
+        detector.reloadingPerformed();
+        EasyMock.replay(detector);
+        ReloadingFileBasedConfigurationBuilderTestImpl builder =
+                new ReloadingFileBasedConfigurationBuilderTestImpl(detector);
+        PropertiesConfiguration config1 = builder.getConfiguration();
+        builder.getReloadingController().checkForReloading(null);
+        PropertiesConfiguration config2 = builder.getConfiguration();
+        assertNotSame("No new configuration instance", config1, config2);
+        assertFalse("Still in reloading state", builder
+                .getReloadingController().isInReloadingState());
+        EasyMock.verify(detector);
+    }
+
+    /**
+     * Tests whether this builder reacts on events fired by the reloading
+     * controller.
+     */
+    @Test
+    public void testReloadingControllerEvents() throws ConfigurationException
+    {
+        ReloadingDetector detector =
+                EasyMock.createMock(ReloadingDetector.class);
+        BuilderListener listener = EasyMock.createMock(BuilderListener.class);
+        EasyMock.expect(detector.isReloadingRequired()).andReturn(Boolean.TRUE);
+        ReloadingFileBasedConfigurationBuilderTestImpl builder =
+                new ReloadingFileBasedConfigurationBuilderTestImpl(detector);
+        listener.builderReset(builder);
+        EasyMock.replay(detector, listener);
+        builder.addBuilderListener(listener);
+        builder.getConfiguration();
+        builder.getReloadingController().checkForReloading(null);
+        EasyMock.verify(detector, listener);
+    }
+
+    /**
+     * A test builder implementation which allows mocking the underlying
+     * reloading detector.
+     */
+    private static class ReloadingFileBasedConfigurationBuilderTestImpl extends
+            ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration>
+    {
+        /** The mock for the reloading detector. */
+        private final ReloadingDetector mockDetector;
+
+        /** Stores the file handler passed to createReloadingDetector(). */
+        private FileHandler handlerForDetector;
+
+        /**
+         * Creates a new instance of
+         * {@code ReloadingFileBasedConfigurationBuilderTestImpl} and
+         * initializes it with a mock reloading detector.
+         *
+         * @param detector the mock detector
+         */
+        public ReloadingFileBasedConfigurationBuilderTestImpl(
+                ReloadingDetector detector)
+        {
+            super(PropertiesConfiguration.class);
+            mockDetector = detector;
+        }
+
+        /**
+         * Returns the file handler that was passed to
+         * createReloadingDetector().
+         *
+         * @return the file handler
+         */
+        public FileHandler getHandlerForDetector()
+        {
+            return handlerForDetector;
+        }
+
+        /**
+         * Returns the mock file handler.
+         */
+        @Override
+        protected ReloadingDetector createReloadingDetector(
+                FileHandler handler, FileBasedBuilderParameters fbparams)
+        {
+            handlerForDetector = handler;
+            return mockDetector;
+        }
+    }
+}

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

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

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



Mime
View raw message