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 Summary

  Constructors
  Constructor
  Description
  `DefaultParametersManager()`
  Creates a new instance of `DefaultParametersManager`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `initializeParameters(BuilderParameters params)`
  Initializes the passed in `BuilderParameters` object by applying all matching `DefaultParametersHandler` objects registered at this instance.
  `<T> void`
  `registerDefaultsHandler(Class<T> paramsClass, DefaultParametersHandler<? super T> handler)`
  Registers the specified `DefaultParametersHandler` object for the given parameters class.
  `<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.
  `void`
  `unregisterDefaultsHandler(DefaultParametersHandler<?> handler)`
  Removes the specified `DefaultParametersHandler` from this instance.
  `void`
  `unregisterDefaultsHandler(DefaultParametersHandler<?> handler, Class<?> startClass)`
  Removes the specified `DefaultParametersHandler` from this instance if it is in combination with the given start class.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DefaultParametersManager

    public DefaultParametersManager()
    Creates a new instance of `DefaultParametersManager`.

- ## 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 (for example `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