svn commit: r1612662 - in /commons/proper/configuration/trunk/src: main/java/org/apache/commons/configuration/builder/EventListenerParameters.java test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java

[oh...@apache.org]

Author: oheger
Date: Tue Jul 22 19:57:47 2014
New Revision: 1612662

URL: http://svn.apache.org/r1612662
Log:
Added new EventListenerParameters class.

This is an implementation of the EventListenerProvider interface providing a
convenient API to define the event listeners of a configuration builder.
Instances of this class can be passed to a builder's configure() method.

Added:
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/EventListenerParameters.java
    commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java

Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/EventListenerParameters.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/EventListenerParameters.java?rev=1612662&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/EventListenerParameters.java (added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/EventListenerParameters.java Tue Jul 22 19:57:47 2014
@@ -0,0 +1,119 @@
+/*
+ * 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.Collections;
+import java.util.Map;
+
+import org.apache.commons.configuration.event.Event;
+import org.apache.commons.configuration.event.EventListener;
+import org.apache.commons.configuration.event.EventListenerList;
+import org.apache.commons.configuration.event.EventListenerRegistrationData;
+import org.apache.commons.configuration.event.EventType;
+
+/**
+ * <p>
+ * A specialized parameters implementation for {@link BasicConfigurationBuilder}
+ * which allows for a convenient event listener initialization.
+ * </p>
+ * <p>
+ * This class offers a fluent interface for registering event listeners. A fully
+ * initialized instance can be passed to the
+ * {@link BasicConfigurationBuilder#configure(BuilderParameters...)} method. All
+ * event listeners which have been registered at the instance are then copied
+ * over to the configuration builder.
+ * </p>
+ * <p>
+ * The code fragment below shows a typical usage scenario:
+ *
+ * <pre>
+ * BasicConfigurationBuilder&lt;Configuration&gt; builder =
+ *         new BasicConfigurationBuilder&lt;Configuration&gt;(
+ *                 PropertiesConfiguration.class)
+ *                 .configure(new EventListenerParameters().addEventListener(
+ *                         ConfigurationEvent.ANY, myListener));
+ * </pre>
+ *
+ * </p>
+ * <p>
+ * In order to support a configuration builder's {@code configure()} method,
+ * this class implements the {@code BuilderParameters} interface. However, this
+ * is just a dummy implementation; no parameters are propagated to the builder.
+ * </p>
+ *
+ * @version $Id$
+ * @since 2.0
+ */
+public class EventListenerParameters implements BuilderParameters,
+        EventListenerProvider
+{
+    /** Stores the event listener registrations added to this object. */
+    private final EventListenerList eventListeners;
+
+    /**
+     * Creates a new instance of {@code EventListenerParameters}.
+     */
+    public EventListenerParameters()
+    {
+        eventListeners = new EventListenerList();
+    }
+
+    /**
+     * Adds an event listener of the specified event type to this object.
+     *
+     * @param eventType the event type object
+     * @param listener the event listener
+     * @param <T> the event type
+     * @return a reference to this object for method chaining
+     */
+    public <T extends Event> EventListenerParameters addEventListener(
+            EventType<T> eventType, EventListener<? super T> listener)
+    {
+        eventListeners.addEventListener(eventType, listener);
+        return this;
+    }
+
+    /**
+     * Adds the specified {@code EventListenerRegistrationData} instance to this
+     * object.
+     *
+     * @param registrationData the registration object to be added
+     * @param <T> the event type of the contained event listener
+     * @return a reference to this object for method chaining
+     */
+    public <T extends Event> EventListenerParameters addEventListener(
+            EventListenerRegistrationData<T> registrationData)
+    {
+        eventListeners.addEventListener(registrationData);
+        return this;
+    }
+
+    /**
+     * {@inheritDoc} This implementation returns an empty map.
+     */
+    @Override
+    public Map<String, Object> getParameters()
+    {
+        return Collections.emptyMap();
+    }
+
+    @Override
+    public EventListenerList getListeners()
+    {
+        return eventListeners;
+    }
+}

Added: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java?rev=1612662&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java (added)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/TestEventListenerParameters.java Tue Jul 22 19:57:47 2014
@@ -0,0 +1,93 @@
+/*
+ * 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.assertSame;
+import static org.junit.Assert.assertTrue;
+
+import org.apache.commons.configuration.event.ConfigurationEvent;
+import org.apache.commons.configuration.event.EventListenerRegistrationData;
+import org.apache.commons.configuration.event.EventListenerTestImpl;
+import org.junit.Test;
+
+/**
+ * Test class for {@code EventListenerParameters}.
+ *
+ * @version $Id$
+ */
+public class TestEventListenerParameters
+{
+    /**
+     * Tests the map with parameters.
+     */
+    @Test
+    public void testGetParameters()
+    {
+        EventListenerParameters parameters = new EventListenerParameters();
+        assertTrue("Got parameters", parameters.getParameters().isEmpty());
+    }
+
+    /**
+     * Tests that the list of event listeners is empty for a newly created
+     * instance.
+     */
+    @Test
+    public void testRegistrationsAfterCreation()
+    {
+        EventListenerParameters parameters = new EventListenerParameters();
+        assertTrue("Got registrations", parameters.getListeners()
+                .getRegistrations().isEmpty());
+    }
+
+    /**
+     * Tests whether an event listener with its type can be added.
+     */
+    @Test
+    public void testAddEventListener()
+    {
+        EventListenerTestImpl listener = new EventListenerTestImpl(null);
+        EventListenerParameters parameters = new EventListenerParameters();
+        assertSame("Wrong result", parameters, parameters.addEventListener(
+                ConfigurationEvent.ADD_PROPERTY, listener));
+        assertEquals("Wrong number of registrations", 1, parameters
+                .getListeners().getRegistrations().size());
+        EventListenerRegistrationData<?> reg =
+                parameters.getListeners().getRegistrations().get(0);
+        assertEquals("Wrong event type", ConfigurationEvent.ADD_PROPERTY,
+                reg.getEventType());
+        assertEquals("Wrong listener", listener, reg.getListener());
+    }
+
+    /**
+     * Tests whether an event listener registration can be added.
+     */
+    @Test
+    public void testAddEventListenerRegistration()
+    {
+        EventListenerRegistrationData<ConfigurationEvent> reg =
+                new EventListenerRegistrationData<ConfigurationEvent>(
+                        ConfigurationEvent.SET_PROPERTY,
+                        new EventListenerTestImpl(null));
+        EventListenerParameters parameters = new EventListenerParameters();
+        assertSame("Wrong result", parameters, parameters.addEventListener(reg));
+        assertEquals("Wrong number of registrations", 1, parameters
+                .getListeners().getRegistrations().size());
+        assertEquals("Wrong registration", reg, parameters.getListeners()
+                .getRegistrations().get(0));
+    }
+}