    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 *     https://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 * @param <T> the type of the result of all set methods for method chaining
    046 * @since 2.0
    047 */
    048public interface BasicBuilderProperties<T> {
    049
    050    /**
    051     * Sets a {@code BeanHelper} object to be used by the configuration builder. The {@code BeanHelper} is used to create
    052     * the managed configuration instance dynamically. It is not a property of the configuration as most other properties
    053     * defined by this interface. By setting an alternative {@code BeanHelper} the process of creating configuration
    054     * instances via reflection can be adapted. (Some specialized configuration builder implementations also use a
    055     * {@code BeanHelper} to create complex helper objects during construction of their result object.
    056     * {@code CombinedConfigurationBuilder} for instance supports a complex configuration definition format which may
    057     * contain several specialized bean declarations.) If no specific {@code BeanHelper} is set, the builder uses the
    058     * default instance.
    059     *
    060     * @param beanHelper the {@code BeanHelper} to be used by the builder
    061     * @return a reference to this object for method chaining
    062     */
    063    T setBeanHelper(BeanHelper beanHelper);
    064
    065    /**
    066     * Sets the {@code ConfigurationDecoder} object for this configuration. This object is called when encoded properties
    067     * are queried using the {@code getEncodedString()} method.
    068     *
    069     * @param decoder the {@code ConfigurationDecoder} to be used
    070     * @return a reference to this object for method chaining
    071     */
    072    T setConfigurationDecoder(ConfigurationDecoder decoder);
    073
    074    /**
    075     * Sets the {@code ConversionHandler} object for this configuration. This object is responsible for all data type
    076     * conversions required for accessing configuration properties in a specific target type. If this property is not set, a
    077     * default {@code ConversionHandler} is used.
    078     *
    079     * @param handler the {@code ConversionHandler} to be used
    080     * @return a reference to this object for method chaining
    081     */
    082    T setConversionHandler(ConversionHandler handler);
    083
    084    /**
    085     * Adds additional default {@code Lookup} objects (i.e. lookups which are not associated with a specific prefix) to this
    086     * configuration object. Note: This method only takes effect if no {@code ConfigurationInterpolator} is set using the
    087     * {@link #setInterpolator(ConfigurationInterpolator)} method.
    088     *
    089     * @param lookups a collection with {@code Lookup} objects to be added as default lookups at the configuration's
    090     *        {@code ConfigurationInterpolator}
    091     * @return a reference to this object for method chaining
    092     * @see ConfigurationInterpolator#addDefaultLookups(Collection)
    093     */
    094    T setDefaultLookups(Collection<? extends Lookup> lookups);
    095
    096    /**
    097     * Sets the {@code ConfigurationInterpolator} to be used for this configuration. Using this method a custom
    098     * {@code ConfigurationInterpolator} can be set which can be freely configured. Alternatively, it is possible to add
    099     * 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}