001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.configuration2.builder;
018
019import java.util.Collection;
020import java.util.LinkedList;
021import java.util.concurrent.CopyOnWriteArrayList;
022
023/**
024 * <p>
025 * A class for managing a set of {@link DefaultParametersHandler} objects.
026 * </p>
027 * <p>
028 * This class provides functionality for registering and removing {@code DefaultParametersHandler} objects for arbitrary
029 * parameters classes. The handlers registered at an instance can then be applied on a passed in parameters object, so
030 * that it gets initialized with the provided default values.
031 * </p>
032 * <p>
033 * Usage of this class is as follows: First the {@code DefaultParametersHandler} objects to be supported must be
034 * registered using one of the {@code registerDefaultHandler()} methods. After that arbitrary parameters objects can be
035 * passed to the {@code initializeParameters()} method. This causes all {@code DefaultParametersHandler} objects
036 * supporting this parameters class to be invoked on this object.
037 * </p>
038 * <p>
039 * Implementation note: This class is thread-safe.
040 * </p>
041 *
042 * @since 2.0
043 */
044public class DefaultParametersManager {
045    /** A collection with the registered default handlers. */
046    private final Collection<DefaultHandlerData> defaultHandlers;
047
048    /**
049     * Creates a new instance of {@code DefaultParametersManager}.
050     */
051    public DefaultParametersManager() {
052        defaultHandlers = new CopyOnWriteArrayList<>();
053    }
054
055    /**
056     * Registers the specified {@code DefaultParametersHandler} object for the given parameters class. This means that this
057     * handler object is invoked every time a parameters object of the specified class or one of its subclasses is
058     * initialized. The handler can set arbitrary default values for the properties supported by this parameters object. If
059     * there are multiple handlers registered supporting a specific parameters class, they are invoked in the order in which
060     * they were registered. So handlers registered later may override the values set by handlers registered earlier.
061     *
062     * @param <T> the type of the parameters supported by this handler
063     * @param paramsClass the parameters class supported by this handler (must not be <b>null</b>)
064     * @param handler the {@code DefaultParametersHandler} to be registered (must not be <b>null</b>)
065     * @throws IllegalArgumentException if a required parameter is missing
066     */
067    public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler) {
068        registerDefaultsHandler(paramsClass, handler, null);
069    }
070
071    /**
072     * Registers the specified {@code DefaultParametersHandler} object for the given parameters class and start class in the
073     * inheritance hierarchy. This method works like {@link #registerDefaultsHandler(Class, DefaultParametersHandler)}, but
074     * the defaults handler is only executed on parameter objects that are instances of the specified start class. Parameter
075     * classes do not stand in a real inheritance hierarchy; however, there is a logic hierarchy defined by the methods
076     * supported by the different parameter objects. A properties parameter object for instance supports all methods defined
077     * for a file-based parameter object. So one can argue that
078     * {@link org.apache.commons.configuration2.builder.fluent.FileBasedBuilderParameters FileBasedBuilderParameters} is a
079     * base interface of {@link org.apache.commons.configuration2.builder.fluent.PropertiesBuilderParameters
080     * PropertiesBuilderParameters} (although, for technical reasons, this relation is not reflected in the Java classes). A
081     * {@link DefaultParametersHandler} object defined for a base interface can also deal with parameter objects "derived"
082     * from this base interface (i.e. supporting a super set of the methods defined by the base interface). Now there may be
083     * the use case that there is an implementation of {@code DefaultParametersHandler} for a base interface (e.g.
084     * {@code FileBasedBuilderParameters}), but it should only process specific derived interfaces (say
085     * {@code PropertiesBuilderParameters}, but not
086     * {@link org.apache.commons.configuration2.builder.fluent.XMLBuilderParameters XMLBuilderParameters}). This can be
087     * achieved by passing in {@code PropertiesBuilderParameters} as start class. In this case,
088     * {@code DefaultParametersManager} ensures that the handler is only called on parameter objects having both the start
089     * class and the actual type supported by the handler as base interfaces. The passed in start class can be <b>null</b>;
090     * then the parameter class supported by the handler is used (which is the default behavior of the
091     * {@link #registerDefaultsHandler(Class, DefaultParametersHandler)} method).
092     *
093     * @param <T> the type of the parameters supported by this handler
094     * @param paramsClass the parameters class supported by this handler (must not be <b>null</b>)
095     * @param handler the {@code DefaultParametersHandler} to be registered (must not be <b>null</b>)
096     * @param startClass an optional start class in the hierarchy of parameter objects for which this handler should be
097     *        applied
098     * @throws IllegalArgumentException if a required parameter is missing
099     */
100    public <T> void registerDefaultsHandler(final Class<T> paramsClass, final DefaultParametersHandler<? super T> handler, final Class<?> startClass) {
101        if (paramsClass == null) {
102            throw new IllegalArgumentException("Parameters class must not be null!");
103        }
104        if (handler == null) {
105            throw new IllegalArgumentException("DefaultParametersHandler must not be null!");
106        }
107        defaultHandlers.add(new DefaultHandlerData(handler, paramsClass, startClass));
108    }
109
110    /**
111     * Removes the specified {@code DefaultParametersHandler} from this instance. If this handler has been registered
112     * multiple times for different start classes, all occurrences are removed.
113     *
114     * @param handler the {@code DefaultParametersHandler} to be removed
115     */
116    public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler) {
117        unregisterDefaultsHandler(handler, null);
118    }
119
120    /**
121     * Removes the specified {@code DefaultParametersHandler} from this instance if it is in combination with the given
122     * start class. If this handler has been registered multiple times for different start classes, only occurrences for the
123     * given start class are removed. The {@code startClass} parameter can be <b>null</b>, then all occurrences of the
124     * handler are removed.
125     *
126     * @param handler the {@code DefaultParametersHandler} to be removed
127     * @param startClass the start class for which this handler is to be removed
128     */
129    public void unregisterDefaultsHandler(final DefaultParametersHandler<?> handler, final Class<?> startClass) {
130        final Collection<DefaultHandlerData> toRemove = new LinkedList<>();
131        for (final DefaultHandlerData dhd : defaultHandlers) {
132            if (dhd.isOccurrence(handler, startClass)) {
133                toRemove.add(dhd);
134            }
135        }
136
137        defaultHandlers.removeAll(toRemove);
138    }
139
140    /**
141     * Initializes the passed in {@code BuilderParameters} object by applying all matching {@link DefaultParametersHandler}
142     * objects registered at this instance. Using this method the passed in parameters object can be populated with default
143     * values.
144     *
145     * @param params the parameters object to be initialized (may be <b>null</b>, then this method has no effect)
146     */
147    public void initializeParameters(final BuilderParameters params) {
148        if (params != null) {
149            for (final DefaultHandlerData dhd : defaultHandlers) {
150                dhd.applyHandlerIfMatching(params);
151            }
152        }
153    }
154
155    /**
156     * A data class storing information about {@code DefaultParametersHandler} objects added to a {@code Parameters} object.
157     * Using this class it is possible to find out which default handlers apply for a given parameters object and to invoke
158     * them.
159     */
160    private static class DefaultHandlerData {
161        /** The handler object. */
162        private final DefaultParametersHandler<?> handler;
163
164        /** The class supported by this handler. */
165        private final Class<?> parameterClass;
166
167        /** The start class for applying this handler. */
168        private final Class<?> startClass;
169
170        /**
171         * Creates a new instance of {@code DefaultHandlerData}.
172         *
173         * @param h the {@code DefaultParametersHandler}
174         * @param cls the handler's data class
175         * @param startCls the start class
176         */
177        public DefaultHandlerData(final DefaultParametersHandler<?> h, final Class<?> cls, final Class<?> startCls) {
178            handler = h;
179            parameterClass = cls;
180            startClass = startCls;
181        }
182
183        /**
184         * Checks whether the managed {@code DefaultParametersHandler} can be applied to the given parameters object. If this is
185         * the case, it is executed on this object and can initialize it with default values.
186         *
187         * @param obj the parameters object to be initialized
188         */
189        @SuppressWarnings("unchecked")
190        // There are explicit isInstance() checks, so there won't be
191        // ClassCastExceptions
192        public void applyHandlerIfMatching(final BuilderParameters obj) {
193            if (parameterClass.isInstance(obj) && (startClass == null || startClass.isInstance(obj))) {
194                @SuppressWarnings("rawtypes")
195                final DefaultParametersHandler handlerUntyped = handler;
196                handlerUntyped.initializeDefaults(obj);
197            }
198        }
199
200        /**
201         * Tests whether this instance refers to the specified occurrence of a {@code DefaultParametersHandler}.
202         *
203         * @param h the handler to be checked
204         * @param startCls the start class
205         * @return <b>true</b> if this instance refers to this occurrence, <b>false</b> otherwise
206         */
207        public boolean isOccurrence(final DefaultParametersHandler<?> h, final Class<?> startCls) {
208            return h == handler && (startCls == null || startCls.equals(startClass));
209        }
210    }
211}