1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.configuration2.builder.combined;
18
19 import org.apache.commons.configuration2.HierarchicalConfiguration;
20 import org.apache.commons.configuration2.builder.BuilderParameters;
21 import org.apache.commons.configuration2.builder.ConfigurationBuilder;
22 import org.apache.commons.configuration2.builder.DefaultParametersHandler;
23 import org.apache.commons.configuration2.builder.DefaultParametersManager;
24
25 /**
26 * <p>
27 * Definition of a properties interface for the parameters of a combined configuration builder.
28 * </p>
29 * <p>
30 * This interface defines a number of properties for adapting the construction of a combined configuration based on a
31 * definition configuration. Properties can be set in a fluent style.
32 * </p>
33 * <p>
34 * <strong>Important note:</strong> This interface is not intended to be implemented by client code! It defines a set of
35 * available properties and may be extended even in minor releases.
36 * </p>
37 *
38 * @since 2.0
39 * @param <T> the return type of all methods for allowing method chaining
40 */
41 public interface CombinedBuilderProperties<T> {
42 /**
43 * Registers a {@code DefaultParametersHandler} for child configuration sources. With this method an arbitrary number of
44 * handler objects can be set. When creating builders for child configuration sources their parameters are initialized
45 * by invoking all matching {@code DefaultParametersHandler}s on them. So, basically the same mechanism is used for the
46 * initialization of parameters for child configuration sources as for normal parameter objects.
47 *
48 * @param <D> the type of the handler to be registered
49 * @param paramClass the parameter class supported by the handler
50 * @param handler the {@code DefaultParametersHandler} to be registered
51 * @return a reference to this object for method chaining
52 * @see DefaultParametersManager#registerDefaultsHandler(Class, DefaultParametersHandler)
53 */
54 <D> T registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler);
55
56 /**
57 * Registers a {@code DefaultParametersHandler} for child configuration sources derived from the given start class. This
58 * method works like the overloaded variant, but limits the application of the defaults handler to specific child
59 * configuration sources.
60 *
61 * @param <D> the type of the handler to be registered
62 * @param paramClass the parameter class supported by the handler
63 * @param handler the {@code DefaultParametersHandler} to be registered
64 * @param startClass an optional start class in the hierarchy of parameter objects for which this handler should be
65 * applied
66 * @return a reference to this object for method chaining
67 * @see DefaultParametersManager#registerDefaultsHandler(Class, DefaultParametersHandler, Class)
68 */
69 <D> T registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler, Class<?> startClass);
70
71 /**
72 * Registers the given {@code ConfigurationBuilderProvider} for the specified tag name. This means that whenever this
73 * tag is encountered in a configuration definition file, the corresponding builder provider is invoked.
74 *
75 * @param tagName the name of the tag (must not be <b>null</b>)
76 * @param provider the {@code ConfigurationBuilderProvider} (must not be <b>null</b>)
77 * @return a reference to this object for method chaining
78 * @throws IllegalArgumentException if a required parameter is missing
79 */
80 T registerProvider(String tagName, ConfigurationBuilderProvider provider);
81
82 /**
83 * Sets the base path for this combined configuration builder. Normally it it not necessary to set the base path
84 * explicitly. Per default, relative file names of configuration sources are resolved based on the location of the
85 * definition file. If this is not desired or if the definition configuration is loaded by a different means, the base
86 * path for relative file names can be specified using this method.
87 *
88 * @param path the base path for resolving relative file names
89 * @return a reference to this object for method chaining
90 */
91 T setBasePath(String path);
92
93 /**
94 * Sets a {@code DefaultParametersManager} object responsible for managing the default parameter handlers to be applied
95 * on child configuration sources. When creating builders for child configuration sources their parameters are
96 * initialized using this {@code DefaultParametersManager} instance. This way, meaningful defaults can be set. Note that
97 * calling this method overrides all {@code DefaultParametersHandler} objects previously set by one of the
98 * {@code registerChildDefaultsHandler()} methods! So either use this method if a pre-configured manager object is to be
99 * set or call the {@code registerChildDefaultHandler()} methods with the handlers to be registered (in the latter case,
100 * it is not necessary to set a {@code DefaultParametersManager} explicitly; a default one is created behind the
101 * scenes).
102 *
103 * @param manager the {@code DefaultParametersManager}
104 * @return a reference to this object for method chaining
105 */
106 T setChildDefaultParametersManager(DefaultParametersManager manager);
107
108 /**
109 * Sets the {@code ConfigurationBuilder} for the definition configuration. This is the configuration which contains the
110 * configuration sources that form the combined configuration.
111 *
112 * @param builder the definition {@code ConfigurationBuilder}
113 * @return a reference to this object for method chaining
114 */
115 T setDefinitionBuilder(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder);
116
117 /**
118 * Sets the parameters object for the definition configuration builder. This property is evaluated only if the
119 * definition configuration builder is not set explicitly (using the {@link #setDefinitionBuilder(ConfigurationBuilder)}
120 * method). In this case, a builder for an XML configuration is created and configured with this parameters object.
121 *
122 * @param params the parameters object for the definition configuration builder
123 * @return a reference to this object for method chaining
124 */
125 T setDefinitionBuilderParameters(BuilderParameters params);
126
127 /**
128 * Sets a flag whether the child configurations created by a {@code CombinedConfigurationBuilder} should inherit the
129 * settings defined for the builder. This is typically useful because for configurations coming from homogeneous sources
130 * often similar conventions are used. Therefore, this flag is <b>true</b> per default.
131 *
132 * @param f the flag whether settings should be inherited by child configurations
133 * @return a reference to this object for method chaining
134 */
135 T setInheritSettings(boolean f);
136 }