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