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}