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