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 *     https://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.interpol;
018
019import java.util.ArrayList;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.HashMap;
023import java.util.LinkedList;
024import java.util.Map;
025import java.util.function.Function;
026
027/**
028 * <p>
029 * A simple value class defining a {@link ConfigurationInterpolator}.
030 * </p>
031 * <p>
032 * Objects of this class can be used for creating new {@code ConfigurationInterpolator} instances; they contain all
033 * required properties. It is either possible to set a fully initialized {@code ConfigurationInterpolator} directly
034 * which can be used as is. Alternatively, some or all properties of an instance to be newly created can be set. These
035 * properties include
036 * </p>
037 * <ul>
038 * <li>a map with {@code Lookup} objects associated with a specific prefix</li>
039 * <li>a collection with default {@code Lookup} objects (without a prefix)</li>
040 * <li>a parent {@code ConfigurationInterpolator}</li>
041 * <li>a function used to convert interpolated values into strings</li>
042 * </ul>
043 * <p>
044 * When setting up a configuration it is possible to define the {@code ConfigurationInterpolator} in terms of this
045 * class. The configuration will then either use the {@code ConfigurationInterpolator} instance explicitly defined in
046 * the {@code InterpolatorSpecification} instance or create a new one.
047 * </p>
048 * <p>
049 * Instances are not created directly, but using the nested {@code Builder} class. They are then immutable.
050 * </p>
051 *
052 * @since 2.0
053 */
054public final class InterpolatorSpecification {
055
056    /**
057     * <p>
058     * A <em>builder</em> class for creating instances of {@code InterpolatorSpecification}.
059     * </p>
060     * <p>
061     * This class provides a fluent API for defining the various properties of an {@code InterpolatorSpecification} object.
062     * <em>Note:</em> This builder class is not thread-safe.
063     * </p>
064     */
065    public static class Builder {
066
067        /**
068         * Helper method for checking a lookup. Throws an exception if the lookup is <strong>null</strong>.
069         *
070         * @param lookup the lookup to be checked
071         * @throws IllegalArgumentException if the lookup is <strong>null</strong>
072         */
073        private static void checkLookup(final Lookup lookup) {
074            if (lookup == null) {
075                throw new IllegalArgumentException("Lookup must not be null!");
076            }
077        }
078
079        /** A map with prefix lookups. */
080        private final Map<String, Lookup> prefixLookups;
081
082        /** A collection with default lookups. */
083        private final Collection<Lookup> defLookups;
084
085        /** The {@code ConfigurationInterpolator}. */
086        private ConfigurationInterpolator interpolator;
087
088        /** The parent {@code ConfigurationInterpolator}. */
089        private ConfigurationInterpolator parentInterpolator;
090
091        /** Function used to convert interpolated values to strings. */
092        private Function<Object, String> stringConverter;
093
094        /**
095         * Constructs a new instance.
096         */
097        public Builder() {
098            prefixLookups = new HashMap<>();
099            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}