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.ArrayList; 020import java.util.Collection; 021import java.util.HashMap; 022import java.util.Map; 023 024import org.apache.commons.configuration2.ConfigurationDecoder; 025import org.apache.commons.configuration2.io.ConfigurationLogger; 026import org.apache.commons.configuration2.beanutils.BeanHelper; 027import org.apache.commons.configuration2.convert.ConversionHandler; 028import org.apache.commons.configuration2.convert.ListDelimiterHandler; 029import org.apache.commons.configuration2.interpol.ConfigurationInterpolator; 030import org.apache.commons.configuration2.interpol.InterpolatorSpecification; 031import org.apache.commons.configuration2.interpol.Lookup; 032import org.apache.commons.configuration2.sync.Synchronizer; 033 034/** 035 * <p> 036 * An implementation of {@code BuilderParameters} which handles the parameters of a {@link ConfigurationBuilder} common 037 * to all concrete {@code Configuration} implementations. 038 * </p> 039 * <p> 040 * This class provides methods for setting standard properties supported by the {@code AbstractConfiguration} base 041 * class. A fluent interface can be used to set property values. 042 * </p> 043 * <p> 044 * This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread 045 * during configuration of a {@code ConfigurationBuilder}. 046 * </p> 047 * 048 * @since 2.0 049 */ 050public class BasicBuilderParameters implements Cloneable, BuilderParameters, BasicBuilderProperties<BasicBuilderParameters> { 051 /** The key of the <em>throwExceptionOnMissing</em> property. */ 052 private static final String PROP_THROW_EXCEPTION_ON_MISSING = "throwExceptionOnMissing"; 053 054 /** The key of the <em>listDelimiterHandler</em> property. */ 055 private static final String PROP_LIST_DELIMITER_HANDLER = "listDelimiterHandler"; 056 057 /** The key of the <em>logger</em> property. */ 058 private static final String PROP_LOGGER = "logger"; 059 060 /** The key for the <em>interpolator</em> property. */ 061 private static final String PROP_INTERPOLATOR = "interpolator"; 062 063 /** The key for the <em>prefixLookups</em> property. */ 064 private static final String PROP_PREFIX_LOOKUPS = "prefixLookups"; 065 066 /** The key for the <em>defaultLookups</em> property. */ 067 private static final String PROP_DEFAULT_LOOKUPS = "defaultLookups"; 068 069 /** The key for the <em>parentInterpolator</em> property. */ 070 private static final String PROP_PARENT_INTERPOLATOR = "parentInterpolator"; 071 072 /** The key for the <em>synchronizer</em> property. */ 073 private static final String PROP_SYNCHRONIZER = "synchronizer"; 074 075 /** The key for the <em>conversionHandler</em> property. */ 076 private static final String PROP_CONVERSION_HANDLER = "conversionHandler"; 077 078 /** The key for the <em>configurationDecoder</em> property. */ 079 private static final String PROP_CONFIGURATION_DECODER = "configurationDecoder"; 080 081 /** The key for the {@code BeanHelper}. */ 082 private static final String PROP_BEAN_HELPER = RESERVED_PARAMETER_PREFIX + "BeanHelper"; 083 084 /** The map for storing the current property values. */ 085 private Map<String, Object> properties; 086 087 /** 088 * Creates a new instance of {@code BasicBuilderParameters}. 089 */ 090 public BasicBuilderParameters() { 091 properties = new HashMap<>(); 092 } 093 094 /** 095 * {@inheritDoc} This implementation returns a copy of the internal parameters map with the values set so far. 096 * Collection structures (e.g. for lookup objects) are stored as defensive copies, so the original data cannot be 097 * modified. 098 */ 099 @Override 100 public Map<String, Object> getParameters() { 101 final HashMap<String, Object> result = new HashMap<>(properties); 102 if (result.containsKey(PROP_INTERPOLATOR)) { 103 // A custom ConfigurationInterpolator overrides lookups 104 result.remove(PROP_PREFIX_LOOKUPS); 105 result.remove(PROP_DEFAULT_LOOKUPS); 106 result.remove(PROP_PARENT_INTERPOLATOR); 107 } 108 109 createDefensiveCopies(result); 110 return result; 111 } 112 113 /** 114 * Sets the <em>logger</em> property. With this property a concrete {@code Log} object can be set for the configuration. 115 * Thus logging behavior can be controlled. 116 * 117 * @param log the {@code Log} for the configuration produced by this builder 118 * @return a reference to this object for method chaining 119 */ 120 @Override 121 public BasicBuilderParameters setLogger(final ConfigurationLogger log) { 122 return setProperty(PROP_LOGGER, log); 123 } 124 125 /** 126 * Sets the value of the <em>throwExceptionOnMissing</em> property. This property controls the configuration's behavior 127 * if missing properties are queried: a value of <b>true</b> causes the configuration to throw an exception, for a value 128 * of <b>false</b> it will return <b>null</b> values. (Note: Methods returning a primitive data type will always throw 129 * an exception if the property is not defined.) 130 * 131 * @param b the value of the property 132 * @return a reference to this object for method chaining 133 */ 134 @Override 135 public BasicBuilderParameters setThrowExceptionOnMissing(final boolean b) { 136 return setProperty(PROP_THROW_EXCEPTION_ON_MISSING, Boolean.valueOf(b)); 137 } 138 139 /** 140 * Sets the value of the <em>listDelimiterHandler</em> property. This property defines the object responsible for 141 * dealing with list delimiter and escaping characters. Note: 142 * {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration} does not allow setting this 143 * property to <b>null</b>. If the default {@code ListDelimiterHandler} is to be used, do not call this method. 144 * 145 * @param handler the {@code ListDelimiterHandler} 146 * @return a reference to this object for method chaining 147 */ 148 @Override 149 public BasicBuilderParameters setListDelimiterHandler(final ListDelimiterHandler handler) { 150 return setProperty(PROP_LIST_DELIMITER_HANDLER, handler); 151 } 152 153 /** 154 * {@inheritDoc} The passed in {@code ConfigurationInterpolator} is set without modifications. 155 */ 156 @Override 157 public BasicBuilderParameters setInterpolator(final ConfigurationInterpolator ci) { 158 return setProperty(PROP_INTERPOLATOR, ci); 159 } 160 161 /** 162 * {@inheritDoc} A defensive copy of the passed in map is created. A <b>null</b> argument causes all prefix lookups to 163 * be removed from the internal parameters map. 164 */ 165 @Override 166 public BasicBuilderParameters setPrefixLookups(final Map<String, ? extends Lookup> lookups) { 167 if (lookups == null) { 168 properties.remove(PROP_PREFIX_LOOKUPS); 169 return this; 170 } 171 return setProperty(PROP_PREFIX_LOOKUPS, new HashMap<>(lookups)); 172 } 173 174 /** 175 * {@inheritDoc} A defensive copy of the passed in collection is created. A <b>null</b> argument causes all default 176 * lookups to be removed from the internal parameters map. 177 */ 178 @Override 179 public BasicBuilderParameters setDefaultLookups(final Collection<? extends Lookup> lookups) { 180 if (lookups == null) { 181 properties.remove(PROP_DEFAULT_LOOKUPS); 182 return this; 183 } 184 return setProperty(PROP_DEFAULT_LOOKUPS, new ArrayList<>(lookups)); 185 } 186 187 /** 188 * {@inheritDoc} This implementation stores the passed in {@code ConfigurationInterpolator} object in the internal 189 * parameters map. 190 */ 191 @Override 192 public BasicBuilderParameters setParentInterpolator(final ConfigurationInterpolator parent) { 193 return setProperty(PROP_PARENT_INTERPOLATOR, parent); 194 } 195 196 /** 197 * {@inheritDoc} This implementation stores the passed in {@code Synchronizer} object in the internal parameters map. 198 */ 199 @Override 200 public BasicBuilderParameters setSynchronizer(final Synchronizer sync) { 201 return setProperty(PROP_SYNCHRONIZER, sync); 202 } 203 204 /** 205 * {@inheritDoc} This implementation stores the passed in {@code ConversionHandler} object in the internal parameters 206 * map. 207 */ 208 @Override 209 public BasicBuilderParameters setConversionHandler(final ConversionHandler handler) { 210 return setProperty(PROP_CONVERSION_HANDLER, handler); 211 } 212 213 /** 214 * {@inheritDoc} This implementation stores the passed in {@code BeanHelper} object in the internal parameters map, but 215 * uses a reserved key, so that it is not used for the initialization of properties of the managed configuration object. 216 * The {@code fetchBeanHelper()} method can be used to obtain the {@code BeanHelper} instance from a parameters map. 217 */ 218 @Override 219 public BasicBuilderParameters setBeanHelper(final BeanHelper beanHelper) { 220 return setProperty(PROP_BEAN_HELPER, beanHelper); 221 } 222 223 /** 224 * {@inheritDoc} This implementation stores the passed in {@code ConfigurationDecoder} object in the internal parameters 225 * map. 226 */ 227 @Override 228 public BasicBuilderParameters setConfigurationDecoder(final ConfigurationDecoder decoder) { 229 return setProperty(PROP_CONFIGURATION_DECODER, decoder); 230 } 231 232 /** 233 * Merges this object with the given parameters object. This method adds all property values defined by the passed in 234 * parameters object to the internal storage which are not already in. So properties already defined in this object take 235 * precedence. Property names starting with the reserved parameter prefix are ignored. 236 * 237 * @param p the object whose properties should be merged (must not be <b>null</b>) 238 * @throws IllegalArgumentException if the passed in object is <b>null</b> 239 */ 240 public void merge(final BuilderParameters p) { 241 if (p == null) { 242 throw new IllegalArgumentException("Parameters to merge must not be null!"); 243 } 244 245 for (final Map.Entry<String, Object> e : p.getParameters().entrySet()) { 246 if (!properties.containsKey(e.getKey()) && !e.getKey().startsWith(RESERVED_PARAMETER_PREFIX)) { 247 storeProperty(e.getKey(), e.getValue()); 248 } 249 } 250 } 251 252 /** 253 * Inherits properties from the specified map. This can be used for instance to reuse parameters from one builder in 254 * another builder - also in parent-child relations in which a parent builder creates child builders. The purpose of 255 * this method is to let a concrete implementation decide which properties can be inherited. Because parameters are 256 * basically organized as a map it would be possible to simply copy over all properties from the source object. However, 257 * this is not appropriate in all cases. For instance, some properties - like a {@code ConfigurationInterpolator} - are 258 * tightly connected to a configuration and cannot be reused in a different context. For other properties, e.g. a file 259 * name, it does not make sense to copy it. Therefore, an implementation has to be explicit in the properties it wants 260 * to take over. 261 * 262 * @param source the source properties to inherit from 263 * @throws IllegalArgumentException if the source map is <b>null</b> 264 */ 265 public void inheritFrom(final Map<String, ?> source) { 266 if (source == null) { 267 throw new IllegalArgumentException("Source properties must not be null!"); 268 } 269 copyPropertiesFrom(source, PROP_BEAN_HELPER, PROP_CONFIGURATION_DECODER, PROP_CONVERSION_HANDLER, PROP_LIST_DELIMITER_HANDLER, PROP_LOGGER, 270 PROP_SYNCHRONIZER, PROP_THROW_EXCEPTION_ON_MISSING); 271 } 272 273 /** 274 * Obtains a specification for a {@link ConfigurationInterpolator} from the specified map with parameters. All 275 * properties related to interpolation are evaluated and added to the specification object. 276 * 277 * @param params the map with parameters (must not be <b>null</b>) 278 * @return an {@code InterpolatorSpecification} object constructed with data from the map 279 * @throws IllegalArgumentException if the map is <b>null</b> or contains invalid data 280 */ 281 public static InterpolatorSpecification fetchInterpolatorSpecification(final Map<String, Object> params) { 282 checkParameters(params); 283 return new InterpolatorSpecification.Builder().withInterpolator(fetchParameter(params, PROP_INTERPOLATOR, ConfigurationInterpolator.class)) 284 .withParentInterpolator(fetchParameter(params, PROP_PARENT_INTERPOLATOR, ConfigurationInterpolator.class)) 285 .withPrefixLookups(fetchAndCheckPrefixLookups(params)).withDefaultLookups(fetchAndCheckDefaultLookups(params)).create(); 286 } 287 288 /** 289 * Obtains the {@code BeanHelper} object from the specified map with parameters. This method can be used to obtain an 290 * instance from a parameters map that has been set via the {@code setBeanHelper()} method. If no such instance is 291 * found, result is <b>null</b>. 292 * 293 * @param params the map with parameters (must not be <b>null</b>) 294 * @return the {@code BeanHelper} stored in this map or <b>null</b> 295 * @throws IllegalArgumentException if the map is <b>null</b> 296 */ 297 public static BeanHelper fetchBeanHelper(final Map<String, Object> params) { 298 checkParameters(params); 299 return (BeanHelper) params.get(PROP_BEAN_HELPER); 300 } 301 302 /** 303 * Clones this object. This is useful because multiple builder instances may use a similar set of parameters. However, 304 * single instances of parameter objects must not assigned to multiple builders. Therefore, cloning a parameters object 305 * provides a solution for this use case. This method creates a new parameters object with the same content as this one. 306 * The internal map storing the parameter values is cloned, too, also collection structures contained in this map. 307 * However, no a full deep clone operation is performed. Objects like a {@code ConfigurationInterpolator} or 308 * {@code Lookup}s are shared between this and the newly created instance. 309 * 310 * @return a clone of this object 311 */ 312 @Override 313 public BasicBuilderParameters clone() { 314 try { 315 final BasicBuilderParameters copy = (BasicBuilderParameters) super.clone(); 316 copy.properties = getParameters(); 317 return copy; 318 } catch (final CloneNotSupportedException cnex) { 319 // should not happen 320 throw new AssertionError(cnex); 321 } 322 } 323 324 /** 325 * Sets a property for this parameters object. Properties are stored in an internal map. With this method a new entry 326 * can be added to this map. If the value is <b>null</b>, the key is removed from the internal map. This method can be 327 * used by sub classes which also store properties in a map. 328 * 329 * @param key the key of the property 330 * @param value the value of the property 331 */ 332 protected void storeProperty(final String key, final Object value) { 333 if (value == null) { 334 properties.remove(key); 335 } else { 336 properties.put(key, value); 337 } 338 } 339 340 /** 341 * Obtains the value of the specified property from the internal map. This method can be used by derived classes if a 342 * specific property is to be accessed. If the given key is not found, result is <b>null</b>. 343 * 344 * @param key the key of the property in question 345 * @return the value of the property with this key or <b>null</b> 346 */ 347 protected Object fetchProperty(final String key) { 348 return properties.get(key); 349 } 350 351 /** 352 * Copies a number of properties from the given map into this object. Properties are only copied if they are defined in 353 * the source map. 354 * 355 * @param source the source map 356 * @param keys the keys to be copied 357 */ 358 protected void copyPropertiesFrom(final Map<String, ?> source, final String... keys) { 359 for (final String key : keys) { 360 final Object value = source.get(key); 361 if (value != null) { 362 storeProperty(key, value); 363 } 364 } 365 } 366 367 /** 368 * Helper method for setting a property value. 369 * 370 * @param key the key of the property 371 * @param value the value of the property 372 * @return a reference to this object 373 */ 374 private BasicBuilderParameters setProperty(final String key, final Object value) { 375 storeProperty(key, value); 376 return this; 377 } 378 379 /** 380 * Creates defensive copies for collection structures when constructing the map with parameters. It should not be 381 * possible to modify this object's internal state when having access to the parameters map. 382 * 383 * @param params the map with parameters to be passed to the caller 384 */ 385 private static void createDefensiveCopies(final HashMap<String, Object> params) { 386 final Map<String, ? extends Lookup> prefixLookups = fetchPrefixLookups(params); 387 if (prefixLookups != null) { 388 params.put(PROP_PREFIX_LOOKUPS, new HashMap<>(prefixLookups)); 389 } 390 final Collection<? extends Lookup> defLookups = fetchDefaultLookups(params); 391 if (defLookups != null) { 392 params.put(PROP_DEFAULT_LOOKUPS, new ArrayList<>(defLookups)); 393 } 394 } 395 396 /** 397 * Obtains the map with prefix lookups from the parameters map. 398 * 399 * @param params the map with parameters 400 * @return the map with prefix lookups (may be <b>null</b>) 401 */ 402 private static Map<String, ? extends Lookup> fetchPrefixLookups(final Map<String, Object> params) { 403 // This is safe to cast because we either have full control over the map 404 // and thus know the types of the contained values or have checked 405 // the content before 406 @SuppressWarnings("unchecked") 407 final Map<String, ? extends Lookup> prefixLookups = (Map<String, ? extends Lookup>) params.get(PROP_PREFIX_LOOKUPS); 408 return prefixLookups; 409 } 410 411 /** 412 * Tests whether the passed in map with parameters contains a map with prefix lookups. This method is used if the 413 * parameters map is from an insecure source and we cannot be sure that it contains valid data. Therefore, we have to 414 * map that the key for the prefix lookups actually points to a map containing keys and values of expected data types. 415 * 416 * @param params the parameters map 417 * @return the obtained map with prefix lookups 418 * @throws IllegalArgumentException if the map contains invalid data 419 */ 420 private static Map<String, ? extends Lookup> fetchAndCheckPrefixLookups(final Map<String, Object> params) { 421 final Map<?, ?> prefixes = fetchParameter(params, PROP_PREFIX_LOOKUPS, Map.class); 422 if (prefixes == null) { 423 return null; 424 } 425 426 for (final Map.Entry<?, ?> e : prefixes.entrySet()) { 427 if (!(e.getKey() instanceof String) || !(e.getValue() instanceof Lookup)) { 428 throw new IllegalArgumentException("Map with prefix lookups contains invalid data: " + prefixes); 429 } 430 } 431 return fetchPrefixLookups(params); 432 } 433 434 /** 435 * Obtains the collection with default lookups from the parameters map. 436 * 437 * @param params the map with parameters 438 * @return the collection with default lookups (may be <b>null</b>) 439 */ 440 private static Collection<? extends Lookup> fetchDefaultLookups(final Map<String, Object> params) { 441 // This is safe to cast because we either have full control over the map 442 // and thus know the types of the contained values or have checked 443 // the content before 444 @SuppressWarnings("unchecked") 445 final Collection<? extends Lookup> defLookups = (Collection<? extends Lookup>) params.get(PROP_DEFAULT_LOOKUPS); 446 return defLookups; 447 } 448 449 /** 450 * Tests whether the passed in map with parameters contains a valid collection with default lookups. This method works 451 * like {@link #fetchAndCheckPrefixLookups(Map)}, but tests the default lookups collection. 452 * 453 * @param params the map with parameters 454 * @return the collection with default lookups (may be <b>null</b>) 455 * @throws IllegalArgumentException if invalid data is found 456 */ 457 private static Collection<? extends Lookup> fetchAndCheckDefaultLookups(final Map<String, Object> params) { 458 final Collection<?> col = fetchParameter(params, PROP_DEFAULT_LOOKUPS, Collection.class); 459 if (col == null) { 460 return null; 461 } 462 463 for (final Object o : col) { 464 if (!(o instanceof Lookup)) { 465 throw new IllegalArgumentException("Collection with default lookups contains invalid data: " + col); 466 } 467 } 468 return fetchDefaultLookups(params); 469 } 470 471 /** 472 * Obtains a parameter from a map and performs a type check. 473 * 474 * @param params the map with parameters 475 * @param key the key of the parameter 476 * @param expClass the expected class of the parameter value 477 * @param <T> the parameter type 478 * @return the value of the parameter in the correct data type 479 * @throws IllegalArgumentException if the parameter is not of the expected type 480 */ 481 private static <T> T fetchParameter(final Map<String, Object> params, final String key, final Class<T> expClass) { 482 final Object value = params.get(key); 483 if (value == null) { 484 return null; 485 } 486 if (!expClass.isInstance(value)) { 487 throw new IllegalArgumentException(String.format("Parameter %s is not of type %s!", key, expClass.getSimpleName())); 488 } 489 return expClass.cast(value); 490 } 491 492 /** 493 * Checks whether a map with parameters is present. Throws an exception if not. 494 * 495 * @param params the map with parameters to check 496 * @throws IllegalArgumentException if the map is <b>null</b> 497 */ 498 private static void checkParameters(final Map<String, Object> params) { 499 if (params == null) { 500 throw new IllegalArgumentException("Parameters map must not be null!"); 501 } 502 } 503}