    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}