    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.combined;
    018
    019import org.apache.commons.configuration2.HierarchicalConfiguration;
    020import org.apache.commons.configuration2.builder.BuilderParameters;
    021import org.apache.commons.configuration2.builder.ConfigurationBuilder;
    022import org.apache.commons.configuration2.builder.DefaultParametersHandler;
    023import org.apache.commons.configuration2.builder.DefaultParametersManager;
    024
    025/**
    026 * <p>
    027 * Definition of a properties interface for the parameters of a combined
    028 * configuration builder.
    029 * </p>
    030 * <p>
    031 * This interface defines a number of properties for adapting the construction
    032 * of a combined configuration based on a definition configuration. Properties
    033 * can be set in a fluent style.
    034 * </p>
    035 * <p>
    036 * <strong>Important note:</strong> This interface is not intended to be
    037 * implemented by client code! It defines a set of available properties and may
    038 * be extended even in minor releases.
    039 * </p>
    040 *
    041 * @since 2.0
    042 * @param <T> the return type of all methods for allowing method chaining
    043 */
    044public interface CombinedBuilderProperties<T>
    045{
    046    /**
    047     * Sets a flag whether the child configurations created by a
    048     * {@code CombinedConfigurationBuilder} should inherit the settings defined
    049     * for the builder. This is typically useful because for configurations
    050     * coming from homogeneous sources often similar conventions are used.
    051     * Therefore, this flag is <b>true</b> per default.
    052     *
    053     * @param f the flag whether settings should be inherited by child
    054     *        configurations
    055     * @return a reference to this object for method chaining
    056     */
    057    T setInheritSettings(boolean f);
    058
    059    /**
    060     * Sets the {@code ConfigurationBuilder} for the definition configuration.
    061     * This is the configuration which contains the configuration sources that
    062     * form the combined configuration.
    063     *
    064     * @param builder the definition {@code ConfigurationBuilder}
    065     * @return a reference to this object for method chaining
    066     */
    067    T setDefinitionBuilder(
    068            ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder);
    069
    070    /**
    071     * Registers the given {@code ConfigurationBuilderProvider} for the
    072     * specified tag name. This means that whenever this tag is encountered in a
    073     * configuration definition file, the corresponding builder provider is
    074     * invoked.
    075     *
    076     * @param tagName the name of the tag (must not be <b>null</b>)
    077     * @param provider the {@code ConfigurationBuilderProvider} (must not be
    078     *        <b>null</b>)
    079     * @return a reference to this object for method chaining
    080     * @throws IllegalArgumentException if a required parameter is missing
    081     */
    082    T registerProvider(String tagName, ConfigurationBuilderProvider provider);
    083
    084    /**
    085     * Sets the base path for this combined configuration builder. Normally it
    086     * it not necessary to set the base path explicitly. Per default, relative
    087     * file names of configuration sources are resolved based on the location of
    088     * the definition file. If this is not desired or if the definition
    089     * configuration is loaded by a different means, the base path for relative
    090     * file names can be specified using this method.
    091     *
    092     * @param path the base path for resolving relative file names
    093     * @return a reference to this object for method chaining
    094     */
    095    T setBasePath(String path);
    096
    097    /**
    098     * Sets the parameters object for the definition configuration builder. This
    099     * property is evaluated only if the definition configuration builder is not
    100     * set explicitly (using the
    101     * {@link #setDefinitionBuilder(ConfigurationBuilder)} method). In this
    102     * case, a builder for an XML configuration is created and configured with
    103     * this parameters object.
    104     *
    105     * @param params the parameters object for the definition configuration
    106     *        builder
    107     * @return a reference to this object for method chaining
    108     */
    109    T setDefinitionBuilderParameters(BuilderParameters params);
    110
    111    /**
    112     * Sets a {@code DefaultParametersManager} object responsible for managing the default
    113     * parameter handlers to be applied on child configuration sources. When creating
    114     * builders for child configuration sources their parameters are initialized using
    115     * this {@code DefaultParametersManager} instance. This way, meaningful defaults can
    116     * be set. Note that calling this method overrides all
    117     * {@code DefaultParametersHandler} objects previously set by one of the
    118     * {@code registerChildDefaultsHandler()} methods! So either use this method if a
    119     * pre-configured manager object is to be set or call the
    120     * {@code registerChildDefaultHandler()} methods with the handlers to be registered
    121     * (in the latter case, it is not necessary to set a {@code DefaultParametersManager}
    122     * explicitly; a default one is created behind the scenes).
    123     *
    124     * @param manager the {@code DefaultParametersManager}
    125     * @return a reference to this object for method chaining
    126     */
    127    T setChildDefaultParametersManager(DefaultParametersManager manager);
    128
    129    /**
    130     * Registers a {@code DefaultParametersHandler} for child configuration sources. With
    131     * this method an arbitrary number of handler objects can be set. When creating
    132     * builders for child configuration sources their parameters are initialized by
    133     * invoking all matching {@code DefaultParametersHandler}s on them. So, basically the
    134     * same mechanism is used for the initialization of parameters for child configuration
    135     * sources as for normal parameter objects.
    136     *
    137     * @param <D> the type of the handler to be registered
    138     * @param paramClass the parameter class supported by the handler
    139     * @param handler the {@code DefaultParametersHandler} to be registered
    140     * @return a reference to this object for method chaining
    141     * @see DefaultParametersManager#registerDefaultsHandler(Class,
    142     * DefaultParametersHandler)
    143     */
    144    <D> T registerChildDefaultsHandler(Class<D> paramClass,
    145            DefaultParametersHandler<? super D> handler);
    146
    147    /**
    148     * Registers a {@code DefaultParametersHandler} for child configuration sources
    149     * derived from the given start class. This method works like the overloaded variant,
    150     * but limits the application of the defaults handler to specific child configuration
    151     * sources.
    152     *
    153     * @param <D> the type of the handler to be registered
    154     * @param paramClass the parameter class supported by the handler
    155     * @param handler the {@code DefaultParametersHandler} to be registered
    156     * @param startClass an optional start class in the hierarchy of parameter objects for
    157     * which this handler should be applied
    158     * @return a reference to this object for method chaining
    159     * @see DefaultParametersManager#registerDefaultsHandler(Class,
    160     * DefaultParametersHandler, Class)
    161     */
    162    <D> T registerChildDefaultsHandler(Class<D> paramClass,
    163            DefaultParametersHandler<? super D> handler, Class<?> startClass);
    164}