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