DefaultParametersManager.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.configuration2.builder;

  18. import java.util.Collection;
  19. import java.util.concurrent.CopyOnWriteArrayList;

  20. /**
  21.  * <p>
  22.  * A class for managing a set of {@link DefaultParametersHandler} objects.
  23.  * </p>
  24.  * <p>
  25.  * This class provides functionality for registering and removing {@code DefaultParametersHandler} objects for arbitrary
  26.  * parameters classes. The handlers registered at an instance can then be applied on a passed in parameters object, so
  27.  * that it gets initialized with the provided default values.
  28.  * </p>
  29.  * <p>
  30.  * Usage of this class is as follows: First the {@code DefaultParametersHandler} objects to be supported must be
  31.  * registered using one of the {@code registerDefaultHandler()} methods. After that arbitrary parameters objects can be
  32.  * passed to the {@code initializeParameters()} method. This causes all {@code DefaultParametersHandler} objects
  33.  * supporting this parameters class to be invoked on this object.
  34.  * </p>
  35.  * <p>
  36.  * Implementation note: This class is thread-safe.
  37.  * </p>
  38.  *
  39.  * @since 2.0
  40.  */
  41. public class DefaultParametersManager {
  42.     /**
  43.      * A data class storing information about {@code DefaultParametersHandler} objects added to a {@code Parameters} object.
  44.      * Using this class it is possible to find out which default handlers apply for a given parameters object and to invoke
  45.      * them.
  46.      */
  47.     private static final class DefaultHandlerData {
  48.         /** The handler object. */
  49.         private final DefaultParametersHandler<?> handler;

  50.         /** The class supported by this handler. */
  51.         private final Class<?> parameterClass;

  52.         /** The start class for applying this handler. */
  53.         private final Class<?> startClass;

  54.         /**
  55.          * Creates a new instance of {@code DefaultHandlerData}.
  56.          *
  57.          * @param h the {@code DefaultParametersHandler}
  58.          * @param cls the handler's data class
  59.          * @param startCls the start class
  60.          */
  61.         public DefaultHandlerData(final DefaultParametersHandler<?> h, final Class<?> cls, final Class<?> startCls) {
  62.             handler = h;
  63.             parameterClass = cls;
  64.             startClass = startCls;
  65.         }

  66.         /**
  67.          * Checks whether the managed {@code DefaultParametersHandler} can be applied to the given parameters object. If this is
  68.          * the case, it is executed on this object and can initialize it with default values.
  69.          *
  70.          * @param obj the parameters object to be initialized
  71.          */
  72.         @SuppressWarnings("unchecked")
  73.         // There are explicit isInstance() checks, so there won't be
  74.         // ClassCastExceptions
  75.         public void applyHandlerIfMatching(final BuilderParameters obj) {
  76.             if (parameterClass.isInstance(obj) && (startClass == null || startClass.isInstance(obj))) {
  77.                 @SuppressWarnings("rawtypes")
  78.                 final DefaultParametersHandler handlerUntyped = handler;
  79.                 handlerUntyped.initializeDefaults(obj);
  80.             }
  81.         }

  82.         /**
  83.          * Tests whether this instance refers to the specified occurrence of a {@code DefaultParametersHandler}.
  84.          *
  85.          * @param h the handler to be checked
  86.          * @param startCls the start class
  87.          * @return <strong>true</strong> if this instance refers to this occurrence, <strong>false</strong> otherwise
  88.          */
  89.         public boolean isOccurrence(final DefaultParametersHandler<?> h, final Class<?> startCls) {
  90.             return h == handler && (startCls == null || startCls.equals(startClass));
  91.         }
  92.     }

  93.     /** A collection with the registered default handlers. */
  94.     private final Collection<DefaultHandlerData> defaultHandlers;

  95.     /**
  96.      * Creates a new instance of {@code DefaultParametersManager}.
  97.      */
  98.     public DefaultParametersManager() {
  99.         defaultHandlers = new CopyOnWriteArrayList<>();
  100.     }

  101.     /**
  102.      * Initializes the passed in {@code BuilderParameters} object by applying all matching {@link DefaultParametersHandler}
  103.      * objects registered at this instance. Using this method the passed in parameters object can be populated with default
  104.      * values.
  105.      *
  106.      * @param params the parameters object to be initialized (may be <strong>null</strong>, then this method has no effect)
  107.      */
  108.     public void initializeParameters(final BuilderParameters params) {
  109.         if (params != null) {
  110.             defaultHandlers.forEach(dhd -> dhd.applyHandlerIfMatching(params));
  111.         }
  112.     }

  113.     /**
  114.      * Registers the specified {@code DefaultParametersHandler} object for the given parameters class. This means that this
  115.      * handler object is invoked every time a parameters object of the specified class or one of its subclasses is
  116.      * initialized. The handler can set arbitrary default values for the properties supported by this parameters object. If
  117.      * there are multiple handlers registered supporting a specific parameters class, they are invoked in the order in which
  118.      * they were registered. So handlers registered later may override the values set by handlers registered earlier.
  119.      *
  120.      * @param <T> the type of the parameters supported by this handler
  121.      * @param paramsClass the parameters class supported by this handler (must not be <strong>null</strong>)
  122.      * @param handler the {@code DefaultParametersHandler} to be registered (must not be <strong>null</strong>)
  123.      * @throws IllegalArgumentException if a required parameter is missing
  124.      */
  125.     public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler) {
  126.         registerDefaultsHandler(paramsClass, handler, null);
  127.     }

  128.     /**
  129.      * Registers the specified {@code DefaultParametersHandler} object for the given parameters class and start class in the
  130.      * inheritance hierarchy. This method works like {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}, but
  131.      * the defaults handler is only executed on parameter objects that are instances of the specified start class. Parameter
  132.      * classes do not stand in a real inheritance hierarchy; however, there is a logic hierarchy defined by the methods
  133.      * supported by the different parameter objects. A properties parameter object for instance supports all methods defined
  134.      * for a file-based parameter object. So one can argue that
  135.      * {@link org.apache.commons.configuration2.builder.fluent.FileBasedBuilderParameters FileBasedBuilderParameters} is a
  136.      * base interface of {@link org.apache.commons.configuration2.builder.fluent.PropertiesBuilderParameters
  137.      * PropertiesBuilderParameters} (although, for technical reasons, this relation is not reflected in the Java classes). A
  138.      * {@link DefaultParametersHandler} object defined for a base interface can also deal with parameter objects "derived"
  139.      * from this base interface (i.e. supporting a super set of the methods defined by the base interface). Now there may be
  140.      * the use case that there is an implementation of {@code DefaultParametersHandler} for a base interface (for example
  141.      * {@code FileBasedBuilderParameters}), but it should only process specific derived interfaces (say
  142.      * {@code PropertiesBuilderParameters}, but not
  143.      * {@link org.apache.commons.configuration2.builder.fluent.XMLBuilderParameters XMLBuilderParameters}). This can be
  144.      * achieved by passing in {@code PropertiesBuilderParameters} as start class. In this case,
  145.      * {@code DefaultParametersManager} ensures that the handler is only called on parameter objects having both the start
  146.      * class and the actual type supported by the handler as base interfaces. The passed in start class can be <strong>null</strong>;
  147.      * then the parameter class supported by the handler is used (which is the default behavior of the
  148.      * {@link #registerDefaultsHandler(Class, DefaultParametersHandler)} method).
  149.      *
  150.      * @param <T> the type of the parameters supported by this handler
  151.      * @param paramsClass the parameters class supported by this handler (must not be <strong>null</strong>)
  152.      * @param handler the {@code DefaultParametersHandler} to be registered (must not be <strong>null</strong>)
  153.      * @param startClass an optional start class in the hierarchy of parameter objects for which this handler should be
  154.      *        applied
  155.      * @throws IllegalArgumentException if a required parameter is missing
  156.      */
  157.     public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler, final Class<?> startClass) {
  158.         if (paramsClass == null) {
  159.             throw new IllegalArgumentException("Parameters class must not be null!");
  160.         }
  161.         if (handler == null) {
  162.             throw new IllegalArgumentException("DefaultParametersHandler must not be null!");
  163.         }
  164.         defaultHandlers.add(new DefaultHandlerData(handler, paramsClass, startClass));
  165.     }

  166.     /**
  167.      * Removes the specified {@code DefaultParametersHandler} from this instance. If this handler has been registered
  168.      * multiple times for different start classes, all occurrences are removed.
  169.      *
  170.      * @param handler the {@code DefaultParametersHandler} to be removed
  171.      */
  172.     public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler) {
  173.         unregisterDefaultsHandler(handler, null);
  174.     }

  175.     /**
  176.      * Removes the specified {@code DefaultParametersHandler} from this instance if it is in combination with the given
  177.      * start class. If this handler has been registered multiple times for different start classes, only occurrences for the
  178.      * given start class are removed. The {@code startClass} parameter can be <strong>null</strong>, then all occurrences of the
  179.      * handler are removed.
  180.      *
  181.      * @param handler the {@code DefaultParametersHandler} to be removed
  182.      * @param startClass the start class for which this handler is to be removed
  183.      */
  184.     public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler, final Class<?> startClass) {
  185.         defaultHandlers.removeIf(dhd -> dhd.isOccurrence(handler, startClass));
  186.     }
  187. }