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 * https://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 * @param <T> the return type of all methods for allowing method chaining
39 * @since 2.0
40 */
41 public interface CombinedBuilderProperties<T> {
42
43 /**
44 * Registers a {@code DefaultParametersHandler} for child configuration sources. With this method an arbitrary number of
45 * handler objects can be set. When creating builders for child configuration sources their parameters are initialized
46 * by invoking all matching {@code DefaultParametersHandler}s on them. So, basically the same mechanism is used for the
47 * initialization of parameters for child configuration sources as for normal parameter objects.
48 *
49 * @param <D> the type of the handler to be registered
50 * @param paramClass the parameter class supported by the handler
51 * @param handler the {@code DefaultParametersHandler} to be registered
52 * @return a reference to this object for method chaining
53 * @see DefaultParametersManager#registerDefaultsHandler(Class, DefaultParametersHandler)
54 */
55 <D> T registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler);
56
57 /**
58 * Registers a {@code DefaultParametersHandler} for child configuration sources derived from the given start class. This
59 * method works like the overloaded variant, but limits the application of the defaults handler to specific child
60 * configuration sources.
61 *
62 * @param <D> the type of the handler to be registered
63 * @param paramClass the parameter class supported by the handler
64 * @param handler the {@code DefaultParametersHandler} to be registered
65 * @param startClass an optional start class in the hierarchy of parameter objects for which this handler should be
66 * applied
67 * @return a reference to this object for method chaining
68 * @see DefaultParametersManager#registerDefaultsHandler(Class, DefaultParametersHandler, Class)
69 */
70 <D> T registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler, Class<?> startClass);
71
72 /**
73 * Registers the given {@code ConfigurationBuilderProvider} for the specified tag name. This means that whenever this
74 * tag is encountered in a configuration definition file, the corresponding builder provider is invoked.
75 *
76 * @param tagName the name of the tag (must not be <strong>null</strong>)
77 * @param provider the {@code ConfigurationBuilderProvider} (must not be <strong>null</strong>)
78 * @return a reference to this object for method chaining
79 * @throws IllegalArgumentException if a required parameter is missing
80 */
81 T registerProvider(String tagName, ConfigurationBuilderProvider provider);
82
83 /**
84 * Sets the base path for this combined configuration builder. Normally it it not necessary to set the base path
85 * explicitly. Per default, relative file names of configuration sources are resolved based on the location of the
86 * definition file. If this is not desired or if the definition configuration is loaded by a different means, the base
87 * path for relative file names can be specified using this method.
88 *
89 * @param path the base path for resolving relative file names
90 * @return a reference to this object for method chaining
91 */
92 T setBasePath(String path);
93
94 /**
95 * Sets a {@code DefaultParametersManager} object responsible for managing the default parameter handlers to be applied
96 * on child configuration sources. When creating builders for child configuration sources their parameters are
97 * initialized using this {@code DefaultParametersManager} instance. This way, meaningful defaults can be set. Note that
98 * calling this method overrides all {@code DefaultParametersHandler} objects previously set by one of the
99 * {@code registerChildDefaultsHandler()} methods! So either use this method if a pre-configured manager object is to be
100 * set or call the {@code registerChildDefaultHandler()} methods with the handlers to be registered (in the latter case,
101 * it is not necessary to set a {@code DefaultParametersManager} explicitly; a default one is created behind the
102 * scenes).
103 *
104 * @param manager the {@code DefaultParametersManager}
105 * @return a reference to this object for method chaining
106 */
107 T setChildDefaultParametersManager(DefaultParametersManager manager);
108
109 /**
110 * Sets the {@code ConfigurationBuilder} for the definition configuration. This is the configuration which contains the
111 * configuration sources that form the combined configuration.
112 *
113 * @param builder the definition {@code ConfigurationBuilder}
114 * @return a reference to this object for method chaining
115 */
116 T setDefinitionBuilder(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder);
117
118 /**
119 * Sets the parameters object for the definition configuration builder. This property is evaluated only if the
120 * definition configuration builder is not set explicitly (using the {@link #setDefinitionBuilder(ConfigurationBuilder)}
121 * method). In this case, a builder for an XML configuration is created and configured with this parameters object.
122 *
123 * @param params the parameters object for the definition configuration builder
124 * @return a reference to this object for method chaining
125 */
126 T setDefinitionBuilderParameters(BuilderParameters params);
127
128 /**
129 * Sets a flag whether the child configurations created by a {@code CombinedConfigurationBuilder} should inherit the
130 * settings defined for the builder. This is typically useful because for configurations coming from homogeneous sources
131 * often similar conventions are used. Therefore, this flag is <strong>true</strong> per default.
132 *
133 * @param f the flag whether settings should be inherited by child configurations
134 * @return a reference to this object for method chaining
135 */
136 T setInheritSettings(boolean f);
137 }