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.interpol;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.Collections;
22 import java.util.HashMap;
23 import java.util.LinkedList;
24 import java.util.Map;
25 import java.util.function.Function;
26
27 /**
28 * <p>
29 * A simple value class defining a {@link ConfigurationInterpolator}.
30 * </p>
31 * <p>
32 * Objects of this class can be used for creating new {@code ConfigurationInterpolator} instances; they contain all
33 * required properties. It is either possible to set a fully initialized {@code ConfigurationInterpolator} directly
34 * which can be used as is. Alternatively, some or all properties of an instance to be newly created can be set. These
35 * properties include
36 * </p>
37 * <ul>
38 * <li>a map with {@code Lookup} objects associated with a specific prefix</li>
39 * <li>a collection with default {@code Lookup} objects (without a prefix)</li>
40 * <li>a parent {@code ConfigurationInterpolator}</li>
41 * <li>a function used to convert interpolated values into strings</li>
42 * </ul>
43 * <p>
44 * When setting up a configuration it is possible to define the {@code ConfigurationInterpolator} in terms of this
45 * class. The configuration will then either use the {@code ConfigurationInterpolator} instance explicitly defined in
46 * the {@code InterpolatorSpecification} instance or create a new one.
47 * </p>
48 * <p>
49 * Instances are not created directly, but using the nested {@code Builder} class. They are then immutable.
50 * </p>
51 *
52 * @since 2.0
53 */
54 public final class InterpolatorSpecification {
55
56 /**
57 * <p>
58 * A <em>builder</em> class for creating instances of {@code InterpolatorSpecification}.
59 * </p>
60 * <p>
61 * This class provides a fluent API for defining the various properties of an {@code InterpolatorSpecification} object.
62 * <em>Note:</em> This builder class is not thread-safe.
63 * </p>
64 */
65 public static class Builder {
66
67 /**
68 * Helper method for checking a lookup. Throws an exception if the lookup is <strong>null</strong>.
69 *
70 * @param lookup the lookup to be checked
71 * @throws IllegalArgumentException if the lookup is <strong>null</strong>
72 */
73 private static void checkLookup(final Lookup lookup) {
74 if (lookup == null) {
75 throw new IllegalArgumentException("Lookup must not be null!");
76 }
77 }
78
79 /** A map with prefix lookups. */
80 private final Map<String, Lookup> prefixLookups;
81
82 /** A collection with default lookups. */
83 private final Collection<Lookup> defLookups;
84
85 /** The {@code ConfigurationInterpolator}. */
86 private ConfigurationInterpolator interpolator;
87
88 /** The parent {@code ConfigurationInterpolator}. */
89 private ConfigurationInterpolator parentInterpolator;
90
91 /** Function used to convert interpolated values to strings. */
92 private Function<Object, String> stringConverter;
93
94 /**
95 * Constructs a new instance.
96 */
97 public Builder() {
98 prefixLookups = new HashMap<>();
99 defLookups = new LinkedList<>();
100 }
101
102 /**
103 * Creates a new {@code InterpolatorSpecification} instance with the properties set so far. After that this builder
104 * instance is reset so that it can be reused for creating further specification objects.
105 *
106 * @return the newly created {@code InterpolatorSpecification}
107 */
108 public InterpolatorSpecification create() {
109 final InterpolatorSpecification spec = new InterpolatorSpecification(this);
110 reset();
111 return spec;
112 }
113
114 /**
115 * Removes all data from this builder. Afterwards it can be used to define a brand new {@code InterpolatorSpecification}
116 * object.
117 */
118 public void reset() {
119 interpolator = null;
120 parentInterpolator = null;
121 prefixLookups.clear();
122 defLookups.clear();
123 stringConverter = null;
124 }
125
126 /**
127 * Adds the given {@code Lookup} object to the list of default lookups.
128 *
129 * @param lookup the {@code Lookup} (must not be <strong>null</strong>)
130 * @return a reference to this builder for method chaining
131 * @throws IllegalArgumentException if the {@code Lookup} is <strong>null</strong>
132 */
133 public Builder withDefaultLookup(final Lookup lookup) {
134 checkLookup(lookup);
135 defLookups.add(lookup);
136 return this;
137 }
138
139 /**
140 * Adds the content of the given collection to the default lookups managed by this builder. The collection can be
141 * <strong>null</strong>, then this method has no effect.
142 *
143 * @param lookups the collection with lookups to be added
144 * @return a reference to this builder for method chaining
145 * @throws IllegalArgumentException if the collection contains <strong>null</strong> entries
146 */
147 public Builder withDefaultLookups(final Collection<? extends Lookup> lookups) {
148 if (lookups != null) {
149 lookups.forEach(this::withDefaultLookup);
150 }
151 return this;
152 }
153
154 /**
155 * Sets the {@code ConfigurationInterpolator} instance for the {@code InterpolatorSpecification}. This means that a
156 * {@code ConfigurationInterpolator} has been created and set up externally and can be used directly.
157 *
158 * @param ci the {@code ConfigurationInterpolator} (can be <strong>null</strong>)
159 * @return a reference to this builder for method chaining
160 */
161 public Builder withInterpolator(final ConfigurationInterpolator ci) {
162 interpolator = ci;
163 return this;
164 }
165
166 /**
167 * Sets an optional parent {@code ConfigurationInterpolator}. If defined, this object is set as parent of a newly
168 * created {@code ConfigurationInterpolator} instance.
169 *
170 * @param parent the parent {@code ConfigurationInterpolator} (can be <strong>null</strong>)
171 * @return a reference to this builder for method chaining
172 */
173 public Builder withParentInterpolator(final ConfigurationInterpolator parent) {
174 parentInterpolator = parent;
175 return this;
176 }
177
178 /**
179 * Adds a {@code Lookup} object for a given prefix.
180 *
181 * @param prefix the prefix (must not be <strong>null</strong>)
182 * @param lookup the {@code Lookup} (must not be <strong>null</strong>)
183 * @return a reference to this builder for method chaining
184 * @throws IllegalArgumentException if a required parameter is missing
185 */
186 public Builder withPrefixLookup(final String prefix, final Lookup lookup) {
187 if (prefix == null) {
188 throw new IllegalArgumentException("Prefix must not be null!");
189 }
190 checkLookup(lookup);
191 prefixLookups.put(prefix, lookup);
192 return this;
193 }
194
195 /**
196 * Adds the content of the given map to the prefix lookups managed by this builder. The map can be <strong>null</strong>, then
197 * this method has no effect.
198 *
199 * @param lookups the map with prefix lookups to be added
200 * @return a reference to this builder for method chaining
201 * @throws IllegalArgumentException if the map contains <strong>null</strong> values
202 */
203 public Builder withPrefixLookups(final Map<String, ? extends Lookup> lookups) {
204 if (lookups != null) {
205 lookups.forEach(this::withPrefixLookup);
206 }
207 return this;
208 }
209
210 /**
211 * Sets the function used to convert interpolated values to strings. Pass {@code null}
212 * if the default conversion function is to be used.
213 *
214 * @param fn function used to convert interpolated values to string or {@code null} if the
215 * default conversion function is to be used
216 * @return a reference to this builder for method chaining
217 */
218 public Builder withStringConverter(final Function<Object, String> fn) {
219 this.stringConverter = fn;
220 return this;
221 }
222 }
223
224 /** The {@code ConfigurationInterpolator} instance to be used directly. */
225 private final ConfigurationInterpolator interpolator;
226
227 /** The parent {@code ConfigurationInterpolator}. */
228 private final ConfigurationInterpolator parentInterpolator;
229
230 /** The map with prefix lookups. */
231 private final Map<String, Lookup> prefixLookups;
232
233 /** The collection with default lookups. */
234 private final Collection<Lookup> defaultLookups;
235
236 /** Function used to convert interpolated values to strings. */
237 private final Function<Object, String> stringConverter;
238
239 /**
240 * Creates a new instance of {@code InterpolatorSpecification} with the properties defined by the given builder object.
241 *
242 * @param builder the builder
243 */
244 private InterpolatorSpecification(final Builder builder) {
245 interpolator = builder.interpolator;
246 parentInterpolator = builder.parentInterpolator;
247 prefixLookups = Collections.unmodifiableMap(new HashMap<>(builder.prefixLookups));
248 defaultLookups = Collections.unmodifiableCollection(new ArrayList<>(builder.defLookups));
249 stringConverter = builder.stringConverter;
250 }
251
252 /**
253 * Gets a collection with the default lookups.
254 *
255 * @return the default lookups for a new {@code ConfigurationInterpolator} instance (never <strong>null</strong>)
256 */
257 public Collection<Lookup> getDefaultLookups() {
258 return defaultLookups;
259 }
260
261 /**
262 * Gets the {@code ConfigurationInterpolator} instance to be used directly.
263 *
264 * @return the {@code ConfigurationInterpolator} (can be <strong>null</strong>)
265 */
266 public ConfigurationInterpolator getInterpolator() {
267 return interpolator;
268 }
269
270 /**
271 * Gets the parent {@code ConfigurationInterpolator} object.
272 *
273 * @return the parent {@code ConfigurationInterpolator} (can be <strong>null</strong>)
274 */
275 public ConfigurationInterpolator getParentInterpolator() {
276 return parentInterpolator;
277 }
278
279 /**
280 * Gets a map with prefix lookups. The keys of the map are the prefix strings, its values are the corresponding
281 * {@code Lookup} objects.
282 *
283 * @return the prefix lookups for a new {@code ConfigurationInterpolator} instance (never <strong>null</strong>)
284 */
285 public Map<String, Lookup> getPrefixLookups() {
286 return prefixLookups;
287 }
288
289 /**
290 * Gets the function used to convert interpolated values to strings or {@code null}
291 * if the default conversion function is to be used.
292 *
293 * @return function used to convert interpolated values to strings or {@code null} if
294 * the default conversion function is to be used
295 */
296 public Function<Object, String> getStringConverter() {
297 return stringConverter;
298 }
299 }