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}