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