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.Map; 21 22 import org.apache.commons.configuration2.ConfigurationDecoder; 23 import org.apache.commons.configuration2.beanutils.BeanHelper; 24 import org.apache.commons.configuration2.convert.ConversionHandler; 25 import org.apache.commons.configuration2.convert.ListDelimiterHandler; 26 import org.apache.commons.configuration2.interpol.ConfigurationInterpolator; 27 import org.apache.commons.configuration2.interpol.Lookup; 28 import org.apache.commons.configuration2.io.ConfigurationLogger; 29 import org.apache.commons.configuration2.sync.Synchronizer; 30 31 /** 32 * <p> 33 * Definition of a properties interface for basic parameters which are supported by all {@link ConfigurationBuilder} 34 * implementations derived from {@link BasicConfigurationBuilder}. 35 * </p> 36 * <p> 37 * This interface defines the single properties supported by a parameters object. Properties can be set using a fluent 38 * API making it convenient for client code to specify concrete property values in a single statement. 39 * </p> 40 * <p> 41 * <strong>Important note:</strong> This interface is not intended to be implemented by client code! It defines a set of 42 * available properties and may be extended even in minor releases. 43 * </p> 44 * 45 * @since 2.0 46 * @param <T> the type of the result of all set methods for method chaining 47 */ 48 public interface BasicBuilderProperties<T> { 49 /** 50 * Sets a {@code BeanHelper} object to be used by the configuration builder. The {@code BeanHelper} is used to create 51 * the managed configuration instance dynamically. It is not a property of the configuration as most other properties 52 * defined by this interface. By setting an alternative {@code BeanHelper} the process of creating configuration 53 * instances via reflection can be adapted. (Some specialized configuration builder implementations also use a 54 * {@code BeanHelper} to create complex helper objects during construction of their result object. 55 * {@code CombinedConfigurationBuilder} for instance supports a complex configuration definition format which may 56 * contain several specialized bean declarations.) If no specific {@code BeanHelper} is set, the builder uses the 57 * default instance. 58 * 59 * @param beanHelper the {@code BeanHelper} to be used by the builder 60 * @return a reference to this object for method chaining 61 */ 62 T setBeanHelper(BeanHelper beanHelper); 63 64 /** 65 * Sets the {@code ConfigurationDecoder} object for this configuration. This object is called when encoded properties 66 * are queried using the {@code getEncodedString()} method. 67 * 68 * @param decoder the {@code ConfigurationDecoder} to be used 69 * @return a reference to this object for method chaining 70 */ 71 T setConfigurationDecoder(ConfigurationDecoder decoder); 72 73 /** 74 * Sets the {@code ConversionHandler} object for this configuration. This object is responsible for all data type 75 * conversions required for accessing configuration properties in a specific target type. If this property is not set, a 76 * default {@code ConversionHandler} is used. 77 * 78 * @param handler the {@code ConversionHandler} to be used 79 * @return a reference to this object for method chaining 80 */ 81 T setConversionHandler(ConversionHandler handler); 82 83 /** 84 * Adds additional default {@code Lookup} objects (i.e. lookups which are not associated with a specific prefix) to this 85 * configuration object. Note: This method only takes effect if no {@code ConfigurationInterpolator} is set using the 86 * {@link #setInterpolator(ConfigurationInterpolator)} method. 87 * 88 * @param lookups a collection with {@code Lookup} objects to be added as default lookups at the configuration's 89 * {@code ConfigurationInterpolator} 90 * @return a reference to this object for method chaining 91 * @see ConfigurationInterpolator#addDefaultLookups(Collection) 92 */ 93 T setDefaultLookups(Collection<? extends Lookup> lookups); 94 95 /** 96 * Sets the {@code ConfigurationInterpolator} to be used for this configuration. Using this method a custom 97 * {@code ConfigurationInterpolator} can be set which can be freely configured. Alternatively, it is possible to add 98 * custom {@code Lookup} objects using other methods provided by this interface. 99 * 100 * @param ci the {@code ConfigurationInterpolator} for this configuration 101 * @return a reference to this object for method chaining 102 */ 103 T setInterpolator(ConfigurationInterpolator ci); 104 105 /** 106 * Sets the value of the <em>listDelimiterHandler</em> property. This property defines the object responsible for 107 * dealing with list delimiter and escaping characters. Note: 108 * {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration} does not allow setting this 109 * property to <b>null</b>. If the default {@code ListDelimiterHandler} is to be used, do not call this method. 110 * 111 * @param handler the {@code ListDelimiterHandler} 112 * @return a reference to this object for method chaining 113 */ 114 T setListDelimiterHandler(ListDelimiterHandler handler); 115 116 /** 117 * Sets the <em>logger</em> property. With this property a concrete {@code ConfigurationLogger} object can be set for 118 * the configuration. Thus logging behavior can be controlled. 119 * 120 * @param log the {@code Log} for the configuration produced by this builder 121 * @return a reference to this object for method chaining 122 */ 123 T setLogger(ConfigurationLogger log); 124 125 /** 126 * Sets the parent {@code ConfigurationInterpolator} for this configuration's {@code ConfigurationInterpolator}. Setting 127 * a parent {@code ConfigurationInterpolator} can be used for defining a default behavior for variables which cannot be 128 * resolved. 129 * 130 * @param parent the new parent {@code ConfigurationInterpolator} 131 * @return a reference to this object for method chaining 132 * @see ConfigurationInterpolator#setParentInterpolator(ConfigurationInterpolator) 133 */ 134 T setParentInterpolator(ConfigurationInterpolator parent); 135 136 /** 137 * Sets additional {@code Lookup} objects for specific prefixes for this configuration object. All {@code Lookup} 138 * objects contained in the given map are added to the configuration's {@code ConfigurationInterpolator}. Note: This 139 * method only takes effect if no {@code ConfigurationInterpolator} is set using the 140 * {@link #setInterpolator(ConfigurationInterpolator)} method. 141 * 142 * @param lookups a map with {@code Lookup} objects and their associated prefixes 143 * @return a reference to this object for method chaining 144 * @see ConfigurationInterpolator#registerLookups(Map) 145 */ 146 T setPrefixLookups(Map<String, ? extends Lookup> lookups); 147 148 /** 149 * Sets the {@code Synchronizer} object for this configuration. This object is used to protect this configuration 150 * instance against concurrent access. The concrete {@code Synchronizer} implementation used determines whether a 151 * configuration instance is thread-safe or not. 152 * 153 * @param sync the {@code Synchronizer} to be used (a value of <b>null</b> means that a default {@code Synchronizer} is 154 * used) 155 * @return a reference to this object for method chaining 156 */ 157 T setSynchronizer(Synchronizer sync); 158 159 /** 160 * Sets the value of the <em>throwExceptionOnMissing</em> property. This property controls the configuration's behavior 161 * if missing properties are queried: a value of <b>true</b> causes the configuration to throw an exception, for a value 162 * of <b>false</b> it will return <b>null</b> values. (Note: Methods returning a primitive data type will always throw 163 * an exception if the property is not defined.) 164 * 165 * @param b the value of the property 166 * @return a reference to this object for method chaining 167 */ 168 T setThrowExceptionOnMissing(boolean b); 169 }