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;
025
026/**
027 * <p>
028 * A simple value class defining a {@link ConfigurationInterpolator}.
029 * </p>
030 * <p>
031 * Objects of this class can be used for creating new
032 * {@code ConfigurationInterpolator} instances; they contain all required
033 * properties. It is either possible to set a fully initialized
034 * {@code ConfigurationInterpolator} directly which can be used as is.
035 * Alternatively, some or all properties of an instance to be newly created can
036 * be set. These properties include
037 * </p>
038 * <ul>
039 * <li>a map with {@code Lookup} objects associated with a specific prefix</li>
040 * <li>a collection with default {@code Lookup} objects (without a prefix)</li>
041 * <li>a parent {@code ConfigurationInterpolator}</li>
042 * </ul>
043 * <p>
044 * When setting up a configuration it is possible to define the
045 * {@code ConfigurationInterpolator} in terms of this class. The configuration
046 * will then either use the {@code ConfigurationInterpolator} instance
047 * explicitly defined in the {@code InterpolatorSpecification} instance or
048 * create a new one.
049 * </p>
050 * <p>
051 * Instances are not created directly, but using the nested {@code Builder}
052 * class. They are then immutable.
053 * </p>
054 *
055 * @since 2.0
056 */
057public final class InterpolatorSpecification
058{
059    /** The {@code ConfigurationInterpolator} instance to be used directly. */
060    private final ConfigurationInterpolator interpolator;
061
062    /** The parent {@code ConfigurationInterpolator}. */
063    private final ConfigurationInterpolator parentInterpolator;
064
065    /** The map with prefix lookups. */
066    private final Map<String, Lookup> prefixLookups;
067
068    /** The collection with default lookups. */
069    private final Collection<Lookup> defaultLookups;
070
071    /**
072     * Creates a new instance of {@code InterpolatorSpecification} with the
073     * properties defined by the given builder object.
074     *
075     * @param builder the builder
076     */
077    private InterpolatorSpecification(final Builder builder)
078    {
079        interpolator = builder.interpolator;
080        parentInterpolator = builder.parentInterpolator;
081        prefixLookups =
082                Collections.unmodifiableMap(new HashMap<>(
083                        builder.prefixLookups));
084        defaultLookups =
085                Collections.unmodifiableCollection(new ArrayList<>(
086                        builder.defLookups));
087    }
088
089    /**
090     * Returns the {@code ConfigurationInterpolator} instance to be used
091     * directly.
092     *
093     * @return the {@code ConfigurationInterpolator} (can be <b>null</b>)
094     */
095    public ConfigurationInterpolator getInterpolator()
096    {
097        return interpolator;
098    }
099
100    /**
101     * Returns the parent {@code ConfigurationInterpolator} object.
102     *
103     * @return the parent {@code ConfigurationInterpolator} (can be <b>null</b>)
104     */
105    public ConfigurationInterpolator getParentInterpolator()
106    {
107        return parentInterpolator;
108    }
109
110    /**
111     * Returns a map with prefix lookups. The keys of the map are the prefix
112     * strings, its values are the corresponding {@code Lookup} objects.
113     *
114     * @return the prefix lookups for a new {@code ConfigurationInterpolator}
115     *         instance (never <b>null</b>)
116     */
117    public Map<String, Lookup> getPrefixLookups()
118    {
119        return prefixLookups;
120    }
121
122    /**
123     * Returns a collection with the default lookups.
124     *
125     * @return the default lookups for a new {@code ConfigurationInterpolator}
126     *         instance (never <b>null</b>)
127     */
128    public Collection<Lookup> getDefaultLookups()
129    {
130        return defaultLookups;
131    }
132
133    /**
134     * <p>A <em>builder</em> class for creating instances of
135     * {@code InterpolatorSpecification}.</p>
136     * <p>
137     * This class provides a fluent API for defining the various properties of
138     * an {@code InterpolatorSpecification} object. <em>Note:</em> This builder
139     * class is not thread-safe.
140     * </p>
141     */
142    public static class Builder
143    {
144        /** A map with prefix lookups. */
145        private final Map<String, Lookup> prefixLookups;
146
147        /** A collection with default lookups. */
148        private final Collection<Lookup> defLookups;
149
150        /** The {@code ConfigurationInterpolator}. */
151        private ConfigurationInterpolator interpolator;
152
153        /** The parent {@code ConfigurationInterpolator}. */
154        private ConfigurationInterpolator parentInterpolator;
155
156        public Builder()
157        {
158            prefixLookups = new HashMap<>();
159            defLookups = new LinkedList<>();
160        }
161
162        /**
163         * Adds a {@code Lookup} object for a given prefix.
164         *
165         * @param prefix the prefix (must not be <b>null</b>)
166         * @param lookup the {@code Lookup} (must not be <b>null</b>)
167         * @return a reference to this builder for method chaining
168         * @throws IllegalArgumentException if a required parameter is missing
169         */
170        public Builder withPrefixLookup(final String prefix, final Lookup lookup)
171        {
172            if (prefix == null)
173            {
174                throw new IllegalArgumentException("Prefix must not be null!");
175            }
176            checkLookup(lookup);
177            prefixLookups.put(prefix, lookup);
178            return this;
179        }
180
181        /**
182         * Adds the content of the given map to the prefix lookups managed by
183         * this builder. The map can be <b>null</b>, then this method has no
184         * effect.
185         *
186         * @param lookups the map with prefix lookups to be added
187         * @return a reference to this builder for method chaining
188         * @throws IllegalArgumentException if the map contains <b>null</b>
189         *         values
190         */
191        public Builder withPrefixLookups(final Map<String, ? extends Lookup> lookups)
192        {
193            if (lookups != null)
194            {
195                for (final Map.Entry<String, ? extends Lookup> e : lookups.entrySet())
196                {
197                    withPrefixLookup(e.getKey(), e.getValue());
198                }
199            }
200            return this;
201        }
202
203        /**
204         * Adds the given {@code Lookup} object to the list of default lookups.
205         *
206         * @param lookup the {@code Lookup} (must not be <b>null</b>)
207         * @return a reference to this builder for method chaining
208         * @throws IllegalArgumentException if the {@code Lookup} is <b>null</b>
209         */
210        public Builder withDefaultLookup(final Lookup lookup)
211        {
212            checkLookup(lookup);
213            defLookups.add(lookup);
214            return this;
215        }
216
217        /**
218         * Adds the content of the given collection to the default lookups
219         * managed by this builder. The collection can be <b>null</b>, then this
220         * method has no effect.
221         *
222         * @param lookups the collection with lookups to be added
223         * @return a reference to this builder for method chaining
224         * @throws IllegalArgumentException if the collection contains
225         *         <b>null</b> entries
226         */
227        public Builder withDefaultLookups(final Collection<? extends Lookup> lookups)
228        {
229            if (lookups != null)
230            {
231                for (final Lookup l : lookups)
232                {
233                    withDefaultLookup(l);
234                }
235            }
236            return this;
237        }
238
239        /**
240         * Sets the {@code ConfigurationInterpolator} instance for the
241         * {@code InterpolatorSpecification}. This means that a
242         * {@code ConfigurationInterpolator} has been created and set up
243         * externally and can be used directly.
244         *
245         * @param ci the {@code ConfigurationInterpolator} (can be <b>null</b>)
246         * @return a reference to this builder for method chaining
247         */
248        public Builder withInterpolator(final ConfigurationInterpolator ci)
249        {
250            interpolator = ci;
251            return this;
252        }
253
254        /**
255         * Sets an optional parent {@code ConfigurationInterpolator}. If
256         * defined, this object is set as parent of a newly created
257         * {@code ConfigurationInterpolator} instance.
258         *
259         * @param parent the parent {@code ConfigurationInterpolator} (can be
260         *        <b>null</b>)
261         * @return a reference to this builder for method chaining
262         */
263        public Builder withParentInterpolator(final ConfigurationInterpolator parent)
264        {
265            parentInterpolator = parent;
266            return this;
267        }
268
269        /**
270         * Creates a new {@code InterpolatorSpecification} instance with the
271         * properties set so far. After that this builder instance is reset so
272         * that it can be reused for creating further specification objects.
273         *
274         * @return the newly created {@code InterpolatorSpecification}
275         */
276        public InterpolatorSpecification create()
277        {
278            final InterpolatorSpecification spec =
279                    new InterpolatorSpecification(this);
280            reset();
281            return spec;
282        }
283
284        /**
285         * Removes all data from this builder. Afterwards it can be used to
286         * define a brand new {@code InterpolatorSpecification} object.
287         */
288        public void reset()
289        {
290            interpolator = null;
291            parentInterpolator = null;
292            prefixLookups.clear();
293            defLookups.clear();
294        }
295
296        /**
297         * Helper method for checking a lookup. Throws an exception if the
298         * lookup is <b>null</b>.
299         *
300         * @param lookup the lookup to be checked
301         * @throws IllegalArgumentException if the lookup is <b>null</b>
302         */
303        private static void checkLookup(final Lookup lookup)
304        {
305            if (lookup == null)
306            {
307                throw new IllegalArgumentException("Lookup must not be null!");
308            }
309        }
310    }
311}