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