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