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.Map;
021
022import org.apache.commons.configuration2.ConfigurationDecoder;
023import org.apache.commons.configuration2.io.ConfigurationLogger;
024import org.apache.commons.configuration2.beanutils.BeanHelper;
025import org.apache.commons.configuration2.convert.ConversionHandler;
026import org.apache.commons.configuration2.convert.ListDelimiterHandler;
027import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;
028import org.apache.commons.configuration2.interpol.Lookup;
029import org.apache.commons.configuration2.sync.Synchronizer;
030
031/**
032 * <p>
033 * Definition of a properties interface for basic parameters which are supported
034 * by all {@link ConfigurationBuilder} implementations derived from
035 * {@link BasicConfigurationBuilder}.
036 * </p>
037 * <p>
038 * This interface defines the single properties supported by a parameters
039 * object. Properties can be set using a fluent API making it convenient for
040 * client code to specify concrete property values in a single statement.
041 * </p>
042 * <p>
043 * <strong>Important note:</strong> This interface is not intended to be
044 * implemented by client code! It defines a set of available properties and may
045 * be extended even in minor releases.
046 * </p>
047 *
048 * @since 2.0
049 * @param <T> the type of the result of all set methods for method chaining
050 */
051public interface BasicBuilderProperties<T>
052{
053    /**
054     * Sets the <em>logger</em> property. With this property a concrete
055     * {@code ConfigurationLogger} object can be set for the configuration. Thus
056     * logging behavior can be controlled.
057     *
058     * @param log the {@code Log} for the configuration produced by this builder
059     * @return a reference to this object for method chaining
060     */
061    T setLogger(ConfigurationLogger log);
062
063    /**
064     * Sets the value of the <em>throwExceptionOnMissing</em> property. This
065     * property controls the configuration's behavior if missing properties are
066     * queried: a value of <b>true</b> causes the configuration to throw an
067     * exception, for a value of <b>false</b> it will return <b>null</b> values.
068     * (Note: Methods returning a primitive data type will always throw an
069     * exception if the property is not defined.)
070     *
071     * @param b the value of the property
072     * @return a reference to this object for method chaining
073     */
074    T setThrowExceptionOnMissing(boolean b);
075
076    /**
077     * Sets the value of the <em>listDelimiterHandler</em> property. This
078     * property defines the object responsible for dealing with list delimiter
079     * and escaping characters. Note:
080     * {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration}
081     * does not allow setting this property to <b>null</b>. If the default
082     * {@code ListDelimiterHandler} is to be used, do not call this method.
083     *
084     * @param handler the {@code ListDelimiterHandler}
085     * @return a reference to this object for method chaining
086     */
087    T setListDelimiterHandler(ListDelimiterHandler handler);
088
089    /**
090     * Sets the {@code ConfigurationInterpolator} to be used for this
091     * configuration. Using this method a custom
092     * {@code ConfigurationInterpolator} can be set which can be freely
093     * configured. Alternatively, it is possible to add custom {@code Lookup}
094     * objects using other methods provided by this interface.
095     *
096     * @param ci the {@code ConfigurationInterpolator} for this configuration
097     * @return a reference to this object for method chaining
098     */
099    T setInterpolator(ConfigurationInterpolator ci);
100
101    /**
102     * Sets additional {@code Lookup} objects for specific prefixes for this
103     * configuration object. All {@code Lookup} objects contained in the given
104     * map are added to the configuration's {@code ConfigurationInterpolator}.
105     * Note: This method only takes effect if no
106     * {@code ConfigurationInterpolator} is set using the
107     * {@link #setInterpolator(ConfigurationInterpolator)} method.
108     *
109     * @param lookups a map with {@code Lookup} objects and their associated
110     *        prefixes
111     * @return a reference to this object for method chaining
112     * @see ConfigurationInterpolator#registerLookups(Map)
113     */
114    T setPrefixLookups(Map<String, ? extends Lookup> lookups);
115
116    /**
117     * Adds additional default {@code Lookup} objects (i.e. lookups which are
118     * not associated with a specific prefix) to this configuration object.
119     * Note: This method only takes effect if no
120     * {@code ConfigurationInterpolator} is set using the
121     * {@link #setInterpolator(ConfigurationInterpolator)} method.
122     *
123     * @param lookups a collection with {@code Lookup} objects to be added as
124     *        default lookups at the configuration's
125     *        {@code ConfigurationInterpolator}
126     * @return a reference to this object for method chaining
127     * @see ConfigurationInterpolator#addDefaultLookups(Collection)
128     */
129    T setDefaultLookups(Collection<? extends Lookup> lookups);
130
131    /**
132     * Sets the parent {@code ConfigurationInterpolator} for this
133     * configuration's {@code ConfigurationInterpolator}. Setting a parent
134     * {@code ConfigurationInterpolator} can be used for defining a default
135     * behavior for variables which cannot be resolved.
136     *
137     * @param parent the new parent {@code ConfigurationInterpolator}
138     * @return a reference to this object for method chaining
139     * @see ConfigurationInterpolator#setParentInterpolator(ConfigurationInterpolator)
140     */
141    T setParentInterpolator(ConfigurationInterpolator parent);
142
143    /**
144     * Sets the {@code Synchronizer} object for this configuration. This object
145     * is used to protect this configuration instance against concurrent access.
146     * The concrete {@code Synchronizer} implementation used determines whether
147     * a configuration instance is thread-safe or not.
148     *
149     * @param sync the {@code Synchronizer} to be used (a value of <b>null</b>
150     *        means that a default {@code Synchronizer} is used)
151     * @return a reference to this object for method chaining
152     */
153    T setSynchronizer(Synchronizer sync);
154
155    /**
156     * Sets the {@code ConversionHandler} object for this configuration. This
157     * object is responsible for all data type conversions required for
158     * accessing configuration properties in a specific target type. If this
159     * property is not set, a default {@code ConversionHandler} is used.
160     *
161     * @param handler the {@code ConversionHandler} to be used
162     * @return a reference to this object for method chaining
163     */
164    T setConversionHandler(ConversionHandler handler);
165
166    /**
167     * Sets the {@code ConfigurationDecoder} object for this configuration. This
168     * object is called when encoded properties are queried using the
169     * {@code getEncodedString()} method.
170     *
171     * @param decoder the {@code ConfigurationDecoder} to be used
172     * @return a reference to this object for method chaining
173     */
174    T setConfigurationDecoder(ConfigurationDecoder decoder);
175
176    /**
177     * Sets a {@code BeanHelper} object to be used by the configuration builder.
178     * The {@code BeanHelper} is used to create the managed configuration
179     * instance dynamically. It is not a property of the configuration as most
180     * other properties defined by this interface. By setting an alternative
181     * {@code BeanHelper} the process of creating configuration instances via
182     * reflection can be adapted. (Some specialized configuration builder
183     * implementations also use a {@code BeanHelper} to create complex helper
184     * objects during construction of their result object.
185     * {@code CombinedConfigurationBuilder} for instance supports a complex
186     * configuration definition format which may contain several specialized
187     * bean declarations.) If no specific {@code BeanHelper} is set, the builder
188     * uses the default instance.
189     *
190     * @param beanHelper the {@code BeanHelper} to be used by the builder
191     * @return a reference to this object for method chaining
192     */
193    T setBeanHelper(BeanHelper beanHelper);
194}