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