001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.apache.hadoop.conf;
020
021 import java.io.BufferedInputStream;
022 import java.io.DataInput;
023 import java.io.DataOutput;
024 import java.io.File;
025 import java.io.FileInputStream;
026 import java.io.IOException;
027 import java.io.InputStream;
028 import java.io.InputStreamReader;
029 import java.io.OutputStream;
030 import java.io.OutputStreamWriter;
031 import java.io.Reader;
032 import java.io.Writer;
033 import java.lang.ref.WeakReference;
034 import java.net.InetSocketAddress;
035 import java.net.URL;
036 import java.util.ArrayList;
037 import java.util.Arrays;
038 import java.util.Collection;
039 import java.util.Collections;
040 import java.util.Enumeration;
041 import java.util.HashMap;
042 import java.util.HashSet;
043 import java.util.Iterator;
044 import java.util.LinkedList;
045 import java.util.List;
046 import java.util.ListIterator;
047 import java.util.Map;
048 import java.util.Map.Entry;
049 import java.util.Properties;
050 import java.util.Set;
051 import java.util.StringTokenizer;
052 import java.util.WeakHashMap;
053 import java.util.concurrent.CopyOnWriteArrayList;
054 import java.util.regex.Matcher;
055 import java.util.regex.Pattern;
056 import java.util.regex.PatternSyntaxException;
057 import java.util.concurrent.TimeUnit;
058 import java.util.concurrent.atomic.AtomicBoolean;
059 import java.util.concurrent.atomic.AtomicReference;
060
061 import javax.xml.parsers.DocumentBuilder;
062 import javax.xml.parsers.DocumentBuilderFactory;
063 import javax.xml.parsers.ParserConfigurationException;
064 import javax.xml.transform.Transformer;
065 import javax.xml.transform.TransformerException;
066 import javax.xml.transform.TransformerFactory;
067 import javax.xml.transform.dom.DOMSource;
068 import javax.xml.transform.stream.StreamResult;
069
070 import org.apache.commons.collections.map.UnmodifiableMap;
071 import org.apache.commons.logging.Log;
072 import org.apache.commons.logging.LogFactory;
073 import org.apache.hadoop.classification.InterfaceAudience;
074 import org.apache.hadoop.classification.InterfaceStability;
075 import org.apache.hadoop.fs.FileSystem;
076 import org.apache.hadoop.fs.Path;
077 import org.apache.hadoop.fs.CommonConfigurationKeys;
078 import org.apache.hadoop.io.Writable;
079 import org.apache.hadoop.io.WritableUtils;
080 import org.apache.hadoop.net.NetUtils;
081 import org.apache.hadoop.util.ReflectionUtils;
082 import org.apache.hadoop.util.StringInterner;
083 import org.apache.hadoop.util.StringUtils;
084 import org.codehaus.jackson.JsonFactory;
085 import org.codehaus.jackson.JsonGenerator;
086 import org.w3c.dom.DOMException;
087 import org.w3c.dom.Document;
088 import org.w3c.dom.Element;
089 import org.w3c.dom.Node;
090 import org.w3c.dom.NodeList;
091 import org.w3c.dom.Text;
092 import org.xml.sax.SAXException;
093
094 import com.google.common.base.Preconditions;
095
096 /**
097 * Provides access to configuration parameters.
098 *
099 * <h4 id="Resources">Resources</h4>
100 *
101 * <p>Configurations are specified by resources. A resource contains a set of
102 * name/value pairs as XML data. Each resource is named by either a
103 * <code>String</code> or by a {@link Path}. If named by a <code>String</code>,
104 * then the classpath is examined for a file with that name. If named by a
105 * <code>Path</code>, then the local filesystem is examined directly, without
106 * referring to the classpath.
107 *
108 * <p>Unless explicitly turned off, Hadoop by default specifies two
109 * resources, loaded in-order from the classpath: <ol>
110 * <li><tt><a href="{@docRoot}/../core-default.html">core-default.xml</a>
111 * </tt>: Read-only defaults for hadoop.</li>
112 * <li><tt>core-site.xml</tt>: Site-specific configuration for a given hadoop
113 * installation.</li>
114 * </ol>
115 * Applications may add additional resources, which are loaded
116 * subsequent to these resources in the order they are added.
117 *
118 * <h4 id="FinalParams">Final Parameters</h4>
119 *
120 * <p>Configuration parameters may be declared <i>final</i>.
121 * Once a resource declares a value final, no subsequently-loaded
122 * resource can alter that value.
123 * For example, one might define a final parameter with:
124 * <tt><pre>
125 * <property>
126 * <name>dfs.hosts.include</name>
127 * <value>/etc/hadoop/conf/hosts.include</value>
128 * <b><final>true</final></b>
129 * </property></pre></tt>
130 *
131 * Administrators typically define parameters as final in
132 * <tt>core-site.xml</tt> for values that user applications may not alter.
133 *
134 * <h4 id="VariableExpansion">Variable Expansion</h4>
135 *
136 * <p>Value strings are first processed for <i>variable expansion</i>. The
137 * available properties are:<ol>
138 * <li>Other properties defined in this Configuration; and, if a name is
139 * undefined here,</li>
140 * <li>Properties in {@link System#getProperties()}.</li>
141 * </ol>
142 *
143 * <p>For example, if a configuration resource contains the following property
144 * definitions:
145 * <tt><pre>
146 * <property>
147 * <name>basedir</name>
148 * <value>/user/${<i>user.name</i>}</value>
149 * </property>
150 *
151 * <property>
152 * <name>tempdir</name>
153 * <value>${<i>basedir</i>}/tmp</value>
154 * </property></pre></tt>
155 *
156 * When <tt>conf.get("tempdir")</tt> is called, then <tt>${<i>basedir</i>}</tt>
157 * will be resolved to another property in this Configuration, while
158 * <tt>${<i>user.name</i>}</tt> would then ordinarily be resolved to the value
159 * of the System property with that name.
160 * By default, warnings will be given to any deprecated configuration
161 * parameters and these are suppressible by configuring
162 * <tt>log4j.logger.org.apache.hadoop.conf.Configuration.deprecation</tt> in
163 * log4j.properties file.
164 */
165 @InterfaceAudience.Public
166 @InterfaceStability.Stable
167 public class Configuration implements Iterable<Map.Entry<String,String>>,
168 Writable {
169 private static final Log LOG =
170 LogFactory.getLog(Configuration.class);
171
172 private static final Log LOG_DEPRECATION =
173 LogFactory.getLog("org.apache.hadoop.conf.Configuration.deprecation");
174
175 private boolean quietmode = true;
176
177 private static class Resource {
178 private final Object resource;
179 private final String name;
180
181 public Resource(Object resource) {
182 this(resource, resource.toString());
183 }
184
185 public Resource(Object resource, String name) {
186 this.resource = resource;
187 this.name = name;
188 }
189
190 public String getName(){
191 return name;
192 }
193
194 public Object getResource() {
195 return resource;
196 }
197
198 @Override
199 public String toString() {
200 return name;
201 }
202 }
203
204 /**
205 * List of configuration resources.
206 */
207 private ArrayList<Resource> resources = new ArrayList<Resource>();
208
209 /**
210 * The value reported as the setting resource when a key is set
211 * by code rather than a file resource by dumpConfiguration.
212 */
213 static final String UNKNOWN_RESOURCE = "Unknown";
214
215
216 /**
217 * List of configuration parameters marked <b>final</b>.
218 */
219 private Set<String> finalParameters = new HashSet<String>();
220
221 private boolean loadDefaults = true;
222
223 /**
224 * Configuration objects
225 */
226 private static final WeakHashMap<Configuration,Object> REGISTRY =
227 new WeakHashMap<Configuration,Object>();
228
229 /**
230 * List of default Resources. Resources are loaded in the order of the list
231 * entries
232 */
233 private static final CopyOnWriteArrayList<String> defaultResources =
234 new CopyOnWriteArrayList<String>();
235
236 private static final Map<ClassLoader, Map<String, WeakReference<Class<?>>>>
237 CACHE_CLASSES = new WeakHashMap<ClassLoader, Map<String, WeakReference<Class<?>>>>();
238
239 /**
240 * Sentinel value to store negative cache results in {@link #CACHE_CLASSES}.
241 */
242 private static final Class<?> NEGATIVE_CACHE_SENTINEL =
243 NegativeCacheSentinel.class;
244
245 /**
246 * Stores the mapping of key to the resource which modifies or loads
247 * the key most recently
248 */
249 private HashMap<String, String[]> updatingResource;
250
251 /**
252 * Class to keep the information about the keys which replace the deprecated
253 * ones.
254 *
255 * This class stores the new keys which replace the deprecated keys and also
256 * gives a provision to have a custom message for each of the deprecated key
257 * that is being replaced. It also provides method to get the appropriate
258 * warning message which can be logged whenever the deprecated key is used.
259 */
260 private static class DeprecatedKeyInfo {
261 private final String[] newKeys;
262 private final String customMessage;
263 private final AtomicBoolean accessed = new AtomicBoolean(false);
264
265 DeprecatedKeyInfo(String[] newKeys, String customMessage) {
266 this.newKeys = newKeys;
267 this.customMessage = customMessage;
268 }
269
270 /**
271 * Method to provide the warning message. It gives the custom message if
272 * non-null, and default message otherwise.
273 * @param key the associated deprecated key.
274 * @return message that is to be logged when a deprecated key is used.
275 */
276 private final String getWarningMessage(String key) {
277 String warningMessage;
278 if(customMessage == null) {
279 StringBuilder message = new StringBuilder(key);
280 String deprecatedKeySuffix = " is deprecated. Instead, use ";
281 message.append(deprecatedKeySuffix);
282 for (int i = 0; i < newKeys.length; i++) {
283 message.append(newKeys[i]);
284 if(i != newKeys.length-1) {
285 message.append(", ");
286 }
287 }
288 warningMessage = message.toString();
289 }
290 else {
291 warningMessage = customMessage;
292 }
293 return warningMessage;
294 }
295
296 boolean getAndSetAccessed() {
297 return accessed.getAndSet(true);
298 }
299
300 public void clearAccessed() {
301 accessed.set(false);
302 }
303 }
304
305 /**
306 * A pending addition to the global set of deprecated keys.
307 */
308 public static class DeprecationDelta {
309 private final String key;
310 private final String[] newKeys;
311 private final String customMessage;
312
313 DeprecationDelta(String key, String[] newKeys, String customMessage) {
314 Preconditions.checkNotNull(key);
315 Preconditions.checkNotNull(newKeys);
316 Preconditions.checkArgument(newKeys.length > 0);
317 this.key = key;
318 this.newKeys = newKeys;
319 this.customMessage = customMessage;
320 }
321
322 public DeprecationDelta(String key, String newKey, String customMessage) {
323 this(key, new String[] { newKey }, customMessage);
324 }
325
326 public DeprecationDelta(String key, String newKey) {
327 this(key, new String[] { newKey }, null);
328 }
329
330 public String getKey() {
331 return key;
332 }
333
334 public String[] getNewKeys() {
335 return newKeys;
336 }
337
338 public String getCustomMessage() {
339 return customMessage;
340 }
341 }
342
343 /**
344 * The set of all keys which are deprecated.
345 *
346 * DeprecationContext objects are immutable.
347 */
348 private static class DeprecationContext {
349 /**
350 * Stores the deprecated keys, the new keys which replace the deprecated keys
351 * and custom message(if any provided).
352 */
353 private final Map<String, DeprecatedKeyInfo> deprecatedKeyMap;
354
355 /**
356 * Stores a mapping from superseding keys to the keys which they deprecate.
357 */
358 private final Map<String, String> reverseDeprecatedKeyMap;
359
360 /**
361 * Create a new DeprecationContext by copying a previous DeprecationContext
362 * and adding some deltas.
363 *
364 * @param other The previous deprecation context to copy, or null to start
365 * from nothing.
366 * @param deltas The deltas to apply.
367 */
368 @SuppressWarnings("unchecked")
369 DeprecationContext(DeprecationContext other, DeprecationDelta[] deltas) {
370 HashMap<String, DeprecatedKeyInfo> newDeprecatedKeyMap =
371 new HashMap<String, DeprecatedKeyInfo>();
372 HashMap<String, String> newReverseDeprecatedKeyMap =
373 new HashMap<String, String>();
374 if (other != null) {
375 for (Entry<String, DeprecatedKeyInfo> entry :
376 other.deprecatedKeyMap.entrySet()) {
377 newDeprecatedKeyMap.put(entry.getKey(), entry.getValue());
378 }
379 for (Entry<String, String> entry :
380 other.reverseDeprecatedKeyMap.entrySet()) {
381 newReverseDeprecatedKeyMap.put(entry.getKey(), entry.getValue());
382 }
383 }
384 for (DeprecationDelta delta : deltas) {
385 if (!newDeprecatedKeyMap.containsKey(delta.getKey())) {
386 DeprecatedKeyInfo newKeyInfo =
387 new DeprecatedKeyInfo(delta.getNewKeys(), delta.getCustomMessage());
388 newDeprecatedKeyMap.put(delta.key, newKeyInfo);
389 for (String newKey : delta.getNewKeys()) {
390 newReverseDeprecatedKeyMap.put(newKey, delta.key);
391 }
392 }
393 }
394 this.deprecatedKeyMap =
395 UnmodifiableMap.decorate(newDeprecatedKeyMap);
396 this.reverseDeprecatedKeyMap =
397 UnmodifiableMap.decorate(newReverseDeprecatedKeyMap);
398 }
399
400 Map<String, DeprecatedKeyInfo> getDeprecatedKeyMap() {
401 return deprecatedKeyMap;
402 }
403
404 Map<String, String> getReverseDeprecatedKeyMap() {
405 return reverseDeprecatedKeyMap;
406 }
407 }
408
409 private static DeprecationDelta[] defaultDeprecations =
410 new DeprecationDelta[] {
411 new DeprecationDelta("topology.script.file.name",
412 CommonConfigurationKeys.NET_TOPOLOGY_SCRIPT_FILE_NAME_KEY),
413 new DeprecationDelta("topology.script.number.args",
414 CommonConfigurationKeys.NET_TOPOLOGY_SCRIPT_NUMBER_ARGS_KEY),
415 new DeprecationDelta("hadoop.configured.node.mapping",
416 CommonConfigurationKeys.NET_TOPOLOGY_CONFIGURED_NODE_MAPPING_KEY),
417 new DeprecationDelta("topology.node.switch.mapping.impl",
418 CommonConfigurationKeys.NET_TOPOLOGY_NODE_SWITCH_MAPPING_IMPL_KEY),
419 new DeprecationDelta("dfs.df.interval",
420 CommonConfigurationKeys.FS_DF_INTERVAL_KEY),
421 new DeprecationDelta("hadoop.native.lib",
422 CommonConfigurationKeys.IO_NATIVE_LIB_AVAILABLE_KEY),
423 new DeprecationDelta("fs.default.name",
424 CommonConfigurationKeys.FS_DEFAULT_NAME_KEY),
425 new DeprecationDelta("dfs.umaskmode",
426 CommonConfigurationKeys.FS_PERMISSIONS_UMASK_KEY)
427 };
428
429 /**
430 * The global DeprecationContext.
431 */
432 private static AtomicReference<DeprecationContext> deprecationContext =
433 new AtomicReference<DeprecationContext>(
434 new DeprecationContext(null, defaultDeprecations));
435
436 /**
437 * Adds a set of deprecated keys to the global deprecations.
438 *
439 * This method is lockless. It works by means of creating a new
440 * DeprecationContext based on the old one, and then atomically swapping in
441 * the new context. If someone else updated the context in between us reading
442 * the old context and swapping in the new one, we try again until we win the
443 * race.
444 *
445 * @param deltas The deprecations to add.
446 */
447 public static void addDeprecations(DeprecationDelta[] deltas) {
448 DeprecationContext prev, next;
449 do {
450 prev = deprecationContext.get();
451 next = new DeprecationContext(prev, deltas);
452 } while (!deprecationContext.compareAndSet(prev, next));
453 }
454
455 /**
456 * Adds the deprecated key to the global deprecation map.
457 * It does not override any existing entries in the deprecation map.
458 * This is to be used only by the developers in order to add deprecation of
459 * keys, and attempts to call this method after loading resources once,
460 * would lead to <tt>UnsupportedOperationException</tt>
461 *
462 * If a key is deprecated in favor of multiple keys, they are all treated as
463 * aliases of each other, and setting any one of them resets all the others
464 * to the new value.
465 *
466 * If you have multiple deprecation entries to add, it is more efficient to
467 * use #addDeprecations(DeprecationDelta[] deltas) instead.
468 *
469 * @param key
470 * @param newKeys
471 * @param customMessage
472 * @deprecated use {@link #addDeprecation(String key, String newKey,
473 String customMessage)} instead
474 */
475 @Deprecated
476 public static void addDeprecation(String key, String[] newKeys,
477 String customMessage) {
478 addDeprecations(new DeprecationDelta[] {
479 new DeprecationDelta(key, newKeys, customMessage)
480 });
481 }
482
483 /**
484 * Adds the deprecated key to the global deprecation map.
485 * It does not override any existing entries in the deprecation map.
486 * This is to be used only by the developers in order to add deprecation of
487 * keys, and attempts to call this method after loading resources once,
488 * would lead to <tt>UnsupportedOperationException</tt>
489 *
490 * If you have multiple deprecation entries to add, it is more efficient to
491 * use #addDeprecations(DeprecationDelta[] deltas) instead.
492 *
493 * @param key
494 * @param newKey
495 * @param customMessage
496 */
497 public static void addDeprecation(String key, String newKey,
498 String customMessage) {
499 addDeprecation(key, new String[] {newKey}, customMessage);
500 }
501
502 /**
503 * Adds the deprecated key to the global deprecation map when no custom
504 * message is provided.
505 * It does not override any existing entries in the deprecation map.
506 * This is to be used only by the developers in order to add deprecation of
507 * keys, and attempts to call this method after loading resources once,
508 * would lead to <tt>UnsupportedOperationException</tt>
509 *
510 * If a key is deprecated in favor of multiple keys, they are all treated as
511 * aliases of each other, and setting any one of them resets all the others
512 * to the new value.
513 *
514 * If you have multiple deprecation entries to add, it is more efficient to
515 * use #addDeprecations(DeprecationDelta[] deltas) instead.
516 *
517 * @param key Key that is to be deprecated
518 * @param newKeys list of keys that take up the values of deprecated key
519 * @deprecated use {@link #addDeprecation(String key, String newKey)} instead
520 */
521 @Deprecated
522 public static void addDeprecation(String key, String[] newKeys) {
523 addDeprecation(key, newKeys, null);
524 }
525
526 /**
527 * Adds the deprecated key to the global deprecation map when no custom
528 * message is provided.
529 * It does not override any existing entries in the deprecation map.
530 * This is to be used only by the developers in order to add deprecation of
531 * keys, and attempts to call this method after loading resources once,
532 * would lead to <tt>UnsupportedOperationException</tt>
533 *
534 * If you have multiple deprecation entries to add, it is more efficient to
535 * use #addDeprecations(DeprecationDelta[] deltas) instead.
536 *
537 * @param key Key that is to be deprecated
538 * @param newKey key that takes up the value of deprecated key
539 */
540 public static void addDeprecation(String key, String newKey) {
541 addDeprecation(key, new String[] {newKey}, null);
542 }
543
544 /**
545 * checks whether the given <code>key</code> is deprecated.
546 *
547 * @param key the parameter which is to be checked for deprecation
548 * @return <code>true</code> if the key is deprecated and
549 * <code>false</code> otherwise.
550 */
551 public static boolean isDeprecated(String key) {
552 return deprecationContext.get().getDeprecatedKeyMap().containsKey(key);
553 }
554
555 /**
556 * Checks for the presence of the property <code>name</code> in the
557 * deprecation map. Returns the first of the list of new keys if present
558 * in the deprecation map or the <code>name</code> itself. If the property
559 * is not presently set but the property map contains an entry for the
560 * deprecated key, the value of the deprecated key is set as the value for
561 * the provided property name.
562 *
563 * @param name the property name
564 * @return the first property in the list of properties mapping
565 * the <code>name</code> or the <code>name</code> itself.
566 */
567 private String[] handleDeprecation(DeprecationContext deprecations,
568 String name) {
569 ArrayList<String > names = new ArrayList<String>();
570 if (isDeprecated(name)) {
571 DeprecatedKeyInfo keyInfo = deprecations.getDeprecatedKeyMap().get(name);
572 warnOnceIfDeprecated(deprecations, name);
573 for (String newKey : keyInfo.newKeys) {
574 if(newKey != null) {
575 names.add(newKey);
576 }
577 }
578 }
579 if(names.size() == 0) {
580 names.add(name);
581 }
582 for(String n : names) {
583 String deprecatedKey = deprecations.getReverseDeprecatedKeyMap().get(n);
584 if (deprecatedKey != null && !getOverlay().containsKey(n) &&
585 getOverlay().containsKey(deprecatedKey)) {
586 getProps().setProperty(n, getOverlay().getProperty(deprecatedKey));
587 getOverlay().setProperty(n, getOverlay().getProperty(deprecatedKey));
588 }
589 }
590 return names.toArray(new String[names.size()]);
591 }
592
593 private void handleDeprecation() {
594 LOG.debug("Handling deprecation for all properties in config...");
595 DeprecationContext deprecations = deprecationContext.get();
596 Set<Object> keys = new HashSet<Object>();
597 keys.addAll(getProps().keySet());
598 for (Object item: keys) {
599 LOG.debug("Handling deprecation for " + (String)item);
600 handleDeprecation(deprecations, (String)item);
601 }
602 }
603
604 static{
605 //print deprecation warning if hadoop-site.xml is found in classpath
606 ClassLoader cL = Thread.currentThread().getContextClassLoader();
607 if (cL == null) {
608 cL = Configuration.class.getClassLoader();
609 }
610 if(cL.getResource("hadoop-site.xml")!=null) {
611 LOG.warn("DEPRECATED: hadoop-site.xml found in the classpath. " +
612 "Usage of hadoop-site.xml is deprecated. Instead use core-site.xml, "
613 + "mapred-site.xml and hdfs-site.xml to override properties of " +
614 "core-default.xml, mapred-default.xml and hdfs-default.xml " +
615 "respectively");
616 }
617 addDefaultResource("core-default.xml");
618 addDefaultResource("org.apache.hadoop.conf.CoreDefaultProperties");
619 addDefaultResource("core-site.xml");
620 }
621
622 private Properties properties;
623 private Properties overlay;
624 private ClassLoader classLoader;
625 {
626 classLoader = Thread.currentThread().getContextClassLoader();
627 if (classLoader == null) {
628 classLoader = Configuration.class.getClassLoader();
629 }
630 }
631
632 /** A new configuration. */
633 public Configuration() {
634 this(true);
635 }
636
637 /** A new configuration where the behavior of reading from the default
638 * resources can be turned off.
639 *
640 * If the parameter {@code loadDefaults} is false, the new instance
641 * will not load resources from the default files.
642 * @param loadDefaults specifies whether to load from the default files
643 */
644 public Configuration(boolean loadDefaults) {
645 this.loadDefaults = loadDefaults;
646 updatingResource = new HashMap<String, String[]>();
647 synchronized(Configuration.class) {
648 REGISTRY.put(this, null);
649 }
650 }
651
652 /**
653 * A new configuration with the same settings cloned from another.
654 *
655 * @param other the configuration from which to clone settings.
656 */
657 @SuppressWarnings("unchecked")
658 public Configuration(Configuration other) {
659 this.resources = (ArrayList<Resource>) other.resources.clone();
660 synchronized(other) {
661 if (other.properties != null) {
662 this.properties = (Properties)other.properties.clone();
663 }
664
665 if (other.overlay!=null) {
666 this.overlay = (Properties)other.overlay.clone();
667 }
668
669 this.updatingResource = new HashMap<String, String[]>(other.updatingResource);
670 }
671
672 this.finalParameters = new HashSet<String>(other.finalParameters);
673 synchronized(Configuration.class) {
674 REGISTRY.put(this, null);
675 }
676 this.classLoader = other.classLoader;
677 this.loadDefaults = other.loadDefaults;
678 setQuietMode(other.getQuietMode());
679 }
680
681 /**
682 * Add a default resource. Resources are loaded in the order of the resources
683 * added.
684 * @param name file name. File should be present in the classpath.
685 */
686 public static synchronized void addDefaultResource(String name) {
687 if(!defaultResources.contains(name)) {
688 defaultResources.add(name);
689 for(Configuration conf : REGISTRY.keySet()) {
690 if(conf.loadDefaults) {
691 conf.reloadConfiguration();
692 }
693 }
694 }
695 }
696
697 /**
698 * Add a configuration resource.
699 *
700 * The properties of this resource will override properties of previously
701 * added resources, unless they were marked <a href="#Final">final</a>.
702 *
703 * @param name resource to be added, the classpath is examined for a file
704 * with that name.
705 */
706 public void addResource(String name) {
707 addResourceObject(new Resource(name));
708 }
709
710 /**
711 * Add a configuration resource.
712 *
713 * The properties of this resource will override properties of previously
714 * added resources, unless they were marked <a href="#Final">final</a>.
715 *
716 * @param url url of the resource to be added, the local filesystem is
717 * examined directly to find the resource, without referring to
718 * the classpath.
719 */
720 public void addResource(URL url) {
721 addResourceObject(new Resource(url));
722 }
723
724 /**
725 * Add a configuration resource.
726 *
727 * The properties of this resource will override properties of previously
728 * added resources, unless they were marked <a href="#Final">final</a>.
729 *
730 * @param file file-path of resource to be added, the local filesystem is
731 * examined directly to find the resource, without referring to
732 * the classpath.
733 */
734 public void addResource(Path file) {
735 addResourceObject(new Resource(file));
736 }
737
738 /**
739 * Add a configuration resource.
740 *
741 * The properties of this resource will override properties of previously
742 * added resources, unless they were marked <a href="#Final">final</a>.
743 *
744 * WARNING: The contents of the InputStream will be cached, by this method.
745 * So use this sparingly because it does increase the memory consumption.
746 *
747 * @param in InputStream to deserialize the object from. In will be read from
748 * when a get or set is called next. After it is read the stream will be
749 * closed.
750 */
751 public void addResource(InputStream in) {
752 addResourceObject(new Resource(in));
753 }
754
755 /**
756 * Add a configuration resource.
757 *
758 * The properties of this resource will override properties of previously
759 * added resources, unless they were marked <a href="#Final">final</a>.
760 *
761 * @param in InputStream to deserialize the object from.
762 * @param name the name of the resource because InputStream.toString is not
763 * very descriptive some times.
764 */
765 public void addResource(InputStream in, String name) {
766 addResourceObject(new Resource(in, name));
767 }
768
769
770 /**
771 * Reload configuration from previously added resources.
772 *
773 * This method will clear all the configuration read from the added
774 * resources, and final parameters. This will make the resources to
775 * be read again before accessing the values. Values that are added
776 * via set methods will overlay values read from the resources.
777 */
778 public synchronized void reloadConfiguration() {
779 properties = null; // trigger reload
780 finalParameters.clear(); // clear site-limits
781 }
782
783 private synchronized void addResourceObject(Resource resource) {
784 resources.add(resource); // add to resources
785 reloadConfiguration();
786 }
787
788 private static Pattern varPat = Pattern.compile("\\$\\{[^\\}\\$\u0020]+\\}");
789 private static int MAX_SUBST = 20;
790
791 private String substituteVars(String expr) {
792 if (expr == null) {
793 return null;
794 }
795 Matcher match = varPat.matcher("");
796 String eval = expr;
797 for(int s=0; s<MAX_SUBST; s++) {
798 match.reset(eval);
799 if (!match.find()) {
800 return eval;
801 }
802 String var = match.group();
803 var = var.substring(2, var.length()-1); // remove ${ .. }
804 String val = null;
805 try {
806 val = System.getProperty(var);
807 } catch(SecurityException se) {
808 LOG.warn("Unexpected SecurityException in Configuration", se);
809 }
810 if (val == null) {
811 val = getRaw(var);
812 }
813 if (val == null) {
814 return eval; // return literal ${var}: var is unbound
815 }
816 // substitute
817 eval = eval.substring(0, match.start())+val+eval.substring(match.end());
818 }
819 throw new IllegalStateException("Variable substitution depth too large: "
820 + MAX_SUBST + " " + expr);
821 }
822
823 /**
824 * Get the value of the <code>name</code> property, <code>null</code> if
825 * no such property exists. If the key is deprecated, it returns the value of
826 * the first key which replaces the deprecated key and is not null
827 *
828 * Values are processed for <a href="#VariableExpansion">variable expansion</a>
829 * before being returned.
830 *
831 * @param name the property name.
832 * @return the value of the <code>name</code> or its replacing property,
833 * or null if no such property exists.
834 */
835 public String get(String name) {
836 String[] names = handleDeprecation(deprecationContext.get(), name);
837 String result = null;
838 for(String n : names) {
839 result = substituteVars(getProps().getProperty(n));
840 }
841 return result;
842 }
843
844 /**
845 * Get the value of the <code>name</code> property as a trimmed <code>String</code>,
846 * <code>null</code> if no such property exists.
847 * If the key is deprecated, it returns the value of
848 * the first key which replaces the deprecated key and is not null
849 *
850 * Values are processed for <a href="#VariableExpansion">variable expansion</a>
851 * before being returned.
852 *
853 * @param name the property name.
854 * @return the value of the <code>name</code> or its replacing property,
855 * or null if no such property exists.
856 */
857 public String getTrimmed(String name) {
858 String value = get(name);
859
860 if (null == value) {
861 return null;
862 } else {
863 return value.trim();
864 }
865 }
866
867 /**
868 * Get the value of the <code>name</code> property as a trimmed <code>String</code>,
869 * <code>defaultValue</code> if no such property exists.
870 * See @{Configuration#getTrimmed} for more details.
871 *
872 * @param name the property name.
873 * @param defaultValue the property default value.
874 * @return the value of the <code>name</code> or defaultValue
875 * if it is not set.
876 */
877 public String getTrimmed(String name, String defaultValue) {
878 String ret = getTrimmed(name);
879 return ret == null ? defaultValue : ret;
880 }
881
882 /**
883 * Get the value of the <code>name</code> property, without doing
884 * <a href="#VariableExpansion">variable expansion</a>.If the key is
885 * deprecated, it returns the value of the first key which replaces
886 * the deprecated key and is not null.
887 *
888 * @param name the property name.
889 * @return the value of the <code>name</code> property or
890 * its replacing property and null if no such property exists.
891 */
892 public String getRaw(String name) {
893 String[] names = handleDeprecation(deprecationContext.get(), name);
894 String result = null;
895 for(String n : names) {
896 result = getProps().getProperty(n);
897 }
898 return result;
899 }
900
901 /**
902 * Returns alternative names (non-deprecated keys or previously-set deprecated keys)
903 * for a given non-deprecated key.
904 * If the given key is deprecated, return null.
905 *
906 * @param name property name.
907 * @return alternative names.
908 */
909 private String[] getAlternativeNames(String name) {
910 String altNames[] = null;
911 DeprecatedKeyInfo keyInfo = null;
912 DeprecationContext cur = deprecationContext.get();
913 String depKey = cur.getReverseDeprecatedKeyMap().get(name);
914 if(depKey != null) {
915 keyInfo = cur.getDeprecatedKeyMap().get(depKey);
916 if(keyInfo.newKeys.length > 0) {
917 if(getProps().containsKey(depKey)) {
918 //if deprecated key is previously set explicitly
919 List<String> list = new ArrayList<String>();
920 list.addAll(Arrays.asList(keyInfo.newKeys));
921 list.add(depKey);
922 altNames = list.toArray(new String[list.size()]);
923 }
924 else {
925 altNames = keyInfo.newKeys;
926 }
927 }
928 }
929 return altNames;
930 }
931
932 /**
933 * Set the <code>value</code> of the <code>name</code> property. If
934 * <code>name</code> is deprecated or there is a deprecated name associated to it,
935 * it sets the value to both names.
936 *
937 * @param name property name.
938 * @param value property value.
939 */
940 public void set(String name, String value) {
941 set(name, value, null);
942 }
943
944 /**
945 * Set the <code>value</code> of the <code>name</code> property. If
946 * <code>name</code> is deprecated, it also sets the <code>value</code> to
947 * the keys that replace the deprecated key.
948 *
949 * @param name property name.
950 * @param value property value.
951 * @param source the place that this configuration value came from
952 * (For debugging).
953 * @throws IllegalArgumentException when the value or name is null.
954 */
955 public void set(String name, String value, String source) {
956 Preconditions.checkArgument(
957 name != null,
958 "Property name must not be null");
959 Preconditions.checkArgument(
960 value != null,
961 "Property value must not be null");
962 DeprecationContext deprecations = deprecationContext.get();
963 if (deprecations.getDeprecatedKeyMap().isEmpty()) {
964 getProps();
965 }
966 getOverlay().setProperty(name, value);
967 getProps().setProperty(name, value);
968 String newSource = (source == null ? "programatically" : source);
969
970 if (!isDeprecated(name)) {
971 updatingResource.put(name, new String[] {newSource});
972 String[] altNames = getAlternativeNames(name);
973 if(altNames != null) {
974 for(String n: altNames) {
975 if(!n.equals(name)) {
976 getOverlay().setProperty(n, value);
977 getProps().setProperty(n, value);
978 updatingResource.put(n, new String[] {newSource});
979 }
980 }
981 }
982 }
983 else {
984 String[] names = handleDeprecation(deprecationContext.get(), name);
985 String altSource = "because " + name + " is deprecated";
986 for(String n : names) {
987 getOverlay().setProperty(n, value);
988 getProps().setProperty(n, value);
989 updatingResource.put(n, new String[] {altSource});
990 }
991 }
992 }
993
994 private void warnOnceIfDeprecated(DeprecationContext deprecations, String name) {
995 DeprecatedKeyInfo keyInfo = deprecations.getDeprecatedKeyMap().get(name);
996 if (keyInfo != null && !keyInfo.getAndSetAccessed()) {
997 LOG_DEPRECATION.info(keyInfo.getWarningMessage(name));
998 }
999 }
1000
1001 /**
1002 * Unset a previously set property.
1003 */
1004 public synchronized void unset(String name) {
1005 String[] names = null;
1006 if (!isDeprecated(name)) {
1007 names = getAlternativeNames(name);
1008 if(names == null) {
1009 names = new String[]{name};
1010 }
1011 }
1012 else {
1013 names = handleDeprecation(deprecationContext.get(), name);
1014 }
1015
1016 for(String n: names) {
1017 getOverlay().remove(n);
1018 getProps().remove(n);
1019 }
1020 }
1021
1022 /**
1023 * Sets a property if it is currently unset.
1024 * @param name the property name
1025 * @param value the new value
1026 */
1027 public synchronized void setIfUnset(String name, String value) {
1028 if (get(name) == null) {
1029 set(name, value);
1030 }
1031 }
1032
1033 private synchronized Properties getOverlay() {
1034 if (overlay==null){
1035 overlay=new Properties();
1036 }
1037 return overlay;
1038 }
1039
1040 /**
1041 * Get the value of the <code>name</code>. If the key is deprecated,
1042 * it returns the value of the first key which replaces the deprecated key
1043 * and is not null.
1044 * If no such property exists,
1045 * then <code>defaultValue</code> is returned.
1046 *
1047 * @param name property name.
1048 * @param defaultValue default value.
1049 * @return property value, or <code>defaultValue</code> if the property
1050 * doesn't exist.
1051 */
1052 public String get(String name, String defaultValue) {
1053 String[] names = handleDeprecation(deprecationContext.get(), name);
1054 String result = null;
1055 for(String n : names) {
1056 result = substituteVars(getProps().getProperty(n, defaultValue));
1057 }
1058 return result;
1059 }
1060
1061 /**
1062 * Get the value of the <code>name</code> property as an <code>int</code>.
1063 *
1064 * If no such property exists, the provided default value is returned,
1065 * or if the specified value is not a valid <code>int</code>,
1066 * then an error is thrown.
1067 *
1068 * @param name property name.
1069 * @param defaultValue default value.
1070 * @throws NumberFormatException when the value is invalid
1071 * @return property value as an <code>int</code>,
1072 * or <code>defaultValue</code>.
1073 */
1074 public int getInt(String name, int defaultValue) {
1075 String valueString = getTrimmed(name);
1076 if (valueString == null)
1077 return defaultValue;
1078 String hexString = getHexDigits(valueString);
1079 if (hexString != null) {
1080 return Integer.parseInt(hexString, 16);
1081 }
1082 return Integer.parseInt(valueString);
1083 }
1084
1085 /**
1086 * Get the value of the <code>name</code> property as a set of comma-delimited
1087 * <code>int</code> values.
1088 *
1089 * If no such property exists, an empty array is returned.
1090 *
1091 * @param name property name
1092 * @return property value interpreted as an array of comma-delimited
1093 * <code>int</code> values
1094 */
1095 public int[] getInts(String name) {
1096 String[] strings = getTrimmedStrings(name);
1097 int[] ints = new int[strings.length];
1098 for (int i = 0; i < strings.length; i++) {
1099 ints[i] = Integer.parseInt(strings[i]);
1100 }
1101 return ints;
1102 }
1103
1104 /**
1105 * Set the value of the <code>name</code> property to an <code>int</code>.
1106 *
1107 * @param name property name.
1108 * @param value <code>int</code> value of the property.
1109 */
1110 public void setInt(String name, int value) {
1111 set(name, Integer.toString(value));
1112 }
1113
1114
1115 /**
1116 * Get the value of the <code>name</code> property as a <code>long</code>.
1117 * If no such property exists, the provided default value is returned,
1118 * or if the specified value is not a valid <code>long</code>,
1119 * then an error is thrown.
1120 *
1121 * @param name property name.
1122 * @param defaultValue default value.
1123 * @throws NumberFormatException when the value is invalid
1124 * @return property value as a <code>long</code>,
1125 * or <code>defaultValue</code>.
1126 */
1127 public long getLong(String name, long defaultValue) {
1128 String valueString = getTrimmed(name);
1129 if (valueString == null)
1130 return defaultValue;
1131 String hexString = getHexDigits(valueString);
1132 if (hexString != null) {
1133 return Long.parseLong(hexString, 16);
1134 }
1135 return Long.parseLong(valueString);
1136 }
1137
1138 /**
1139 * Get the value of the <code>name</code> property as a <code>long</code> or
1140 * human readable format. If no such property exists, the provided default
1141 * value is returned, or if the specified value is not a valid
1142 * <code>long</code> or human readable format, then an error is thrown. You
1143 * can use the following suffix (case insensitive): k(kilo), m(mega), g(giga),
1144 * t(tera), p(peta), e(exa)
1145 *
1146 * @param name property name.
1147 * @param defaultValue default value.
1148 * @throws NumberFormatException when the value is invalid
1149 * @return property value as a <code>long</code>,
1150 * or <code>defaultValue</code>.
1151 */
1152 public long getLongBytes(String name, long defaultValue) {
1153 String valueString = getTrimmed(name);
1154 if (valueString == null)
1155 return defaultValue;
1156 return StringUtils.TraditionalBinaryPrefix.string2long(valueString);
1157 }
1158
1159 private String getHexDigits(String value) {
1160 boolean negative = false;
1161 String str = value;
1162 String hexString = null;
1163 if (value.startsWith("-")) {
1164 negative = true;
1165 str = value.substring(1);
1166 }
1167 if (str.startsWith("0x") || str.startsWith("0X")) {
1168 hexString = str.substring(2);
1169 if (negative) {
1170 hexString = "-" + hexString;
1171 }
1172 return hexString;
1173 }
1174 return null;
1175 }
1176
1177 /**
1178 * Set the value of the <code>name</code> property to a <code>long</code>.
1179 *
1180 * @param name property name.
1181 * @param value <code>long</code> value of the property.
1182 */
1183 public void setLong(String name, long value) {
1184 set(name, Long.toString(value));
1185 }
1186
1187 /**
1188 * Get the value of the <code>name</code> property as a <code>float</code>.
1189 * If no such property exists, the provided default value is returned,
1190 * or if the specified value is not a valid <code>float</code>,
1191 * then an error is thrown.
1192 *
1193 * @param name property name.
1194 * @param defaultValue default value.
1195 * @throws NumberFormatException when the value is invalid
1196 * @return property value as a <code>float</code>,
1197 * or <code>defaultValue</code>.
1198 */
1199 public float getFloat(String name, float defaultValue) {
1200 String valueString = getTrimmed(name);
1201 if (valueString == null)
1202 return defaultValue;
1203 return Float.parseFloat(valueString);
1204 }
1205
1206 /**
1207 * Set the value of the <code>name</code> property to a <code>float</code>.
1208 *
1209 * @param name property name.
1210 * @param value property value.
1211 */
1212 public void setFloat(String name, float value) {
1213 set(name,Float.toString(value));
1214 }
1215
1216 /**
1217 * Get the value of the <code>name</code> property as a <code>double</code>.
1218 * If no such property exists, the provided default value is returned,
1219 * or if the specified value is not a valid <code>double</code>,
1220 * then an error is thrown.
1221 *
1222 * @param name property name.
1223 * @param defaultValue default value.
1224 * @throws NumberFormatException when the value is invalid
1225 * @return property value as a <code>double</code>,
1226 * or <code>defaultValue</code>.
1227 */
1228 public double getDouble(String name, double defaultValue) {
1229 String valueString = getTrimmed(name);
1230 if (valueString == null)
1231 return defaultValue;
1232 return Double.parseDouble(valueString);
1233 }
1234
1235 /**
1236 * Set the value of the <code>name</code> property to a <code>double</code>.
1237 *
1238 * @param name property name.
1239 * @param value property value.
1240 */
1241 public void setDouble(String name, double value) {
1242 set(name,Double.toString(value));
1243 }
1244
1245 /**
1246 * Get the value of the <code>name</code> property as a <code>boolean</code>.
1247 * If no such property is specified, or if the specified value is not a valid
1248 * <code>boolean</code>, then <code>defaultValue</code> is returned.
1249 *
1250 * @param name property name.
1251 * @param defaultValue default value.
1252 * @return property value as a <code>boolean</code>,
1253 * or <code>defaultValue</code>.
1254 */
1255 public boolean getBoolean(String name, boolean defaultValue) {
1256 String valueString = getTrimmed(name);
1257 if (null == valueString || valueString.isEmpty()) {
1258 return defaultValue;
1259 }
1260
1261 valueString = valueString.toLowerCase();
1262
1263 if ("true".equals(valueString))
1264 return true;
1265 else if ("false".equals(valueString))
1266 return false;
1267 else return defaultValue;
1268 }
1269
1270 /**
1271 * Set the value of the <code>name</code> property to a <code>boolean</code>.
1272 *
1273 * @param name property name.
1274 * @param value <code>boolean</code> value of the property.
1275 */
1276 public void setBoolean(String name, boolean value) {
1277 set(name, Boolean.toString(value));
1278 }
1279
1280 /**
1281 * Set the given property, if it is currently unset.
1282 * @param name property name
1283 * @param value new value
1284 */
1285 public void setBooleanIfUnset(String name, boolean value) {
1286 setIfUnset(name, Boolean.toString(value));
1287 }
1288
1289 /**
1290 * Set the value of the <code>name</code> property to the given type. This
1291 * is equivalent to <code>set(<name>, value.toString())</code>.
1292 * @param name property name
1293 * @param value new value
1294 */
1295 public <T extends Enum<T>> void setEnum(String name, T value) {
1296 set(name, value.toString());
1297 }
1298
1299 /**
1300 * Return value matching this enumerated type.
1301 * @param name Property name
1302 * @param defaultValue Value returned if no mapping exists
1303 * @throws IllegalArgumentException If mapping is illegal for the type
1304 * provided
1305 */
1306 public <T extends Enum<T>> T getEnum(String name, T defaultValue) {
1307 final String val = get(name);
1308 return null == val
1309 ? defaultValue
1310 : Enum.valueOf(defaultValue.getDeclaringClass(), val);
1311 }
1312
1313 enum ParsedTimeDuration {
1314 NS {
1315 TimeUnit unit() { return TimeUnit.NANOSECONDS; }
1316 String suffix() { return "ns"; }
1317 },
1318 US {
1319 TimeUnit unit() { return TimeUnit.MICROSECONDS; }
1320 String suffix() { return "us"; }
1321 },
1322 MS {
1323 TimeUnit unit() { return TimeUnit.MILLISECONDS; }
1324 String suffix() { return "ms"; }
1325 },
1326 S {
1327 TimeUnit unit() { return TimeUnit.SECONDS; }
1328 String suffix() { return "s"; }
1329 },
1330 M {
1331 TimeUnit unit() { return TimeUnit.MINUTES; }
1332 String suffix() { return "m"; }
1333 },
1334 H {
1335 TimeUnit unit() { return TimeUnit.HOURS; }
1336 String suffix() { return "h"; }
1337 },
1338 D {
1339 TimeUnit unit() { return TimeUnit.DAYS; }
1340 String suffix() { return "d"; }
1341 };
1342 abstract TimeUnit unit();
1343 abstract String suffix();
1344 static ParsedTimeDuration unitFor(String s) {
1345 for (ParsedTimeDuration ptd : values()) {
1346 // iteration order is in decl order, so SECONDS matched last
1347 if (s.endsWith(ptd.suffix())) {
1348 return ptd;
1349 }
1350 }
1351 return null;
1352 }
1353 static ParsedTimeDuration unitFor(TimeUnit unit) {
1354 for (ParsedTimeDuration ptd : values()) {
1355 if (ptd.unit() == unit) {
1356 return ptd;
1357 }
1358 }
1359 return null;
1360 }
1361 }
1362
1363 /**
1364 * Set the value of <code>name</code> to the given time duration. This
1365 * is equivalent to <code>set(<name>, value + <time suffix>)</code>.
1366 * @param name Property name
1367 * @param value Time duration
1368 * @param unit Unit of time
1369 */
1370 public void setTimeDuration(String name, long value, TimeUnit unit) {
1371 set(name, value + ParsedTimeDuration.unitFor(unit).suffix());
1372 }
1373
1374 /**
1375 * Return time duration in the given time unit. Valid units are encoded in
1376 * properties as suffixes: nanoseconds (ns), microseconds (us), milliseconds
1377 * (ms), seconds (s), minutes (m), hours (h), and days (d).
1378 * @param name Property name
1379 * @param defaultValue Value returned if no mapping exists.
1380 * @param unit Unit to convert the stored property, if it exists.
1381 * @throws NumberFormatException If the property stripped of its unit is not
1382 * a number
1383 */
1384 public long getTimeDuration(String name, long defaultValue, TimeUnit unit) {
1385 String vStr = get(name);
1386 if (null == vStr) {
1387 return defaultValue;
1388 }
1389 vStr = vStr.trim();
1390 ParsedTimeDuration vUnit = ParsedTimeDuration.unitFor(vStr);
1391 if (null == vUnit) {
1392 LOG.warn("No unit for " + name + "(" + vStr + ") assuming " + unit);
1393 vUnit = ParsedTimeDuration.unitFor(unit);
1394 } else {
1395 vStr = vStr.substring(0, vStr.lastIndexOf(vUnit.suffix()));
1396 }
1397 return unit.convert(Long.parseLong(vStr), vUnit.unit());
1398 }
1399
1400 /**
1401 * Get the value of the <code>name</code> property as a <code>Pattern</code>.
1402 * If no such property is specified, or if the specified value is not a valid
1403 * <code>Pattern</code>, then <code>DefaultValue</code> is returned.
1404 *
1405 * @param name property name
1406 * @param defaultValue default value
1407 * @return property value as a compiled Pattern, or defaultValue
1408 */
1409 public Pattern getPattern(String name, Pattern defaultValue) {
1410 String valString = get(name);
1411 if (null == valString || valString.isEmpty()) {
1412 return defaultValue;
1413 }
1414 try {
1415 return Pattern.compile(valString);
1416 } catch (PatternSyntaxException pse) {
1417 LOG.warn("Regular expression '" + valString + "' for property '" +
1418 name + "' not valid. Using default", pse);
1419 return defaultValue;
1420 }
1421 }
1422
1423 /**
1424 * Set the given property to <code>Pattern</code>.
1425 * If the pattern is passed as null, sets the empty pattern which results in
1426 * further calls to getPattern(...) returning the default value.
1427 *
1428 * @param name property name
1429 * @param pattern new value
1430 */
1431 public void setPattern(String name, Pattern pattern) {
1432 if (null == pattern) {
1433 set(name, null);
1434 } else {
1435 set(name, pattern.pattern());
1436 }
1437 }
1438
1439 /**
1440 * Gets information about why a property was set. Typically this is the
1441 * path to the resource objects (file, URL, etc.) the property came from, but
1442 * it can also indicate that it was set programatically, or because of the
1443 * command line.
1444 *
1445 * @param name - The property name to get the source of.
1446 * @return null - If the property or its source wasn't found. Otherwise,
1447 * returns a list of the sources of the resource. The older sources are
1448 * the first ones in the list. So for example if a configuration is set from
1449 * the command line, and then written out to a file that is read back in the
1450 * first entry would indicate that it was set from the command line, while
1451 * the second one would indicate the file that the new configuration was read
1452 * in from.
1453 */
1454 @InterfaceStability.Unstable
1455 public synchronized String[] getPropertySources(String name) {
1456 if (properties == null) {
1457 // If properties is null, it means a resource was newly added
1458 // but the props were cleared so as to load it upon future
1459 // requests. So lets force a load by asking a properties list.
1460 getProps();
1461 }
1462 // Return a null right away if our properties still
1463 // haven't loaded or the resource mapping isn't defined
1464 if (properties == null || updatingResource == null) {
1465 return null;
1466 } else {
1467 String[] source = updatingResource.get(name);
1468 if(source == null) {
1469 return null;
1470 } else {
1471 return Arrays.copyOf(source, source.length);
1472 }
1473 }
1474 }
1475
1476 /**
1477 * A class that represents a set of positive integer ranges. It parses
1478 * strings of the form: "2-3,5,7-" where ranges are separated by comma and
1479 * the lower/upper bounds are separated by dash. Either the lower or upper
1480 * bound may be omitted meaning all values up to or over. So the string
1481 * above means 2, 3, 5, and 7, 8, 9, ...
1482 */
1483 public static class IntegerRanges implements Iterable<Integer>{
1484 private static class Range {
1485 int start;
1486 int end;
1487 }
1488
1489 private static class RangeNumberIterator implements Iterator<Integer> {
1490 Iterator<Range> internal;
1491 int at;
1492 int end;
1493
1494 public RangeNumberIterator(List<Range> ranges) {
1495 if (ranges != null) {
1496 internal = ranges.iterator();
1497 }
1498 at = -1;
1499 end = -2;
1500 }
1501
1502 @Override
1503 public boolean hasNext() {
1504 if (at <= end) {
1505 return true;
1506 } else if (internal != null){
1507 return internal.hasNext();
1508 }
1509 return false;
1510 }
1511
1512 @Override
1513 public Integer next() {
1514 if (at <= end) {
1515 at++;
1516 return at - 1;
1517 } else if (internal != null){
1518 Range found = internal.next();
1519 if (found != null) {
1520 at = found.start;
1521 end = found.end;
1522 at++;
1523 return at - 1;
1524 }
1525 }
1526 return null;
1527 }
1528
1529 @Override
1530 public void remove() {
1531 throw new UnsupportedOperationException();
1532 }
1533 };
1534
1535 List<Range> ranges = new ArrayList<Range>();
1536
1537 public IntegerRanges() {
1538 }
1539
1540 public IntegerRanges(String newValue) {
1541 StringTokenizer itr = new StringTokenizer(newValue, ",");
1542 while (itr.hasMoreTokens()) {
1543 String rng = itr.nextToken().trim();
1544 String[] parts = rng.split("-", 3);
1545 if (parts.length < 1 || parts.length > 2) {
1546 throw new IllegalArgumentException("integer range badly formed: " +
1547 rng);
1548 }
1549 Range r = new Range();
1550 r.start = convertToInt(parts[0], 0);
1551 if (parts.length == 2) {
1552 r.end = convertToInt(parts[1], Integer.MAX_VALUE);
1553 } else {
1554 r.end = r.start;
1555 }
1556 if (r.start > r.end) {
1557 throw new IllegalArgumentException("IntegerRange from " + r.start +
1558 " to " + r.end + " is invalid");
1559 }
1560 ranges.add(r);
1561 }
1562 }
1563
1564 /**
1565 * Convert a string to an int treating empty strings as the default value.
1566 * @param value the string value
1567 * @param defaultValue the value for if the string is empty
1568 * @return the desired integer
1569 */
1570 private static int convertToInt(String value, int defaultValue) {
1571 String trim = value.trim();
1572 if (trim.length() == 0) {
1573 return defaultValue;
1574 }
1575 return Integer.parseInt(trim);
1576 }
1577
1578 /**
1579 * Is the given value in the set of ranges
1580 * @param value the value to check
1581 * @return is the value in the ranges?
1582 */
1583 public boolean isIncluded(int value) {
1584 for(Range r: ranges) {
1585 if (r.start <= value && value <= r.end) {
1586 return true;
1587 }
1588 }
1589 return false;
1590 }
1591
1592 /**
1593 * @return true if there are no values in this range, else false.
1594 */
1595 public boolean isEmpty() {
1596 return ranges == null || ranges.isEmpty();
1597 }
1598
1599 @Override
1600 public String toString() {
1601 StringBuilder result = new StringBuilder();
1602 boolean first = true;
1603 for(Range r: ranges) {
1604 if (first) {
1605 first = false;
1606 } else {
1607 result.append(',');
1608 }
1609 result.append(r.start);
1610 result.append('-');
1611 result.append(r.end);
1612 }
1613 return result.toString();
1614 }
1615
1616 @Override
1617 public Iterator<Integer> iterator() {
1618 return new RangeNumberIterator(ranges);
1619 }
1620
1621 }
1622
1623 /**
1624 * Parse the given attribute as a set of integer ranges
1625 * @param name the attribute name
1626 * @param defaultValue the default value if it is not set
1627 * @return a new set of ranges from the configured value
1628 */
1629 public IntegerRanges getRange(String name, String defaultValue) {
1630 return new IntegerRanges(get(name, defaultValue));
1631 }
1632
1633 /**
1634 * Get the comma delimited values of the <code>name</code> property as
1635 * a collection of <code>String</code>s.
1636 * If no such property is specified then empty collection is returned.
1637 * <p>
1638 * This is an optimized version of {@link #getStrings(String)}
1639 *
1640 * @param name property name.
1641 * @return property value as a collection of <code>String</code>s.
1642 */
1643 public Collection<String> getStringCollection(String name) {
1644 String valueString = get(name);
1645 return StringUtils.getStringCollection(valueString);
1646 }
1647
1648 /**
1649 * Get the comma delimited values of the <code>name</code> property as
1650 * an array of <code>String</code>s.
1651 * If no such property is specified then <code>null</code> is returned.
1652 *
1653 * @param name property name.
1654 * @return property value as an array of <code>String</code>s,
1655 * or <code>null</code>.
1656 */
1657 public String[] getStrings(String name) {
1658 String valueString = get(name);
1659 return StringUtils.getStrings(valueString);
1660 }
1661
1662 /**
1663 * Get the comma delimited values of the <code>name</code> property as
1664 * an array of <code>String</code>s.
1665 * If no such property is specified then default value is returned.
1666 *
1667 * @param name property name.
1668 * @param defaultValue The default value
1669 * @return property value as an array of <code>String</code>s,
1670 * or default value.
1671 */
1672 public String[] getStrings(String name, String... defaultValue) {
1673 String valueString = get(name);
1674 if (valueString == null) {
1675 return defaultValue;
1676 } else {
1677 return StringUtils.getStrings(valueString);
1678 }
1679 }
1680
1681 /**
1682 * Get the comma delimited values of the <code>name</code> property as
1683 * a collection of <code>String</code>s, trimmed of the leading and trailing whitespace.
1684 * If no such property is specified then empty <code>Collection</code> is returned.
1685 *
1686 * @param name property name.
1687 * @return property value as a collection of <code>String</code>s, or empty <code>Collection</code>
1688 */
1689 public Collection<String> getTrimmedStringCollection(String name) {
1690 String valueString = get(name);
1691 if (null == valueString) {
1692 Collection<String> empty = new ArrayList<String>();
1693 return empty;
1694 }
1695 return StringUtils.getTrimmedStringCollection(valueString);
1696 }
1697
1698 /**
1699 * Get the comma delimited values of the <code>name</code> property as
1700 * an array of <code>String</code>s, trimmed of the leading and trailing whitespace.
1701 * If no such property is specified then an empty array is returned.
1702 *
1703 * @param name property name.
1704 * @return property value as an array of trimmed <code>String</code>s,
1705 * or empty array.
1706 */
1707 public String[] getTrimmedStrings(String name) {
1708 String valueString = get(name);
1709 return StringUtils.getTrimmedStrings(valueString);
1710 }
1711
1712 /**
1713 * Get the comma delimited values of the <code>name</code> property as
1714 * an array of <code>String</code>s, trimmed of the leading and trailing whitespace.
1715 * If no such property is specified then default value is returned.
1716 *
1717 * @param name property name.
1718 * @param defaultValue The default value
1719 * @return property value as an array of trimmed <code>String</code>s,
1720 * or default value.
1721 */
1722 public String[] getTrimmedStrings(String name, String... defaultValue) {
1723 String valueString = get(name);
1724 if (null == valueString) {
1725 return defaultValue;
1726 } else {
1727 return StringUtils.getTrimmedStrings(valueString);
1728 }
1729 }
1730
1731 /**
1732 * Set the array of string values for the <code>name</code> property as
1733 * as comma delimited values.
1734 *
1735 * @param name property name.
1736 * @param values The values
1737 */
1738 public void setStrings(String name, String... values) {
1739 set(name, StringUtils.arrayToString(values));
1740 }
1741
1742 /**
1743 * Get the socket address for <code>name</code> property as a
1744 * <code>InetSocketAddress</code>.
1745 * @param name property name.
1746 * @param defaultAddress the default value
1747 * @param defaultPort the default port
1748 * @return InetSocketAddress
1749 */
1750 public InetSocketAddress getSocketAddr(
1751 String name, String defaultAddress, int defaultPort) {
1752 final String address = get(name, defaultAddress);
1753 return NetUtils.createSocketAddr(address, defaultPort, name);
1754 }
1755
1756 /**
1757 * Set the socket address for the <code>name</code> property as
1758 * a <code>host:port</code>.
1759 */
1760 public void setSocketAddr(String name, InetSocketAddress addr) {
1761 set(name, NetUtils.getHostPortString(addr));
1762 }
1763
1764 /**
1765 * Set the socket address a client can use to connect for the
1766 * <code>name</code> property as a <code>host:port</code>. The wildcard
1767 * address is replaced with the local host's address.
1768 * @param name property name.
1769 * @param addr InetSocketAddress of a listener to store in the given property
1770 * @return InetSocketAddress for clients to connect
1771 */
1772 public InetSocketAddress updateConnectAddr(String name,
1773 InetSocketAddress addr) {
1774 final InetSocketAddress connectAddr = NetUtils.getConnectAddress(addr);
1775 setSocketAddr(name, connectAddr);
1776 return connectAddr;
1777 }
1778
1779 /**
1780 * Load a class by name.
1781 *
1782 * @param name the class name.
1783 * @return the class object.
1784 * @throws ClassNotFoundException if the class is not found.
1785 */
1786 public Class<?> getClassByName(String name) throws ClassNotFoundException {
1787 Class<?> ret = getClassByNameOrNull(name);
1788 if (ret == null) {
1789 throw new ClassNotFoundException("Class " + name + " not found");
1790 }
1791 return ret;
1792 }
1793
1794 /**
1795 * Load a class by name, returning null rather than throwing an exception
1796 * if it couldn't be loaded. This is to avoid the overhead of creating
1797 * an exception.
1798 *
1799 * @param name the class name
1800 * @return the class object, or null if it could not be found.
1801 */
1802 public Class<?> getClassByNameOrNull(String name) {
1803 Map<String, WeakReference<Class<?>>> map;
1804
1805 synchronized (CACHE_CLASSES) {
1806 map = CACHE_CLASSES.get(classLoader);
1807 if (map == null) {
1808 map = Collections.synchronizedMap(
1809 new WeakHashMap<String, WeakReference<Class<?>>>());
1810 CACHE_CLASSES.put(classLoader, map);
1811 }
1812 }
1813
1814 Class<?> clazz = null;
1815 WeakReference<Class<?>> ref = map.get(name);
1816 if (ref != null) {
1817 clazz = ref.get();
1818 }
1819
1820 if (clazz == null) {
1821 try {
1822 clazz = Class.forName(name, true, classLoader);
1823 } catch (ClassNotFoundException e) {
1824 // Leave a marker that the class isn't found
1825 map.put(name, new WeakReference<Class<?>>(NEGATIVE_CACHE_SENTINEL));
1826 return null;
1827 }
1828 // two putters can race here, but they'll put the same class
1829 map.put(name, new WeakReference<Class<?>>(clazz));
1830 return clazz;
1831 } else if (clazz == NEGATIVE_CACHE_SENTINEL) {
1832 return null; // not found
1833 } else {
1834 // cache hit
1835 return clazz;
1836 }
1837 }
1838
1839 /**
1840 * Get the value of the <code>name</code> property
1841 * as an array of <code>Class</code>.
1842 * The value of the property specifies a list of comma separated class names.
1843 * If no such property is specified, then <code>defaultValue</code> is
1844 * returned.
1845 *
1846 * @param name the property name.
1847 * @param defaultValue default value.
1848 * @return property value as a <code>Class[]</code>,
1849 * or <code>defaultValue</code>.
1850 */
1851 public Class<?>[] getClasses(String name, Class<?> ... defaultValue) {
1852 String[] classnames = getTrimmedStrings(name);
1853 if (classnames == null)
1854 return defaultValue;
1855 try {
1856 Class<?>[] classes = new Class<?>[classnames.length];
1857 for(int i = 0; i < classnames.length; i++) {
1858 classes[i] = getClassByName(classnames[i]);
1859 }
1860 return classes;
1861 } catch (ClassNotFoundException e) {
1862 throw new RuntimeException(e);
1863 }
1864 }
1865
1866 /**
1867 * Get the value of the <code>name</code> property as a <code>Class</code>.
1868 * If no such property is specified, then <code>defaultValue</code> is
1869 * returned.
1870 *
1871 * @param name the class name.
1872 * @param defaultValue default value.
1873 * @return property value as a <code>Class</code>,
1874 * or <code>defaultValue</code>.
1875 */
1876 public Class<?> getClass(String name, Class<?> defaultValue) {
1877 String valueString = getTrimmed(name);
1878 if (valueString == null)
1879 return defaultValue;
1880 try {
1881 return getClassByName(valueString);
1882 } catch (ClassNotFoundException e) {
1883 throw new RuntimeException(e);
1884 }
1885 }
1886
1887 /**
1888 * Get the value of the <code>name</code> property as a <code>Class</code>
1889 * implementing the interface specified by <code>xface</code>.
1890 *
1891 * If no such property is specified, then <code>defaultValue</code> is
1892 * returned.
1893 *
1894 * An exception is thrown if the returned class does not implement the named
1895 * interface.
1896 *
1897 * @param name the class name.
1898 * @param defaultValue default value.
1899 * @param xface the interface implemented by the named class.
1900 * @return property value as a <code>Class</code>,
1901 * or <code>defaultValue</code>.
1902 */
1903 public <U> Class<? extends U> getClass(String name,
1904 Class<? extends U> defaultValue,
1905 Class<U> xface) {
1906 try {
1907 Class<?> theClass = getClass(name, defaultValue);
1908 if (theClass != null && !xface.isAssignableFrom(theClass))
1909 throw new RuntimeException(theClass+" not "+xface.getName());
1910 else if (theClass != null)
1911 return theClass.asSubclass(xface);
1912 else
1913 return null;
1914 } catch (Exception e) {
1915 throw new RuntimeException(e);
1916 }
1917 }
1918
1919 /**
1920 * Get the value of the <code>name</code> property as a <code>List</code>
1921 * of objects implementing the interface specified by <code>xface</code>.
1922 *
1923 * An exception is thrown if any of the classes does not exist, or if it does
1924 * not implement the named interface.
1925 *
1926 * @param name the property name.
1927 * @param xface the interface implemented by the classes named by
1928 * <code>name</code>.
1929 * @return a <code>List</code> of objects implementing <code>xface</code>.
1930 */
1931 @SuppressWarnings("unchecked")
1932 public <U> List<U> getInstances(String name, Class<U> xface) {
1933 List<U> ret = new ArrayList<U>();
1934 Class<?>[] classes = getClasses(name);
1935 for (Class<?> cl: classes) {
1936 if (!xface.isAssignableFrom(cl)) {
1937 throw new RuntimeException(cl + " does not implement " + xface);
1938 }
1939 ret.add((U)ReflectionUtils.newInstance(cl, this));
1940 }
1941 return ret;
1942 }
1943
1944 /**
1945 * Set the value of the <code>name</code> property to the name of a
1946 * <code>theClass</code> implementing the given interface <code>xface</code>.
1947 *
1948 * An exception is thrown if <code>theClass</code> does not implement the
1949 * interface <code>xface</code>.
1950 *
1951 * @param name property name.
1952 * @param theClass property value.
1953 * @param xface the interface implemented by the named class.
1954 */
1955 public void setClass(String name, Class<?> theClass, Class<?> xface) {
1956 if (!xface.isAssignableFrom(theClass))
1957 throw new RuntimeException(theClass+" not "+xface.getName());
1958 set(name, theClass.getName());
1959 }
1960
1961 /**
1962 * Get a local file under a directory named by <i>dirsProp</i> with
1963 * the given <i>path</i>. If <i>dirsProp</i> contains multiple directories,
1964 * then one is chosen based on <i>path</i>'s hash code. If the selected
1965 * directory does not exist, an attempt is made to create it.
1966 *
1967 * @param dirsProp directory in which to locate the file.
1968 * @param path file-path.
1969 * @return local file under the directory with the given path.
1970 */
1971 public Path getLocalPath(String dirsProp, String path)
1972 throws IOException {
1973 String[] dirs = getTrimmedStrings(dirsProp);
1974 int hashCode = path.hashCode();
1975 FileSystem fs = FileSystem.getLocal(this);
1976 for (int i = 0; i < dirs.length; i++) { // try each local dir
1977 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
1978 Path file = new Path(dirs[index], path);
1979 Path dir = file.getParent();
1980 if (fs.mkdirs(dir) || fs.exists(dir)) {
1981 return file;
1982 }
1983 }
1984 LOG.warn("Could not make " + path +
1985 " in local directories from " + dirsProp);
1986 for(int i=0; i < dirs.length; i++) {
1987 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
1988 LOG.warn(dirsProp + "[" + index + "]=" + dirs[index]);
1989 }
1990 throw new IOException("No valid local directories in property: "+dirsProp);
1991 }
1992
1993 /**
1994 * Get a local file name under a directory named in <i>dirsProp</i> with
1995 * the given <i>path</i>. If <i>dirsProp</i> contains multiple directories,
1996 * then one is chosen based on <i>path</i>'s hash code. If the selected
1997 * directory does not exist, an attempt is made to create it.
1998 *
1999 * @param dirsProp directory in which to locate the file.
2000 * @param path file-path.
2001 * @return local file under the directory with the given path.
2002 */
2003 public File getFile(String dirsProp, String path)
2004 throws IOException {
2005 String[] dirs = getTrimmedStrings(dirsProp);
2006 int hashCode = path.hashCode();
2007 for (int i = 0; i < dirs.length; i++) { // try each local dir
2008 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
2009 File file = new File(dirs[index], path);
2010 File dir = file.getParentFile();
2011 if (dir.exists() || dir.mkdirs()) {
2012 return file;
2013 }
2014 }
2015 throw new IOException("No valid local directories in property: "+dirsProp);
2016 }
2017
2018 /**
2019 * Get the {@link URL} for the named resource.
2020 *
2021 * @param name resource name.
2022 * @return the url for the named resource.
2023 */
2024 public URL getResource(String name) {
2025 return classLoader.getResource(name);
2026 }
2027
2028 /**
2029 * Checks if the class specified by propertiesClassName is found on the classLoader.
2030 * If yes, creates an instance of the class and checks if the instance is of type {@link java.util.Properties}.
2031 *
2032 * @param propertiesClassName class name.
2033 * @return instance of {@link Properties} if successful. Returns null otherwise.
2034 */
2035 public Properties getProperties(String propertiesClassName) {
2036 try {
2037 Class<?> propertiesClass = getClassByNameOrNull(propertiesClassName);
2038 if (propertiesClass != null) {
2039 Object propertiesObj = propertiesClass.newInstance();
2040 if (propertiesObj instanceof Properties) {
2041 if (LOG.isDebugEnabled()) {
2042 LOG.debug("Loaded " + propertiesClass.getName());
2043 }
2044 return (Properties) propertiesObj;
2045 }
2046 }
2047 } catch (InstantiationException e) {
2048 } catch (IllegalAccessException e) {
2049 }
2050
2051 return null;
2052 }
2053
2054 /**
2055 * Get an input stream attached to the configuration resource with the
2056 * given <code>name</code>.
2057 *
2058 * @param name configuration resource name.
2059 * @return an input stream attached to the resource.
2060 */
2061 public InputStream getConfResourceAsInputStream(String name) {
2062 try {
2063 URL url= getResource(name);
2064
2065 if (url == null) {
2066 LOG.info(name + " not found");
2067 return null;
2068 } else {
2069 LOG.info("found resource " + name + " at " + url);
2070 }
2071
2072 return url.openStream();
2073 } catch (Exception e) {
2074 return null;
2075 }
2076 }
2077
2078 /**
2079 * Get a {@link Reader} attached to the configuration resource with the
2080 * given <code>name</code>.
2081 *
2082 * @param name configuration resource name.
2083 * @return a reader attached to the resource.
2084 */
2085 public Reader getConfResourceAsReader(String name) {
2086 try {
2087 URL url= getResource(name);
2088
2089 if (url == null) {
2090 LOG.info(name + " not found");
2091 return null;
2092 } else {
2093 LOG.info("found resource " + name + " at " + url);
2094 }
2095
2096 return new InputStreamReader(url.openStream());
2097 } catch (Exception e) {
2098 return null;
2099 }
2100 }
2101
2102 protected synchronized Properties getProps() {
2103 if (properties == null) {
2104 properties = new Properties();
2105 HashMap<String, String[]> backup =
2106 new HashMap<String, String[]>(updatingResource);
2107 loadResources(properties, resources, quietmode);
2108 if (overlay!= null) {
2109 properties.putAll(overlay);
2110 for (Map.Entry<Object,Object> item: overlay.entrySet()) {
2111 String key = (String)item.getKey();
2112 updatingResource.put(key, backup.get(key));
2113 }
2114 }
2115 }
2116 return properties;
2117 }
2118
2119 /**
2120 * Return the number of keys in the configuration.
2121 *
2122 * @return number of keys in the configuration.
2123 */
2124 public int size() {
2125 return getProps().size();
2126 }
2127
2128 /**
2129 * Clears all keys from the configuration.
2130 */
2131 public void clear() {
2132 getProps().clear();
2133 getOverlay().clear();
2134 }
2135
2136 /**
2137 * Get an {@link Iterator} to go through the list of <code>String</code>
2138 * key-value pairs in the configuration.
2139 *
2140 * @return an iterator over the entries.
2141 */
2142 @Override
2143 public Iterator<Map.Entry<String, String>> iterator() {
2144 // Get a copy of just the string to string pairs. After the old object
2145 // methods that allow non-strings to be put into configurations are removed,
2146 // we could replace properties with a Map<String,String> and get rid of this
2147 // code.
2148 Map<String,String> result = new HashMap<String,String>();
2149 for(Map.Entry<Object,Object> item: getProps().entrySet()) {
2150 if (item.getKey() instanceof String &&
2151 item.getValue() instanceof String) {
2152 result.put((String) item.getKey(), (String) item.getValue());
2153 }
2154 }
2155 return result.entrySet().iterator();
2156 }
2157
2158 private Document parse(DocumentBuilder builder, URL url)
2159 throws IOException, SAXException {
2160 if (!quietmode) {
2161 LOG.info("parsing URL " + url);
2162 }
2163 if (url == null) {
2164 return null;
2165 }
2166 return parse(builder, url.openStream(), url.toString());
2167 }
2168
2169 private Document parse(DocumentBuilder builder, InputStream is,
2170 String systemId) throws IOException, SAXException {
2171 if (!quietmode) {
2172 LOG.info("parsing input stream " + is);
2173 }
2174 if (is == null) {
2175 return null;
2176 }
2177 try {
2178 return (systemId == null) ? builder.parse(is) : builder.parse(is,
2179 systemId);
2180 } finally {
2181 is.close();
2182 }
2183 }
2184
2185 private void loadResources(Properties properties,
2186 ArrayList<Resource> resources,
2187 boolean quiet) {
2188 if(loadDefaults) {
2189 for (String resource : defaultResources) {
2190 loadResource(properties, new Resource(resource), quiet);
2191 }
2192
2193 //support the hadoop-site.xml as a deprecated case
2194 if(getResource("hadoop-site.xml")!=null) {
2195 loadResource(properties, new Resource("hadoop-site.xml"), quiet);
2196 }
2197 }
2198
2199 for (int i = 0; i < resources.size(); i++) {
2200 Resource ret = loadResource(properties, resources.get(i), quiet);
2201 if (ret != null) {
2202 resources.set(i, ret);
2203 }
2204 }
2205 }
2206
2207 private Resource loadResource(Properties properties, Resource wrapper, boolean quiet) {
2208 String name = UNKNOWN_RESOURCE;
2209 try {
2210 Object resource = wrapper.getResource();
2211 name = wrapper.getName();
2212
2213 DocumentBuilderFactory docBuilderFactory
2214 = DocumentBuilderFactory.newInstance();
2215 //ignore all comments inside the xml file
2216 docBuilderFactory.setIgnoringComments(true);
2217
2218 //allow includes in the xml file
2219 docBuilderFactory.setNamespaceAware(true);
2220 try {
2221 docBuilderFactory.setXIncludeAware(true);
2222 } catch (UnsupportedOperationException e) {
2223 LOG.error("Failed to set setXIncludeAware(true) for parser "
2224 + docBuilderFactory
2225 + ":" + e,
2226 e);
2227 }
2228 DocumentBuilder builder = docBuilderFactory.newDocumentBuilder();
2229 Document doc = null;
2230 Element root = null;
2231 boolean returnCachedProperties = false;
2232
2233 if (resource instanceof URL) { // an URL resource
2234 doc = parse(builder, (URL)resource);
2235 } else if (resource instanceof String) { // a CLASSPATH resource
2236 String resourceStr = (String) resource;
2237 Properties props = null;
2238 if (!resourceStr.endsWith(".xml") && (props = getProperties(resourceStr)) != null) {
2239 overlay(properties, props);
2240 } else {
2241 URL url = getResource(resourceStr);
2242 doc = parse(builder, url);
2243 }
2244 } else if (resource instanceof Path) { // a file resource
2245 // Can't use FileSystem API or we get an infinite loop
2246 // since FileSystem uses Configuration API. Use java.io.File instead.
2247 File file = new File(((Path)resource).toUri().getPath())
2248 .getAbsoluteFile();
2249 if (file.exists()) {
2250 if (!quiet) {
2251 LOG.info("parsing File " + file);
2252 }
2253 doc = parse(builder, new BufferedInputStream(
2254 new FileInputStream(file)), ((Path)resource).toString());
2255 }
2256 } else if (resource instanceof InputStream) {
2257 doc = parse(builder, (InputStream) resource, null);
2258 returnCachedProperties = true;
2259 } else if (resource instanceof Properties) {
2260 overlay(properties, (Properties)resource);
2261 } else if (resource instanceof Element) {
2262 root = (Element)resource;
2263 }
2264
2265 if (doc == null && root == null) {
2266 if (quiet)
2267 return null;
2268 throw new RuntimeException(resource + " not found");
2269 }
2270
2271 if (root == null) {
2272 root = doc.getDocumentElement();
2273 }
2274 Properties toAddTo = properties;
2275 if(returnCachedProperties) {
2276 toAddTo = new Properties();
2277 }
2278 if (!"configuration".equals(root.getTagName()))
2279 LOG.fatal("bad conf file: top-level element not <configuration>");
2280 NodeList props = root.getChildNodes();
2281 DeprecationContext deprecations = deprecationContext.get();
2282 for (int i = 0; i < props.getLength(); i++) {
2283 Node propNode = props.item(i);
2284 if (!(propNode instanceof Element))
2285 continue;
2286 Element prop = (Element)propNode;
2287 if ("configuration".equals(prop.getTagName())) {
2288 loadResource(toAddTo, new Resource(prop, name), quiet);
2289 continue;
2290 }
2291 if (!"property".equals(prop.getTagName()))
2292 LOG.warn("bad conf file: element not <property>");
2293 NodeList fields = prop.getChildNodes();
2294 String attr = null;
2295 String value = null;
2296 boolean finalParameter = false;
2297 LinkedList<String> source = new LinkedList<String>();
2298 for (int j = 0; j < fields.getLength(); j++) {
2299 Node fieldNode = fields.item(j);
2300 if (!(fieldNode instanceof Element))
2301 continue;
2302 Element field = (Element)fieldNode;
2303 if ("name".equals(field.getTagName()) && field.hasChildNodes())
2304 attr = StringInterner.weakIntern(
2305 ((Text)field.getFirstChild()).getData().trim());
2306 if ("value".equals(field.getTagName()) && field.hasChildNodes())
2307 value = StringInterner.weakIntern(
2308 ((Text)field.getFirstChild()).getData());
2309 if ("final".equals(field.getTagName()) && field.hasChildNodes())
2310 finalParameter = "true".equals(((Text)field.getFirstChild()).getData());
2311 if ("source".equals(field.getTagName()) && field.hasChildNodes())
2312 source.add(StringInterner.weakIntern(
2313 ((Text)field.getFirstChild()).getData()));
2314 }
2315 source.add(name);
2316
2317 // Ignore this parameter if it has already been marked as 'final'
2318 if (attr != null) {
2319 if (deprecations.getDeprecatedKeyMap().containsKey(attr)) {
2320 DeprecatedKeyInfo keyInfo =
2321 deprecations.getDeprecatedKeyMap().get(attr);
2322 keyInfo.clearAccessed();
2323 for (String key:keyInfo.newKeys) {
2324 // update new keys with deprecated key's value
2325 loadProperty(toAddTo, name, key, value, finalParameter,
2326 source.toArray(new String[source.size()]));
2327 }
2328 }
2329 else {
2330 loadProperty(toAddTo, name, attr, value, finalParameter,
2331 source.toArray(new String[source.size()]));
2332 }
2333 }
2334 }
2335
2336 if (returnCachedProperties) {
2337 overlay(properties, toAddTo);
2338 return new Resource(toAddTo, name);
2339 }
2340 return null;
2341 } catch (IOException e) {
2342 LOG.fatal("error parsing conf " + name, e);
2343 throw new RuntimeException(e);
2344 } catch (DOMException e) {
2345 LOG.fatal("error parsing conf " + name, e);
2346 throw new RuntimeException(e);
2347 } catch (SAXException e) {
2348 LOG.fatal("error parsing conf " + name, e);
2349 throw new RuntimeException(e);
2350 } catch (ParserConfigurationException e) {
2351 LOG.fatal("error parsing conf " + name , e);
2352 throw new RuntimeException(e);
2353 }
2354 }
2355
2356 private void overlay(Properties to, Properties from) {
2357 for (Entry<Object, Object> entry: from.entrySet()) {
2358 to.put(entry.getKey(), entry.getValue());
2359 }
2360 }
2361
2362 private void loadProperty(Properties properties, String name, String attr,
2363 String value, boolean finalParameter, String[] source) {
2364 if (value != null) {
2365 if (!finalParameters.contains(attr)) {
2366 properties.setProperty(attr, value);
2367 updatingResource.put(attr, source);
2368 } else {
2369 LOG.warn(name+":an attempt to override final parameter: "+attr
2370 +"; Ignoring.");
2371 }
2372 }
2373 if (finalParameter) {
2374 finalParameters.add(attr);
2375 }
2376 }
2377
2378 /**
2379 * Write out the non-default properties in this configuration to the given
2380 * {@link OutputStream} using UTF-8 encoding.
2381 *
2382 * @param out the output stream to write to.
2383 */
2384 public void writeXml(OutputStream out) throws IOException {
2385 writeXml(new OutputStreamWriter(out, "UTF-8"));
2386 }
2387
2388 /**
2389 * Write out the non-default properties in this configuration to the given
2390 * {@link Writer}.
2391 *
2392 * @param out the writer to write to.
2393 */
2394 public void writeXml(Writer out) throws IOException {
2395 Document doc = asXmlDocument();
2396
2397 try {
2398 DOMSource source = new DOMSource(doc);
2399 StreamResult result = new StreamResult(out);
2400 TransformerFactory transFactory = TransformerFactory.newInstance();
2401 Transformer transformer = transFactory.newTransformer();
2402
2403 // Important to not hold Configuration log while writing result, since
2404 // 'out' may be an HDFS stream which needs to lock this configuration
2405 // from another thread.
2406 transformer.transform(source, result);
2407 } catch (TransformerException te) {
2408 throw new IOException(te);
2409 }
2410 }
2411
2412 /**
2413 * Return the XML DOM corresponding to this Configuration.
2414 */
2415 private synchronized Document asXmlDocument() throws IOException {
2416 Document doc;
2417 try {
2418 doc =
2419 DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
2420 } catch (ParserConfigurationException pe) {
2421 throw new IOException(pe);
2422 }
2423 Element conf = doc.createElement("configuration");
2424 doc.appendChild(conf);
2425 conf.appendChild(doc.createTextNode("\n"));
2426 handleDeprecation(); //ensure properties is set and deprecation is handled
2427 for (Enumeration<Object> e = properties.keys(); e.hasMoreElements();) {
2428 String name = (String)e.nextElement();
2429 Object object = properties.get(name);
2430 String value = null;
2431 if (object instanceof String) {
2432 value = (String) object;
2433 }else {
2434 continue;
2435 }
2436 Element propNode = doc.createElement("property");
2437 conf.appendChild(propNode);
2438
2439 Element nameNode = doc.createElement("name");
2440 nameNode.appendChild(doc.createTextNode(name));
2441 propNode.appendChild(nameNode);
2442
2443 Element valueNode = doc.createElement("value");
2444 valueNode.appendChild(doc.createTextNode(value));
2445 propNode.appendChild(valueNode);
2446
2447 if (updatingResource != null) {
2448 String[] sources = updatingResource.get(name);
2449 if(sources != null) {
2450 for(String s : sources) {
2451 Element sourceNode = doc.createElement("source");
2452 sourceNode.appendChild(doc.createTextNode(s));
2453 propNode.appendChild(sourceNode);
2454 }
2455 }
2456 }
2457
2458 conf.appendChild(doc.createTextNode("\n"));
2459 }
2460 return doc;
2461 }
2462
2463 /**
2464 * Writes out all the parameters and their properties (final and resource) to
2465 * the given {@link Writer}
2466 * The format of the output would be
2467 * { "properties" : [ {key1,value1,key1.isFinal,key1.resource}, {key2,value2,
2468 * key2.isFinal,key2.resource}... ] }
2469 * It does not output the parameters of the configuration object which is
2470 * loaded from an input stream.
2471 * @param out the Writer to write to
2472 * @throws IOException
2473 */
2474 public static void dumpConfiguration(Configuration config,
2475 Writer out) throws IOException {
2476 JsonFactory dumpFactory = new JsonFactory();
2477 JsonGenerator dumpGenerator = dumpFactory.createJsonGenerator(out);
2478 dumpGenerator.writeStartObject();
2479 dumpGenerator.writeFieldName("properties");
2480 dumpGenerator.writeStartArray();
2481 dumpGenerator.flush();
2482 synchronized (config) {
2483 for (Map.Entry<Object,Object> item: config.getProps().entrySet()) {
2484 dumpGenerator.writeStartObject();
2485 dumpGenerator.writeStringField("key", (String) item.getKey());
2486 dumpGenerator.writeStringField("value",
2487 config.get((String) item.getKey()));
2488 dumpGenerator.writeBooleanField("isFinal",
2489 config.finalParameters.contains(item.getKey()));
2490 String[] resources = config.updatingResource.get(item.getKey());
2491 String resource = UNKNOWN_RESOURCE;
2492 if(resources != null && resources.length > 0) {
2493 resource = resources[0];
2494 }
2495 dumpGenerator.writeStringField("resource", resource);
2496 dumpGenerator.writeEndObject();
2497 }
2498 }
2499 dumpGenerator.writeEndArray();
2500 dumpGenerator.writeEndObject();
2501 dumpGenerator.flush();
2502 }
2503
2504 /**
2505 * Get the {@link ClassLoader} for this job.
2506 *
2507 * @return the correct class loader.
2508 */
2509 public ClassLoader getClassLoader() {
2510 return classLoader;
2511 }
2512
2513 /**
2514 * Set the class loader that will be used to load the various objects.
2515 *
2516 * @param classLoader the new class loader.
2517 */
2518 public void setClassLoader(ClassLoader classLoader) {
2519 this.classLoader = classLoader;
2520 }
2521
2522 @Override
2523 public String toString() {
2524 StringBuilder sb = new StringBuilder();
2525 sb.append("Configuration: ");
2526 if(loadDefaults) {
2527 toString(defaultResources, sb);
2528 if(resources.size()>0) {
2529 sb.append(", ");
2530 }
2531 }
2532 toString(resources, sb);
2533 return sb.toString();
2534 }
2535
2536 private <T> void toString(List<T> resources, StringBuilder sb) {
2537 ListIterator<T> i = resources.listIterator();
2538 while (i.hasNext()) {
2539 if (i.nextIndex() != 0) {
2540 sb.append(", ");
2541 }
2542 sb.append(i.next());
2543 }
2544 }
2545
2546 /**
2547 * Set the quietness-mode.
2548 *
2549 * In the quiet-mode, error and informational messages might not be logged.
2550 *
2551 * @param quietmode <code>true</code> to set quiet-mode on, <code>false</code>
2552 * to turn it off.
2553 */
2554 public synchronized void setQuietMode(boolean quietmode) {
2555 this.quietmode = quietmode;
2556 }
2557
2558 synchronized boolean getQuietMode() {
2559 return this.quietmode;
2560 }
2561
2562 /** For debugging. List non-default properties to the terminal and exit. */
2563 public static void main(String[] args) throws Exception {
2564 new Configuration().writeXml(System.out);
2565 }
2566
2567 @Override
2568 public void readFields(DataInput in) throws IOException {
2569 clear();
2570 int size = WritableUtils.readVInt(in);
2571 for(int i=0; i < size; ++i) {
2572 String key = org.apache.hadoop.io.Text.readString(in);
2573 String value = org.apache.hadoop.io.Text.readString(in);
2574 set(key, value);
2575 String sources[] = WritableUtils.readCompressedStringArray(in);
2576 updatingResource.put(key, sources);
2577 }
2578 }
2579
2580 //@Override
2581 @Override
2582 public void write(DataOutput out) throws IOException {
2583 Properties props = getProps();
2584 WritableUtils.writeVInt(out, props.size());
2585 for(Map.Entry<Object, Object> item: props.entrySet()) {
2586 org.apache.hadoop.io.Text.writeString(out, (String) item.getKey());
2587 org.apache.hadoop.io.Text.writeString(out, (String) item.getValue());
2588 WritableUtils.writeCompressedStringArray(out,
2589 updatingResource.get(item.getKey()));
2590 }
2591 }
2592
2593 /**
2594 * get keys matching the the regex
2595 * @param regex
2596 * @return Map<String,String> with matching keys
2597 */
2598 public Map<String,String> getValByRegex(String regex) {
2599 Pattern p = Pattern.compile(regex);
2600
2601 Map<String,String> result = new HashMap<String,String>();
2602 Matcher m;
2603
2604 for(Map.Entry<Object,Object> item: getProps().entrySet()) {
2605 if (item.getKey() instanceof String &&
2606 item.getValue() instanceof String) {
2607 m = p.matcher((String)item.getKey());
2608 if(m.find()) { // match
2609 result.put((String) item.getKey(), (String) item.getValue());
2610 }
2611 }
2612 }
2613 return result;
2614 }
2615
2616 /**
2617 * A unique class which is used as a sentinel value in the caching
2618 * for getClassByName. {@see Configuration#getClassByNameOrNull(String)}
2619 */
2620 private static abstract class NegativeCacheSentinel {}
2621
2622 public static void dumpDeprecatedKeys() {
2623 DeprecationContext deprecations = deprecationContext.get();
2624 for (Map.Entry<String, DeprecatedKeyInfo> entry :
2625 deprecations.getDeprecatedKeyMap().entrySet()) {
2626 StringBuilder newKeys = new StringBuilder();
2627 for (String newKey : entry.getValue().newKeys) {
2628 newKeys.append(newKey).append("\t");
2629 }
2630 System.out.println(entry.getKey() + "\t" + newKeys.toString());
2631 }
2632 }
2633
2634 /**
2635 * Returns whether or not a deprecated name has been warned. If the name is not
2636 * deprecated then always return false
2637 */
2638 public static boolean hasWarnedDeprecation(String name) {
2639 DeprecationContext deprecations = deprecationContext.get();
2640 if(deprecations.getDeprecatedKeyMap().containsKey(name)) {
2641 if(deprecations.getDeprecatedKeyMap().get(name).accessed.get()) {
2642 return true;
2643 }
2644 }
2645 return false;
2646 }
2647 }