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}