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