Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ConfigurationInterpolator |
|
| 2.1818181818181817;2,182 |
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.configuration.interpol; | |
18 | ||
19 | import java.util.HashMap; | |
20 | import java.util.Map; | |
21 | import java.util.Set; | |
22 | ||
23 | import org.apache.commons.lang.text.StrLookup; | |
24 | ||
25 | /** | |
26 | * <p> | |
27 | * A class that handles interpolation (variable substitution) for configuration | |
28 | * objects. | |
29 | * </p> | |
30 | * <p> | |
31 | * Each instance of <code>AbstractConfiguration</code> is associated with an | |
32 | * object of this class. Each interpolation tasks are delegated to this object. | |
33 | * </p> | |
34 | * <p> | |
35 | * <code>ConfigurationInterpolator</code> works together with the | |
36 | * <code>StrSubstitutor</code> class from <a | |
37 | * href="http://jakarta.apache.org/commons/lang">Commons Lang</a>. By extending | |
38 | * <code>StrLookup</code> it is able to provide values for variables that | |
39 | * appear in expressions. | |
40 | * </p> | |
41 | * <p> | |
42 | * The basic idea of this class is that it can maintain a set of primitive | |
43 | * <code>StrLookup</code> objects, each of which are identified by a special | |
44 | * prefix. The variables to be processed have the form | |
45 | * <code>${prefix:name}</code>. <code>ConfigurationInterpolator</code> will | |
46 | * extract the prefix and determine, which primitive lookup object is registered | |
47 | * for it. Then the name of the variable is passed to this object to obtain the | |
48 | * actual value. It is also possible to define a default lookup object, which | |
49 | * will be used for variables that do not have a prefix. | |
50 | * </p> | |
51 | * <p> | |
52 | * When a new instance of this class is created it is initialized with a default | |
53 | * set of primitive lookup objects. This set can be customized using the static | |
54 | * methods <code>registerGlobalLookup()</code> and | |
55 | * <code>deregisterGlobalLookup()</code>. Per default it contains the | |
56 | * following standard lookup objects: | |
57 | * </p> | |
58 | * <p> | |
59 | * <table border="1"> | |
60 | * <tr> | |
61 | * <th>Prefix</th> | |
62 | * <th>Lookup object</th> | |
63 | * </tr> | |
64 | * <tr> | |
65 | * <td valign="top">sys</td> | |
66 | * <td>With this prefix a lookup object is associated that is able to resolve | |
67 | * system properties.</td> | |
68 | * </tr> | |
69 | * <tr> | |
70 | * <td valign="top">const</td> | |
71 | * <td>The <code>const</code> prefix indicates that a variable is to be | |
72 | * interpreted as a constant member field of a class (i.e. a field with the | |
73 | * <b>static final</b> modifiers). The name of the variable must be of the form | |
74 | * <code><full qualified class name>.<field name></code>, e.g. | |
75 | * <code>org.apache.commons.configuration.interpol.ConfigurationInterpolator.PREFIX_CONSTANTS | |
76 | * </code>.</td> | |
77 | * </tr> | |
78 | * </table> | |
79 | * </p> | |
80 | * <p> | |
81 | * After an instance has been created the current set of lookup objects can be | |
82 | * modified using the <code>registerLookup()</code> and | |
83 | * <code>deregisterLookup()</code> methods. The default lookup object (that is | |
84 | * invoked for variables without a prefix) can be set with the | |
85 | * <code>setDefaultLookup()</code> method. (If a | |
86 | * <code>ConfigurationInterpolator</code> instance is created by a | |
87 | * configuration object, this lookup points to the configuration itself, so that | |
88 | * variables are resolved using the configuration's properties. This ensures | |
89 | * backward compatibility to earlier version of Commons Configuration.) | |
90 | * </p> | |
91 | * <p> | |
92 | * Implementation node: Instances of this class are not thread-safe related to | |
93 | * modifications of their current set of registered lookup objects. It is | |
94 | * intended that each instance is associated with a single | |
95 | * <code>Configuration</conde> | |
96 | * object and used for its interpolation tasks.</p> | |
97 | * | |
98 | * @version $Id: ConfigurationInterpolator.java 491243 2006-12-30 16:04:03Z oheger $ | |
99 | * @since 1.4 | |
100 | * @author <a | |
101 | * href="http://jakarta.apache.org/commons/configuration/team-list.html">Commons | |
102 | * Configuration team</a> | |
103 | */ | |
104 | public class ConfigurationInterpolator extends StrLookup | |
105 | { | |
106 | /** | |
107 | * Constant for the prefix of the standard lookup object for resolving | |
108 | * system properties. | |
109 | */ | |
110 | public static final String PREFIX_SYSPROPERTIES = "sys"; | |
111 | ||
112 | /** | |
113 | * Constant for the prefix of the standard lookup object for resolving | |
114 | * constant values. | |
115 | */ | |
116 | public static final String PREFIX_CONSTANTS = "const"; | |
117 | ||
118 | /** Constant for the prefix separator. */ | |
119 | private static final char PREFIX_SEPARATOR = ':'; | |
120 | ||
121 | /** A map with the globally registered lookup objects. */ | |
122 | private static Map globalLookups; | |
123 | ||
124 | /** A map with the locally registered lookup objects. */ | |
125 | private Map localLookups; | |
126 | ||
127 | /** Stores the default lookup object. */ | |
128 | private StrLookup defaultLookup; | |
129 | ||
130 | /** | |
131 | * Creates a new instance of <code>ConfigurationInterpolator</code>. | |
132 | */ | |
133 | public ConfigurationInterpolator() | |
134 | 475 | { |
135 | 475 | synchronized (globalLookups) |
136 | { | |
137 | 475 | localLookups = new HashMap(globalLookups); |
138 | 475 | } |
139 | 475 | } |
140 | ||
141 | /** | |
142 | * Registers the given lookup object for the specified prefix globally. This | |
143 | * means that all instances that are created later will use this lookup | |
144 | * object for this prefix. If for this prefix a lookup object is already | |
145 | * registered, the new lookup object will replace the old one. Note that the | |
146 | * lookup objects registered here will be shared between multiple clients. | |
147 | * So they should be thread-safe. | |
148 | * | |
149 | * @param prefix the variable prefix (must not be <b>null</b>) | |
150 | * @param lookup the lookup object to be used for this prefix (must not be | |
151 | * <b>null</b>) | |
152 | */ | |
153 | public static void registerGlobalLookup(String prefix, StrLookup lookup) | |
154 | { | |
155 | 4 | if (prefix == null) |
156 | { | |
157 | 1 | throw new IllegalArgumentException( |
158 | "Prefix for lookup object must not be null!"); | |
159 | } | |
160 | 3 | if (lookup == null) |
161 | { | |
162 | 1 | throw new IllegalArgumentException( |
163 | "Lookup object must not be null!"); | |
164 | } | |
165 | 2 | synchronized (globalLookups) |
166 | { | |
167 | 2 | globalLookups.put(prefix, lookup); |
168 | 2 | } |
169 | 2 | } |
170 | ||
171 | /** | |
172 | * Deregisters the global lookup object for the specified prefix. This means | |
173 | * that this lookup object won't be available for later created instances | |
174 | * any more. For already existing instances this operation does not have any | |
175 | * impact. | |
176 | * | |
177 | * @param prefix the variable prefix | |
178 | * @return a flag whether for this prefix a lookup object had been | |
179 | * registered | |
180 | */ | |
181 | public static boolean deregisterGlobalLookup(String prefix) | |
182 | { | |
183 | 23 | synchronized (globalLookups) |
184 | { | |
185 | 23 | return globalLookups.remove(prefix) != null; |
186 | 0 | } |
187 | } | |
188 | ||
189 | /** | |
190 | * Registers the given lookup object for the specified prefix at this | |
191 | * instance. From now on this lookup object will be used for variables that | |
192 | * have the specified prefix. | |
193 | * | |
194 | * @param prefix the variable prefix (must not be <b>null</b>) | |
195 | * @param lookup the lookup object to be used for this prefix (must not be | |
196 | * <b>null</b>) | |
197 | */ | |
198 | public void registerLookup(String prefix, StrLookup lookup) | |
199 | { | |
200 | 9 | if (prefix == null) |
201 | { | |
202 | 1 | throw new IllegalArgumentException( |
203 | "Prefix for lookup object must not be null!"); | |
204 | } | |
205 | 8 | if (lookup == null) |
206 | { | |
207 | 1 | throw new IllegalArgumentException( |
208 | "Lookup object must not be null!"); | |
209 | } | |
210 | 7 | localLookups.put(prefix, lookup); |
211 | 7 | } |
212 | ||
213 | /** | |
214 | * Deregisters the lookup object for the specified prefix at this instance. | |
215 | * It will be removed from this instance. | |
216 | * | |
217 | * @param prefix the variable prefix | |
218 | * @return a flag whether for this prefix a lookup object had been | |
219 | * registered | |
220 | */ | |
221 | public boolean deregisterLookup(String prefix) | |
222 | { | |
223 | 2 | return localLookups.remove(prefix) != null; |
224 | } | |
225 | ||
226 | /** | |
227 | * Returns a set with the prefixes, for which lookup objects are registered | |
228 | * at this instance. This means that variables with these prefixes can be | |
229 | * processed. | |
230 | * | |
231 | * @return a set with the registered variable prefixes | |
232 | */ | |
233 | public Set prefixSet() | |
234 | { | |
235 | 9 | return localLookups.keySet(); |
236 | } | |
237 | ||
238 | /** | |
239 | * Returns the default lookup object. | |
240 | * | |
241 | * @return the default lookup object | |
242 | */ | |
243 | public StrLookup getDefaultLookup() | |
244 | { | |
245 | 276 | return defaultLookup; |
246 | } | |
247 | ||
248 | /** | |
249 | * Sets the default lookup object. This lookup object will be used for all | |
250 | * variables without a special prefix. If it is set to <b>null</b>, such | |
251 | * variables won't be processed. | |
252 | * | |
253 | * @param defaultLookup the new default lookup object | |
254 | */ | |
255 | public void setDefaultLookup(StrLookup defaultLookup) | |
256 | { | |
257 | 453 | this.defaultLookup = defaultLookup; |
258 | 453 | } |
259 | ||
260 | /** | |
261 | * Resolves the specified variable. This implementation will try to extract | |
262 | * a variable prefix from the given variable name (the first colon (':') is | |
263 | * used as prefix separator). It then passes the name of the variable with | |
264 | * the prefix stripped to the lookup object registered for this prefix. If | |
265 | * no prefix can be found, the default lookup object will be used. | |
266 | * | |
267 | * @param var the name of the variable whose value is to be looked up | |
268 | * @return the value of this variable or <b>null</b> if it cannot be | |
269 | * resolved | |
270 | */ | |
271 | public String lookup(String var) | |
272 | { | |
273 | 204 | if (var == null) |
274 | { | |
275 | 1 | return null; |
276 | } | |
277 | ||
278 | 203 | int prefixPos = var.indexOf(PREFIX_SEPARATOR); |
279 | 203 | if (prefixPos < 0) |
280 | { | |
281 | 138 | return fetchNoPrefixLookup().lookup(var); |
282 | } | |
283 | else | |
284 | { | |
285 | 65 | String prefix = var.substring(0, prefixPos); |
286 | 65 | String name = var.substring(prefixPos + 1); |
287 | 65 | return fetchLookupForPrefix(prefix).lookup(name); |
288 | } | |
289 | } | |
290 | ||
291 | /** | |
292 | * Returns the lookup object to be used for variables without a prefix. This | |
293 | * implementation will check whether a default lookup object was set. If | |
294 | * this is the case, it will be returned. Otherwise a <b>null</b> lookup | |
295 | * object will be returned. | |
296 | * | |
297 | * @return the lookup object to be used for variables without a prefix | |
298 | */ | |
299 | protected StrLookup fetchNoPrefixLookup() | |
300 | { | |
301 | 138 | return (getDefaultLookup() != null) ? getDefaultLookup() : StrLookup |
302 | .noneLookup(); | |
303 | } | |
304 | ||
305 | /** | |
306 | * Obtains the lookup object for the specified prefix. This method is called | |
307 | * by the <code>lookup()</code> method. This implementation will check | |
308 | * whether a lookup object is registered for the given prefix. If not, a | |
309 | * <b>null</b> lookup object will be returned. | |
310 | * | |
311 | * @param prefix the prefix | |
312 | * @return the lookup object to be used for this prefix | |
313 | */ | |
314 | protected StrLookup fetchLookupForPrefix(String prefix) | |
315 | { | |
316 | 65 | StrLookup lookup = (StrLookup) localLookups.get(prefix); |
317 | 65 | if (lookup == null) |
318 | { | |
319 | 2 | lookup = StrLookup.noneLookup(); |
320 | } | |
321 | 65 | return lookup; |
322 | } | |
323 | ||
324 | // static initializer, sets up the map with the standard lookups | |
325 | static | |
326 | 48 | { |
327 | 48 | globalLookups = new HashMap(); |
328 | 48 | globalLookups.put(PREFIX_SYSPROPERTIES, StrLookup |
329 | .systemPropertiesLookup()); | |
330 | 48 | globalLookups.put(PREFIX_CONSTANTS, new ConstantLookup()); |
331 | } | |
332 | } |