InterpolatorSpecification.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.configuration2.interpol;

  19. import java.util.ArrayList;
  20. import java.util.Collection;
  21. import java.util.Collections;
  22. import java.util.HashMap;
  23. import java.util.LinkedList;
  24. import java.util.Map;
  25. import java.util.function.Function;

  27. /**
  28.  * <p>
  29.  * A simple value class defining a {@link ConfigurationInterpolator}.
  30.  * </p>
  31.  * <p>
  32.  * Objects of this class can be used for creating new {@code ConfigurationInterpolator} instances; they contain all
  33.  * required properties. It is either possible to set a fully initialized {@code ConfigurationInterpolator} directly
  34.  * which can be used as is. Alternatively, some or all properties of an instance to be newly created can be set. These
  35.  * properties include
  36.  * </p>
  37.  * <ul>
  38.  * <li>a map with {@code Lookup} objects associated with a specific prefix</li>
  39.  * <li>a collection with default {@code Lookup} objects (without a prefix)</li>
  40.  * <li>a parent {@code ConfigurationInterpolator}</li>
  41.  * <li>a function used to convert interpolated values into strings</li>
  42.  * </ul>
  43.  * <p>
  44.  * When setting up a configuration it is possible to define the {@code ConfigurationInterpolator} in terms of this
  45.  * class. The configuration will then either use the {@code ConfigurationInterpolator} instance explicitly defined in
  46.  * the {@code InterpolatorSpecification} instance or create a new one.
  47.  * </p>
  48.  * <p>
  49.  * Instances are not created directly, but using the nested {@code Builder} class. They are then immutable.
  50.  * </p>
  51.  *
  52.  * @since 2.0
  53.  */
  54. public final class InterpolatorSpecification {
  55.     /**
  56.      * <p>
  57.      * A <em>builder</em> class for creating instances of {@code InterpolatorSpecification}.
  58.      * </p>
  59.      * <p>
  60.      * This class provides a fluent API for defining the various properties of an {@code InterpolatorSpecification} object.
  61.      * <em>Note:</em> This builder class is not thread-safe.
  62.      * </p>
  63.      */
  64.     public static class Builder {
  65.         /**
  66.          * Helper method for checking a lookup. Throws an exception if the lookup is <strong>null</strong>.
  67.          *
  68.          * @param lookup the lookup to be checked
  69.          * @throws IllegalArgumentException if the lookup is <strong>null</strong>
  70.          */
  71.         private static void checkLookup(final Lookup lookup) {
  72.             if (lookup == null) {
  73.                 throw new IllegalArgumentException("Lookup must not be null!");
  74.             }
  75.         }

  77.         /** A map with prefix lookups. */
  78.         private final Map<String, Lookup> prefixLookups;

  80.         /** A collection with default lookups. */
  81.         private final Collection<Lookup> defLookups;

  83.         /** The {@code ConfigurationInterpolator}. */
  84.         private ConfigurationInterpolator interpolator;

  86.         /** The parent {@code ConfigurationInterpolator}. */
  87.         private ConfigurationInterpolator parentInterpolator;

  89.         /** Function used to convert interpolated values to strings. */
  90.         private Function<Object, String> stringConverter;

  92.         /**
  93.          * Constructs a new instance.
  94.          */
  95.         public Builder() {
  96.             prefixLookups = new HashMap<>();
  97.             defLookups = new LinkedList<>();
  98.         }

  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.         }

  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.         }

  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.         }

  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.         }

  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.         }

  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.         }

  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.         }

  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.         }

  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.     }

  222.     /** The {@code ConfigurationInterpolator} instance to be used directly. */
  223.     private final ConfigurationInterpolator interpolator;

  225.     /** The parent {@code ConfigurationInterpolator}. */
  226.     private final ConfigurationInterpolator parentInterpolator;

  228.     /** The map with prefix lookups. */
  229.     private final Map<String, Lookup> prefixLookups;

  231.     /** The collection with default lookups. */
  232.     private final Collection<Lookup> defaultLookups;

  234.     /** Function used to convert interpolated values to strings. */
  235.     private final Function<Object, String> stringConverter;

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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. }
Created with JaCoCo 0.8.12.202403310830