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.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     * <p>
057     * A <em>builder</em> class for creating instances of {@code InterpolatorSpecification}.
058     * </p>
059     * <p>
060     * This class provides a fluent API for defining the various properties of an {@code InterpolatorSpecification} object.
061     * <em>Note:</em> This builder class is not thread-safe.
062     * </p>
063     */
064    public static class Builder {
065        /**
066         * Helper method for checking a lookup. Throws an exception if the lookup is <b>null</b>.
067         *
068         * @param lookup the lookup to be checked
069         * @throws IllegalArgumentException if the lookup is <b>null</b>
070         */
071        private static void checkLookup(final Lookup lookup) {
072            if (lookup == null) {
073                throw new IllegalArgumentException("Lookup must not be null!");
074            }
075        }
076
077        /** A map with prefix lookups. */
078        private final Map<String, Lookup> prefixLookups;
079
080        /** A collection with default lookups. */
081        private final Collection<Lookup> defLookups;
082
083        /** The {@code ConfigurationInterpolator}. */
084        private ConfigurationInterpolator interpolator;
085
086        /** The parent {@code ConfigurationInterpolator}. */
087        private ConfigurationInterpolator parentInterpolator;
088
089        /** Function used to convert interpolated values to strings. */
090        private Function<Object, String> stringConverter;
091
092        public Builder() {
093            prefixLookups = new HashMap<>();
094            defLookups = new LinkedList<>();
095        }
096
097        /**
098         * Creates a new {@code InterpolatorSpecification} instance with the properties set so far. After that this builder
099         * instance is reset so that it can be reused for creating further specification objects.
100         *
101         * @return the newly created {@code InterpolatorSpecification}
102         */
103        public InterpolatorSpecification create() {
104            final InterpolatorSpecification spec = new InterpolatorSpecification(this);
105            reset();
106            return spec;
107        }
108
109        /**
110         * Removes all data from this builder. Afterwards it can be used to define a brand new {@code InterpolatorSpecification}
111         * object.
112         */
113        public void reset() {
114            interpolator = null;
115            parentInterpolator = null;
116            prefixLookups.clear();
117            defLookups.clear();
118            stringConverter = null;
119        }
120
121        /**
122         * Adds the given {@code Lookup} object to the list of default lookups.
123         *
124         * @param lookup the {@code Lookup} (must not be <b>null</b>)
125         * @return a reference to this builder for method chaining
126         * @throws IllegalArgumentException if the {@code Lookup} is <b>null</b>
127         */
128        public Builder withDefaultLookup(final Lookup lookup) {
129            checkLookup(lookup);
130            defLookups.add(lookup);
131            return this;
132        }
133
134        /**
135         * Adds the content of the given collection to the default lookups managed by this builder. The collection can be
136         * <b>null</b>, then this method has no effect.
137         *
138         * @param lookups the collection with lookups to be added
139         * @return a reference to this builder for method chaining
140         * @throws IllegalArgumentException if the collection contains <b>null</b> entries
141         */
142        public Builder withDefaultLookups(final Collection<? extends Lookup> lookups) {
143            if (lookups != null) {
144                lookups.forEach(this::withDefaultLookup);
145            }
146            return this;
147        }
148
149        /**
150         * Sets the {@code ConfigurationInterpolator} instance for the {@code InterpolatorSpecification}. This means that a
151         * {@code ConfigurationInterpolator} has been created and set up externally and can be used directly.
152         *
153         * @param ci the {@code ConfigurationInterpolator} (can be <b>null</b>)
154         * @return a reference to this builder for method chaining
155         */
156        public Builder withInterpolator(final ConfigurationInterpolator ci) {
157            interpolator = ci;
158            return this;
159        }
160
161        /**
162         * Sets an optional parent {@code ConfigurationInterpolator}. If defined, this object is set as parent of a newly
163         * created {@code ConfigurationInterpolator} instance.
164         *
165         * @param parent the parent {@code ConfigurationInterpolator} (can be <b>null</b>)
166         * @return a reference to this builder for method chaining
167         */
168        public Builder withParentInterpolator(final ConfigurationInterpolator parent) {
169            parentInterpolator = parent;
170            return this;
171        }
172
173        /**
174         * Adds a {@code Lookup} object for a given prefix.
175         *
176         * @param prefix the prefix (must not be <b>null</b>)
177         * @param lookup the {@code Lookup} (must not be <b>null</b>)
178         * @return a reference to this builder for method chaining
179         * @throws IllegalArgumentException if a required parameter is missing
180         */
181        public Builder withPrefixLookup(final String prefix, final Lookup lookup) {
182            if (prefix == null) {
183                throw new IllegalArgumentException("Prefix must not be null!");
184            }
185            checkLookup(lookup);
186            prefixLookups.put(prefix, lookup);
187            return this;
188        }
189
190        /**
191         * Adds the content of the given map to the prefix lookups managed by this builder. The map can be <b>null</b>, then
192         * this method has no effect.
193         *
194         * @param lookups the map with prefix lookups to be added
195         * @return a reference to this builder for method chaining
196         * @throws IllegalArgumentException if the map contains <b>null</b> values
197         */
198        public Builder withPrefixLookups(final Map<String, ? extends Lookup> lookups) {
199            if (lookups != null) {
200                lookups.forEach(this::withPrefixLookup);
201            }
202            return this;
203        }
204
205        /**
206         * Sets the function used to convert interpolated values to strings. Pass {@code null}
207         * if the default conversion function is to be used.
208         *
209         * @param fn function used to convert interpolated values to string or {@code null} if the
210         *      default conversion function is to be used
211         * @return a reference to this builder for method chaining
212         */
213        public Builder withStringConverter(final Function<Object, String> fn) {
214            this.stringConverter = fn;
215            return this;
216        }
217    }
218
219    /** The {@code ConfigurationInterpolator} instance to be used directly. */
220    private final ConfigurationInterpolator interpolator;
221
222    /** The parent {@code ConfigurationInterpolator}. */
223    private final ConfigurationInterpolator parentInterpolator;
224
225    /** The map with prefix lookups. */
226    private final Map<String, Lookup> prefixLookups;
227
228    /** The collection with default lookups. */
229    private final Collection<Lookup> defaultLookups;
230
231    /** Function used to convert interpolated values to strings. */
232    private final Function<Object, String> stringConverter;
233
234    /**
235     * Creates a new instance of {@code InterpolatorSpecification} with the properties defined by the given builder object.
236     *
237     * @param builder the builder
238     */
239    private InterpolatorSpecification(final Builder builder) {
240        interpolator = builder.interpolator;
241        parentInterpolator = builder.parentInterpolator;
242        prefixLookups = Collections.unmodifiableMap(new HashMap<>(builder.prefixLookups));
243        defaultLookups = Collections.unmodifiableCollection(new ArrayList<>(builder.defLookups));
244        stringConverter = builder.stringConverter;
245    }
246
247    /**
248     * Gets a collection with the default lookups.
249     *
250     * @return the default lookups for a new {@code ConfigurationInterpolator} instance (never <b>null</b>)
251     */
252    public Collection<Lookup> getDefaultLookups() {
253        return defaultLookups;
254    }
255
256    /**
257     * Gets the {@code ConfigurationInterpolator} instance to be used directly.
258     *
259     * @return the {@code ConfigurationInterpolator} (can be <b>null</b>)
260     */
261    public ConfigurationInterpolator getInterpolator() {
262        return interpolator;
263    }
264
265    /**
266     * Gets the parent {@code ConfigurationInterpolator} object.
267     *
268     * @return the parent {@code ConfigurationInterpolator} (can be <b>null</b>)
269     */
270    public ConfigurationInterpolator getParentInterpolator() {
271        return parentInterpolator;
272    }
273
274    /**
275     * Gets a map with prefix lookups. The keys of the map are the prefix strings, its values are the corresponding
276     * {@code Lookup} objects.
277     *
278     * @return the prefix lookups for a new {@code ConfigurationInterpolator} instance (never <b>null</b>)
279     */
280    public Map<String, Lookup> getPrefixLookups() {
281        return prefixLookups;
282    }
283
284    /**
285     * Gets the function used to convert interpolated values to strings or {@code null}
286     * if the default conversion function is to be used.
287     *
288     * @return function used to convert interpolated values to strings or {@code null} if
289     *      the default conversion function is to be used
290     */
291    public Function<Object, String> getStringConverter() {
292        return stringConverter;
293    }
294}