View Javadoc
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  
19  import java.util.Collection;
20  import java.util.concurrent.CopyOnWriteArrayList;
21  
22  /**
23   * <p>
24   * A class for managing a set of {@link DefaultParametersHandler} objects.
25   * </p>
26   * <p>
27   * This class provides functionality for registering and removing {@code DefaultParametersHandler} objects for arbitrary
28   * parameters classes. The handlers registered at an instance can then be applied on a passed in parameters object, so
29   * that it gets initialized with the provided default values.
30   * </p>
31   * <p>
32   * Usage of this class is as follows: First the {@code DefaultParametersHandler} objects to be supported must be
33   * registered using one of the {@code registerDefaultHandler()} methods. After that arbitrary parameters objects can be
34   * passed to the {@code initializeParameters()} method. This causes all {@code DefaultParametersHandler} objects
35   * supporting this parameters class to be invoked on this object.
36   * </p>
37   * <p>
38   * Implementation note: This class is thread-safe.
39   * </p>
40   *
41   * @since 2.0
42   */
43  public class DefaultParametersManager {
44      /** A collection with the registered default handlers. */
45      private final Collection<DefaultHandlerData> defaultHandlers;
46  
47      /**
48       * Creates a new instance of {@code DefaultParametersManager}.
49       */
50      public DefaultParametersManager() {
51          defaultHandlers = new CopyOnWriteArrayList<>();
52      }
53  
54      /**
55       * Registers the specified {@code DefaultParametersHandler} object for the given parameters class. This means that this
56       * handler object is invoked every time a parameters object of the specified class or one of its subclasses is
57       * initialized. The handler can set arbitrary default values for the properties supported by this parameters object. If
58       * there are multiple handlers registered supporting a specific parameters class, they are invoked in the order in which
59       * they were registered. So handlers registered later may override the values set by handlers registered earlier.
60       *
61       * @param <T> the type of the parameters supported by this handler
62       * @param paramsClass the parameters class supported by this handler (must not be <b>null</b>)
63       * @param handler the {@code DefaultParametersHandler} to be registered (must not be <b>null</b>)
64       * @throws IllegalArgumentException if a required parameter is missing
65       */
66      public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler) {
67          registerDefaultsHandler(paramsClass, handler, null);
68      }
69  
70      /**
71       * Registers the specified {@code DefaultParametersHandler} object for the given parameters class and start class in the
72       * inheritance hierarchy. This method works like {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}, but
73       * the defaults handler is only executed on parameter objects that are instances of the specified start class. Parameter
74       * classes do not stand in a real inheritance hierarchy; however, there is a logic hierarchy defined by the methods
75       * supported by the different parameter objects. A properties parameter object for instance supports all methods defined
76       * for a file-based parameter object. So one can argue that
77       * {@link org.apache.commons.configuration2.builder.fluent.FileBasedBuilderParameters FileBasedBuilderParameters} is a
78       * base interface of {@link org.apache.commons.configuration2.builder.fluent.PropertiesBuilderParameters
79       * PropertiesBuilderParameters} (although, for technical reasons, this relation is not reflected in the Java classes). A
80       * {@link DefaultParametersHandler} object defined for a base interface can also deal with parameter objects "derived"
81       * from this base interface (i.e. supporting a super set of the methods defined by the base interface). Now there may be
82       * the use case that there is an implementation of {@code DefaultParametersHandler} for a base interface (e.g.
83       * {@code FileBasedBuilderParameters}), but it should only process specific derived interfaces (say
84       * {@code PropertiesBuilderParameters}, but not
85       * {@link org.apache.commons.configuration2.builder.fluent.XMLBuilderParameters XMLBuilderParameters}). This can be
86       * achieved by passing in {@code PropertiesBuilderParameters} as start class. In this case,
87       * {@code DefaultParametersManager} ensures that the handler is only called on parameter objects having both the start
88       * class and the actual type supported by the handler as base interfaces. The passed in start class can be <b>null</b>;
89       * then the parameter class supported by the handler is used (which is the default behavior of the
90       * {@link #registerDefaultsHandler(Class, DefaultParametersHandler)} method).
91       *
92       * @param <T> the type of the parameters supported by this handler
93       * @param paramsClass the parameters class supported by this handler (must not be <b>null</b>)
94       * @param handler the {@code DefaultParametersHandler} to be registered (must not be <b>null</b>)
95       * @param startClass an optional start class in the hierarchy of parameter objects for which this handler should be
96       *        applied
97       * @throws IllegalArgumentException if a required parameter is missing
98       */
99      public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler, final Class<?> startClass) {
100         if (paramsClass == null) {
101             throw new IllegalArgumentException("Parameters class must not be null!");
102         }
103         if (handler == null) {
104             throw new IllegalArgumentException("DefaultParametersHandler must not be null!");
105         }
106         defaultHandlers.add(new DefaultHandlerData(handler, paramsClass, startClass));
107     }
108 
109     /**
110      * Removes the specified {@code DefaultParametersHandler} from this instance. If this handler has been registered
111      * multiple times for different start classes, all occurrences are removed.
112      *
113      * @param handler the {@code DefaultParametersHandler} to be removed
114      */
115     public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler) {
116         unregisterDefaultsHandler(handler, null);
117     }
118 
119     /**
120      * Removes the specified {@code DefaultParametersHandler} from this instance if it is in combination with the given
121      * start class. If this handler has been registered multiple times for different start classes, only occurrences for the
122      * given start class are removed. The {@code startClass} parameter can be <b>null</b>, then all occurrences of the
123      * handler are removed.
124      *
125      * @param handler the {@code DefaultParametersHandler} to be removed
126      * @param startClass the start class for which this handler is to be removed
127      */
128     public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler, final Class<?> startClass) {
129         defaultHandlers.removeIf(dhd -> dhd.isOccurrence(handler, startClass));
130     }
131 
132     /**
133      * Initializes the passed in {@code BuilderParameters} object by applying all matching {@link DefaultParametersHandler}
134      * objects registered at this instance. Using this method the passed in parameters object can be populated with default
135      * values.
136      *
137      * @param params the parameters object to be initialized (may be <b>null</b>, then this method has no effect)
138      */
139     public void initializeParameters(final BuilderParameters params) {
140         if (params != null) {
141             defaultHandlers.forEach(dhd -> dhd.applyHandlerIfMatching(params));
142         }
143     }
144 
145     /**
146      * A data class storing information about {@code DefaultParametersHandler} objects added to a {@code Parameters} object.
147      * Using this class it is possible to find out which default handlers apply for a given parameters object and to invoke
148      * them.
149      */
150     private static final class DefaultHandlerData {
151         /** The handler object. */
152         private final DefaultParametersHandler<?> handler;
153 
154         /** The class supported by this handler. */
155         private final Class<?> parameterClass;
156 
157         /** The start class for applying this handler. */
158         private final Class<?> startClass;
159 
160         /**
161          * Creates a new instance of {@code DefaultHandlerData}.
162          *
163          * @param h the {@code DefaultParametersHandler}
164          * @param cls the handler's data class
165          * @param startCls the start class
166          */
167         public DefaultHandlerData(final DefaultParametersHandler<?> h, final Class<?> cls, final Class<?> startCls) {
168             handler = h;
169             parameterClass = cls;
170             startClass = startCls;
171         }
172 
173         /**
174          * Checks whether the managed {@code DefaultParametersHandler} can be applied to the given parameters object. If this is
175          * the case, it is executed on this object and can initialize it with default values.
176          *
177          * @param obj the parameters object to be initialized
178          */
179         @SuppressWarnings("unchecked")
180         // There are explicit isInstance() checks, so there won't be
181         // ClassCastExceptions
182         public void applyHandlerIfMatching(final BuilderParameters obj) {
183             if (parameterClass.isInstance(obj) && (startClass == null || startClass.isInstance(obj))) {
184                 @SuppressWarnings("rawtypes")
185                 final DefaultParametersHandler handlerUntyped = handler;
186                 handlerUntyped.initializeDefaults(obj);
187             }
188         }
189 
190         /**
191          * Tests whether this instance refers to the specified occurrence of a {@code DefaultParametersHandler}.
192          *
193          * @param h the handler to be checked
194          * @param startCls the start class
195          * @return <b>true</b> if this instance refers to this occurrence, <b>false</b> otherwise
196          */
197         public boolean isOccurrence(final DefaultParametersHandler<?> h, final Class<?> startCls) {
198             return h == handler && (startCls == null || startCls.equals(startClass));
199         }
200     }
201 }