You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2013/11/24 21:37:57 UTC
svn commit: r1545073 - in /commons/proper/configuration/trunk/src:
main/java/org/apache/commons/configuration/builder/fluent/Parameters.java
test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java
Author: oheger
Date: Sun Nov 24 20:37:56 2013
New Revision: 1545073
URL: http://svn.apache.org/r1545073
Log:
Parameters now supports the registration of DefaultParametersHandlers.
The parameters objects created by an instance are now directly initialized with
default values provided by the registered handlers.
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/fluent/Parameters.java
commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java
Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/fluent/Parameters.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/fluent/Parameters.java?rev=1545073&r1=1545072&r2=1545073&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/fluent/Parameters.java (original)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/builder/fluent/Parameters.java Sun Nov 24 20:37:56 2013
@@ -19,6 +19,9 @@ package org.apache.commons.configuration
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
+import java.util.Collection;
+import java.util.LinkedList;
+import java.util.concurrent.CopyOnWriteArrayList;
import org.apache.commons.configuration.builder.BasicBuilderParameters;
import org.apache.commons.configuration.builder.BuilderParameters;
@@ -50,9 +53,9 @@ import org.apache.commons.configuration.
* However, the inheritance structure of the parameter classes makes it
* surprisingly difficult to provide such an API. This class comes to rescue by
* defining a set of methods for the creation of interface-based parameter
- * objects offering a truly fluent API. The methods provided can be
- * called directly when setting up a configuration builder as shown in the
- * following example code fragment:
+ * objects offering a truly fluent API. The methods provided can be called
+ * directly when setting up a configuration builder as shown in the following
+ * example code fragment:
*
* <pre>
* Parameters params = new Parameters();
@@ -62,12 +65,157 @@ import org.apache.commons.configuration.
* </pre>
*
* </p>
+ * <p>
+ * Using this class it is not only possible to create new parameters objects but
+ * also to initialize the newly created objects with default values. This is
+ * achieved by registering objects implementing the
+ * {@link DefaultParametersHandler} interface with the
+ * {@code registerDefaultsHandler()} method. The handler object is then called
+ * whenever a parameters object of the supported class (or one of its
+ * subclasses) is created. This makes it easy to define default settings that
+ * are applied for all parameters object created by this {@code Parameters}
+ * instance.
+ * </p>
+ * <p>
+ * Implementation note: This class is thread-safe.
+ * </p>
*
* @version $Id$
* @since 2.0
*/
public final class Parameters
{
+ /** A collection with the registered default handlers. */
+ private final Collection<DefaultHandlerData> defaultHandlers;
+
+ /**
+ * Creates a new instance of {@code Parameters}.
+ */
+ public Parameters()
+ {
+ 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 new parameters object of the specified class or one of its
+ * subclasses is created. 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 Parameters} 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);
+ }
+
/**
* Creates a new instance of a parameters object for basic configuration
* properties.
@@ -177,8 +325,35 @@ public final class Parameters
}
/**
+ * 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. It is not necessary to call this method
+ * for parameter objects that have been created by this {@code Parameters}
+ * instance - in this case, it is called automatically. However, if a
+ * parameters object was created by another source, this method can be used
+ * to apply the {@code DefaultParametersHandler} objects which have been
+ * registered here.
+ *
+ * @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);
+ }
+ }
+ }
+
+ /**
* Creates a proxy object for a given parameters interface based on the
- * given implementation object.
+ * given implementation object. The newly created object is initialized
+ * with default values if there are matching {@link DefaultParametersHandler}
+ * objects.
*
* @param <T> the type of the parameters interface
* @param target the implementing target object
@@ -187,15 +362,17 @@ public final class Parameters
* implemented
* @return the proxy object
*/
- private static <T> T createParametersProxy(Object target,
- Class<T> ifcClass, Class<?>... superIfcs)
+ private <T> T createParametersProxy(Object target, Class<T> ifcClass,
+ Class<?>... superIfcs)
{
Class<?>[] ifcClasses = new Class<?>[1 + superIfcs.length];
ifcClasses[0] = ifcClass;
System.arraycopy(superIfcs, 0, ifcClasses, 1, superIfcs.length);
- return ifcClass.cast(Proxy.newProxyInstance(
- Parameters.class.getClassLoader(), ifcClasses,
- new ParametersIfcInvocationHandler(target)));
+ Object obj =
+ Proxy.newProxyInstance(Parameters.class.getClassLoader(),
+ ifcClasses, new ParametersIfcInvocationHandler(target));
+ initializeParameters((BuilderParameters) obj);
+ return ifcClass.cast(obj);
}
/**
@@ -251,4 +428,71 @@ public final class Parameters
&& !declaringClass.equals(BuilderParameters.class);
}
}
+
+ /**
+ * 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));
+ }
+ }
}
Modified: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java?rev=1545073&r1=1545072&r2=1545073&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java (original)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/builder/fluent/TestParameters.java Sun Nov 24 20:37:56 2013
@@ -17,7 +17,9 @@
package org.apache.commons.configuration.builder.fluent;
import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
import static org.junit.Assert.assertSame;
import static org.junit.Assert.assertTrue;
@@ -44,6 +46,9 @@ import org.junit.Test;
*/
public class TestParameters
{
+ /** A default encoding. */
+ private static final String DEF_ENCODING = "UTF-8";
+
/** A test list delimiter handler. */
private static ListDelimiterHandler listHandler;
@@ -94,13 +99,13 @@ public class TestParameters
{
Map<String, Object> map =
parameters.fileBased().setThrowExceptionOnMissing(true)
- .setEncoding("UTF-8").setListDelimiterHandler(listHandler)
+ .setEncoding(DEF_ENCODING).setListDelimiterHandler(listHandler)
.setFileName("test.xml").getParameters();
FileBasedBuilderParametersImpl fbparams =
FileBasedBuilderParametersImpl.fromParameters(map);
assertEquals("Wrong file name", "test.xml", fbparams.getFileHandler()
.getFileName());
- assertEquals("Wrong encoding", "UTF-8", fbparams.getFileHandler()
+ assertEquals("Wrong encoding", DEF_ENCODING, fbparams.getFileHandler()
.getEncoding());
checkBasicProperties(map);
}
@@ -350,4 +355,198 @@ public class TestParameters
checkBasicProperties(map);
assertSame("Wrong expression engine", engine, map.get("expressionEngine"));
}
+
+ /**
+ * Tries to register a default handler without a class.
+ */
+ @Test(expected = IllegalArgumentException.class)
+ public void testRegisterDefaultsHandlerNoClass()
+ {
+ parameters
+ .registerDefaultsHandler(null, new FileBasedDefaultsHandler());
+ }
+
+ /**
+ * Tries to register a null default handler.
+ */
+ @Test(expected = IllegalArgumentException.class)
+ public void testRegisterDefaultsHandlerNoHandler()
+ {
+ parameters.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)
+ {
+ checkBasicProperties(map);
+ 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()
+ {
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler());
+ Map<String, Object> map = parameters.fileBased().getParameters();
+ checkDefaultValues(map);
+ }
+
+ /**
+ * Tests whether default values are also applied when a sub parameters class
+ * is created.
+ */
+ @Test
+ public void testApplyDefaultsOnSubClass()
+ {
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler());
+ Map<String, Object> map = parameters.xml().getParameters();
+ checkDefaultValues(map);
+ }
+
+ /**
+ * Tests that default values are only applied if the start class provided at
+ * registration time matches.
+ */
+ @Test
+ public void testApplyDefaultsStartClass()
+ {
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler(), XMLBuilderParameters.class);
+ Map<String, Object> map = parameters.xml().getParameters();
+ checkDefaultValues(map);
+ map = parameters.properties().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);
+ parameters.registerDefaultsHandler(XMLBuilderParameters.class,
+ new DefaultParametersHandler<XMLBuilderParameters>()
+ {
+ public void initializeDefaults(
+ XMLBuilderParameters parameters)
+ {
+ parameters
+ .setThrowExceptionOnMissing(false)
+ .setListDelimiterHandler(
+ EasyMock.createMock(ListDelimiterHandler.class))
+ .setExpressionEngine(engine);
+ }
+ });
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler());
+ Map<String, Object> map = parameters.xml().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()
+ {
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler());
+ parameters.initializeParameters(null);
+ }
+
+ /**
+ * Tests whether a parameters object created externally can be initialized.
+ */
+ @Test
+ public void testInitializeParameters()
+ {
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ new FileBasedDefaultsHandler());
+ XMLBuilderParameters params = new Parameters().xml();
+ parameters.initializeParameters(params);
+ checkDefaultValues(params.getParameters());
+ }
+
+ /**
+ * Tests whether all occurrences of a given defaults handler can be removed.
+ */
+ @Test
+ public void testUnregisterDefaultsHandlerAll()
+ {
+ FileBasedDefaultsHandler handler = new FileBasedDefaultsHandler();
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ handler, XMLBuilderParameters.class);
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ handler, PropertiesBuilderParameters.class);
+ parameters.unregisterDefaultsHandler(handler);
+ checkNoDefaultValues(parameters.fileBased().getParameters());
+ checkNoDefaultValues(parameters.xml().getParameters());
+ checkNoDefaultValues(parameters.properties().getParameters());
+ }
+
+ /**
+ * Tests whether a specific occurrence of a defaults handler can be removed.
+ */
+ @Test
+ public void testUnregisterDefaultsHandlerSpecific()
+ {
+ FileBasedDefaultsHandler handler = new FileBasedDefaultsHandler();
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ handler, XMLBuilderParameters.class);
+ parameters.registerDefaultsHandler(FileBasedBuilderParameters.class,
+ handler, PropertiesBuilderParameters.class);
+ parameters.unregisterDefaultsHandler(handler,
+ PropertiesBuilderParameters.class);
+ checkDefaultValues(parameters.xml().getParameters());
+ checkNoDefaultValues(parameters.properties().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);
+ }
+ }
}