Package org.apache.commons.configuration2.builder

Class DefaultParametersManager

java.lang.Object
org.apache.commons.configuration2.builder.DefaultParametersManager
public class DefaultParametersManager extends Object

A class for managing a set of DefaultParametersHandler objects.

This class provides functionality for registering and removing 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 DefaultParametersHandler objects to be supported must be registered using one of the registerDefaultHandler() methods. After that arbitrary parameters objects can be passed to the initializeParameters() method. This causes all DefaultParametersHandler objects supporting this parameters class to be invoked on this object.

Implementation note: This class is thread-safe.

Since:
2.0

  • Constructor Details

  • Method Details

    • initializeParameters

      public void initializeParameters(BuilderParameters params)
      Initializes the passed in BuilderParameters object by applying all matching DefaultParametersHandler objects registered at this instance. Using this method the passed in parameters object can be populated with default values.
      Parameters:
      params - the parameters object to be initialized (may be null, then this method has no effect)

    • registerDefaultsHandler

      public <T> void registerDefaultsHandler(Class<T> paramsClass, DefaultParametersHandler<? super T> handler)
      Registers the specified 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.
      Type Parameters:
      T - the type of the parameters supported by this handler
      Parameters:
      paramsClass - the parameters class supported by this handler (must not be null)
      handler - the DefaultParametersHandler to be registered (must not be null)
      Throws:
      IllegalArgumentException - if a required parameter is missing

    • registerDefaultsHandler

      public <T> void registerDefaultsHandler(Class<T> paramsClass, DefaultParametersHandler<? super T> handler, Class<?> startClass)
      Registers the specified DefaultParametersHandler object for the given parameters class and start class in the inheritance hierarchy. This method works like 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 FileBasedBuilderParameters is a base interface of PropertiesBuilderParameters (although, for technical reasons, this relation is not reflected in the Java classes). A 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 DefaultParametersHandler for a base interface (e.g. FileBasedBuilderParameters), but it should only process specific derived interfaces (say PropertiesBuilderParameters, but not XMLBuilderParameters). This can be achieved by passing in PropertiesBuilderParameters as start class. In this case, 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 registerDefaultsHandler(Class, DefaultParametersHandler) method).
      Type Parameters:
      T - the type of the parameters supported by this handler
      Parameters:
      paramsClass - the parameters class supported by this handler (must not be null)
      handler - the DefaultParametersHandler to be registered (must not be null)
      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

    • unregisterDefaultsHandler

      public void unregisterDefaultsHandler(DefaultParametersHandler<?> handler)
      Removes the specified DefaultParametersHandler from this instance. If this handler has been registered multiple times for different start classes, all occurrences are removed.
      Parameters:
      handler - the DefaultParametersHandler to be removed

    • unregisterDefaultsHandler

      public void unregisterDefaultsHandler(DefaultParametersHandler<?> handler, Class<?> startClass)
      Removes the specified 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 startClass parameter can be null, then all occurrences of the handler are removed.
      Parameters:
      handler - the DefaultParametersHandler to be removed
      startClass - the start class for which this handler is to be removed