org.apache.commons.configuration2.builder.DefaultParametersManager Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in
various formats
/*
* 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.configuration2.builder;
import java.util.Collection;
import java.util.LinkedList;
import java.util.concurrent.CopyOnWriteArrayList;
/**
*
* A class for managing a set of {@link DefaultParametersHandler} objects.
*
*
* 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.
*
*
* 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.
*
*
* Implementation note: This class is thread-safe.
*
*
* @since 2.0
*/
public class DefaultParametersManager
{
/** A collection with the registered default handlers. */
private final Collection defaultHandlers;
/**
* Creates a new instance of {@code DefaultParametersManager}.
*/
public DefaultParametersManager()
{
defaultHandlers = new CopyOnWriteArrayList<>();
}
/**
* 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 the type of the parameters supported by this handler
* @param paramsClass the parameters class supported by this handler (must
* not be null)
* @param handler the {@code DefaultParametersHandler} to be registered
* (must not be null)
* @throws IllegalArgumentException if a required parameter is missing
*/
public void registerDefaultsHandler(final Class paramsClass,
final DefaultParametersHandler 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 org.apache.commons.configuration2.builder.fluent.FileBasedBuilderParameters
* FileBasedBuilderParameters} is a base interface of
* {@link org.apache.commons.configuration2.builder.fluent.PropertiesBuilderParameters
* 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 org.apache.commons.configuration2.builder.fluent.XMLBuilderParameters
* 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 null; then the parameter class supported by the handler is
* used (which is the default behavior of the
* {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}
* method).
*
* @param the type of the parameters supported by this handler
* @param paramsClass the parameters class supported by this handler (must
* not be null)
* @param handler the {@code DefaultParametersHandler} to be registered
* (must not be null)
* @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 void registerDefaultsHandler(final Class paramsClass,
final DefaultParametersHandler handler, final 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(final 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 null, 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(final DefaultParametersHandler handler,
final Class startClass)
{
final Collection toRemove =
new LinkedList<>();
for (final 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
* null, then this method has no effect)
*/
public void initializeParameters(final BuilderParameters params)
{
if (params != null)
{
for (final 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(final DefaultParametersHandler h, final Class cls,
final 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(final BuilderParameters obj)
{
if (parameterClass.isInstance(obj)
&& (startClass == null || startClass.isInstance(obj)))
{
@SuppressWarnings("rawtypes")
final
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 true if this instance refers to this occurrence,
* false otherwise
*/
public boolean isOccurrence(final DefaultParametersHandler h,
final Class startCls)
{
return h == handler
&& (startCls == null || startCls.equals(startClass));
}
}
}