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("core-site.xml"); 619 } 620 621 private Properties properties; 622 private Properties overlay; 623 private ClassLoader classLoader; 624 { 625 classLoader = Thread.currentThread().getContextClassLoader(); 626 if (classLoader == null) { 627 classLoader = Configuration.class.getClassLoader(); 628 } 629 } 630 631 /** A new configuration. */ 632 public Configuration() { 633 this(true); 634 } 635 636 /** A new configuration where the behavior of reading from the default 637 * resources can be turned off. 638 * 639 * If the parameter {@code loadDefaults} is false, the new instance 640 * will not load resources from the default files. 641 * @param loadDefaults specifies whether to load from the default files 642 */ 643 public Configuration(boolean loadDefaults) { 644 this.loadDefaults = loadDefaults; 645 updatingResource = new HashMap<String, String[]>(); 646 synchronized(Configuration.class) { 647 REGISTRY.put(this, null); 648 } 649 } 650 651 /** 652 * A new configuration with the same settings cloned from another. 653 * 654 * @param other the configuration from which to clone settings. 655 */ 656 @SuppressWarnings("unchecked") 657 public Configuration(Configuration other) { 658 this.resources = (ArrayList<Resource>) other.resources.clone(); 659 synchronized(other) { 660 if (other.properties != null) { 661 this.properties = (Properties)other.properties.clone(); 662 } 663 664 if (other.overlay!=null) { 665 this.overlay = (Properties)other.overlay.clone(); 666 } 667 668 this.updatingResource = new HashMap<String, String[]>(other.updatingResource); 669 } 670 671 this.finalParameters = new HashSet<String>(other.finalParameters); 672 synchronized(Configuration.class) { 673 REGISTRY.put(this, null); 674 } 675 this.classLoader = other.classLoader; 676 this.loadDefaults = other.loadDefaults; 677 setQuietMode(other.getQuietMode()); 678 } 679 680 /** 681 * Add a default resource. Resources are loaded in the order of the resources 682 * added. 683 * @param name file name. File should be present in the classpath. 684 */ 685 public static synchronized void addDefaultResource(String name) { 686 if(!defaultResources.contains(name)) { 687 defaultResources.add(name); 688 for(Configuration conf : REGISTRY.keySet()) { 689 if(conf.loadDefaults) { 690 conf.reloadConfiguration(); 691 } 692 } 693 } 694 } 695 696 /** 697 * Add a configuration resource. 698 * 699 * The properties of this resource will override properties of previously 700 * added resources, unless they were marked <a href="#Final">final</a>. 701 * 702 * @param name resource to be added, the classpath is examined for a file 703 * with that name. 704 */ 705 public void addResource(String name) { 706 addResourceObject(new Resource(name)); 707 } 708 709 /** 710 * Add a configuration resource. 711 * 712 * The properties of this resource will override properties of previously 713 * added resources, unless they were marked <a href="#Final">final</a>. 714 * 715 * @param url url of the resource to be added, the local filesystem is 716 * examined directly to find the resource, without referring to 717 * the classpath. 718 */ 719 public void addResource(URL url) { 720 addResourceObject(new Resource(url)); 721 } 722 723 /** 724 * Add a configuration resource. 725 * 726 * The properties of this resource will override properties of previously 727 * added resources, unless they were marked <a href="#Final">final</a>. 728 * 729 * @param file file-path of resource to be added, the local filesystem is 730 * examined directly to find the resource, without referring to 731 * the classpath. 732 */ 733 public void addResource(Path file) { 734 addResourceObject(new Resource(file)); 735 } 736 737 /** 738 * Add a configuration resource. 739 * 740 * The properties of this resource will override properties of previously 741 * added resources, unless they were marked <a href="#Final">final</a>. 742 * 743 * WARNING: The contents of the InputStream will be cached, by this method. 744 * So use this sparingly because it does increase the memory consumption. 745 * 746 * @param in InputStream to deserialize the object from. In will be read from 747 * when a get or set is called next. After it is read the stream will be 748 * closed. 749 */ 750 public void addResource(InputStream in) { 751 addResourceObject(new Resource(in)); 752 } 753 754 /** 755 * Add a configuration resource. 756 * 757 * The properties of this resource will override properties of previously 758 * added resources, unless they were marked <a href="#Final">final</a>. 759 * 760 * @param in InputStream to deserialize the object from. 761 * @param name the name of the resource because InputStream.toString is not 762 * very descriptive some times. 763 */ 764 public void addResource(InputStream in, String name) { 765 addResourceObject(new Resource(in, name)); 766 } 767 768 769 /** 770 * Reload configuration from previously added resources. 771 * 772 * This method will clear all the configuration read from the added 773 * resources, and final parameters. This will make the resources to 774 * be read again before accessing the values. Values that are added 775 * via set methods will overlay values read from the resources. 776 */ 777 public synchronized void reloadConfiguration() { 778 properties = null; // trigger reload 779 finalParameters.clear(); // clear site-limits 780 } 781 782 private synchronized void addResourceObject(Resource resource) { 783 resources.add(resource); // add to resources 784 reloadConfiguration(); 785 } 786 787 private static Pattern varPat = Pattern.compile("\\$\\{[^\\}\\$\u0020]+\\}"); 788 private static int MAX_SUBST = 20; 789 790 private String substituteVars(String expr) { 791 if (expr == null) { 792 return null; 793 } 794 Matcher match = varPat.matcher(""); 795 String eval = expr; 796 for(int s=0; s<MAX_SUBST; s++) { 797 match.reset(eval); 798 if (!match.find()) { 799 return eval; 800 } 801 String var = match.group(); 802 var = var.substring(2, var.length()-1); // remove ${ .. } 803 String val = null; 804 try { 805 val = System.getProperty(var); 806 } catch(SecurityException se) { 807 LOG.warn("Unexpected SecurityException in Configuration", se); 808 } 809 if (val == null) { 810 val = getRaw(var); 811 } 812 if (val == null) { 813 return eval; // return literal ${var}: var is unbound 814 } 815 // substitute 816 eval = eval.substring(0, match.start())+val+eval.substring(match.end()); 817 } 818 throw new IllegalStateException("Variable substitution depth too large: " 819 + MAX_SUBST + " " + expr); 820 } 821 822 /** 823 * Get the value of the <code>name</code> property, <code>null</code> if 824 * no such property exists. If the key is deprecated, it returns the value of 825 * the first key which replaces the deprecated key and is not null 826 * 827 * Values are processed for <a href="#VariableExpansion">variable expansion</a> 828 * before being returned. 829 * 830 * @param name the property name. 831 * @return the value of the <code>name</code> or its replacing property, 832 * or null if no such property exists. 833 */ 834 public String get(String name) { 835 String[] names = handleDeprecation(deprecationContext.get(), name); 836 String result = null; 837 for(String n : names) { 838 result = substituteVars(getProps().getProperty(n)); 839 } 840 return result; 841 } 842 843 /** 844 * Get the value of the <code>name</code> property as a trimmed <code>String</code>, 845 * <code>null</code> if no such property exists. 846 * If the key is deprecated, it returns the value of 847 * the first key which replaces the deprecated key and is not null 848 * 849 * Values are processed for <a href="#VariableExpansion">variable expansion</a> 850 * before being returned. 851 * 852 * @param name the property name. 853 * @return the value of the <code>name</code> or its replacing property, 854 * or null if no such property exists. 855 */ 856 public String getTrimmed(String name) { 857 String value = get(name); 858 859 if (null == value) { 860 return null; 861 } else { 862 return value.trim(); 863 } 864 } 865 866 /** 867 * Get the value of the <code>name</code> property as a trimmed <code>String</code>, 868 * <code>defaultValue</code> if no such property exists. 869 * See @{Configuration#getTrimmed} for more details. 870 * 871 * @param name the property name. 872 * @param defaultValue the property default value. 873 * @return the value of the <code>name</code> or defaultValue 874 * if it is not set. 875 */ 876 public String getTrimmed(String name, String defaultValue) { 877 String ret = getTrimmed(name); 878 return ret == null ? defaultValue : ret; 879 } 880 881 /** 882 * Get the value of the <code>name</code> property, without doing 883 * <a href="#VariableExpansion">variable expansion</a>.If the key is 884 * deprecated, it returns the value of the first key which replaces 885 * the deprecated key and is not null. 886 * 887 * @param name the property name. 888 * @return the value of the <code>name</code> property or 889 * its replacing property and null if no such property exists. 890 */ 891 public String getRaw(String name) { 892 String[] names = handleDeprecation(deprecationContext.get(), name); 893 String result = null; 894 for(String n : names) { 895 result = getProps().getProperty(n); 896 } 897 return result; 898 } 899 900 /** 901 * Returns alternative names (non-deprecated keys or previously-set deprecated keys) 902 * for a given non-deprecated key. 903 * If the given key is deprecated, return null. 904 * 905 * @param name property name. 906 * @return alternative names. 907 */ 908 private String[] getAlternativeNames(String name) { 909 String altNames[] = null; 910 DeprecatedKeyInfo keyInfo = null; 911 DeprecationContext cur = deprecationContext.get(); 912 String depKey = cur.getReverseDeprecatedKeyMap().get(name); 913 if(depKey != null) { 914 keyInfo = cur.getDeprecatedKeyMap().get(depKey); 915 if(keyInfo.newKeys.length > 0) { 916 if(getProps().containsKey(depKey)) { 917 //if deprecated key is previously set explicitly 918 List<String> list = new ArrayList<String>(); 919 list.addAll(Arrays.asList(keyInfo.newKeys)); 920 list.add(depKey); 921 altNames = list.toArray(new String[list.size()]); 922 } 923 else { 924 altNames = keyInfo.newKeys; 925 } 926 } 927 } 928 return altNames; 929 } 930 931 /** 932 * Set the <code>value</code> of the <code>name</code> property. If 933 * <code>name</code> is deprecated or there is a deprecated name associated to it, 934 * it sets the value to both names. 935 * 936 * @param name property name. 937 * @param value property value. 938 */ 939 public void set(String name, String value) { 940 set(name, value, null); 941 } 942 943 /** 944 * Set the <code>value</code> of the <code>name</code> property. If 945 * <code>name</code> is deprecated, it also sets the <code>value</code> to 946 * the keys that replace the deprecated key. 947 * 948 * @param name property name. 949 * @param value property value. 950 * @param source the place that this configuration value came from 951 * (For debugging). 952 * @throws IllegalArgumentException when the value or name is null. 953 */ 954 public void set(String name, String value, String source) { 955 Preconditions.checkArgument( 956 name != null, 957 "Property name must not be null"); 958 Preconditions.checkArgument( 959 value != null, 960 "The value of property " + name + " must not be null"); 961 DeprecationContext deprecations = deprecationContext.get(); 962 if (deprecations.getDeprecatedKeyMap().isEmpty()) { 963 getProps(); 964 } 965 getOverlay().setProperty(name, value); 966 getProps().setProperty(name, value); 967 String newSource = (source == null ? "programatically" : source); 968 969 if (!isDeprecated(name)) { 970 updatingResource.put(name, new String[] {newSource}); 971 String[] altNames = getAlternativeNames(name); 972 if(altNames != null) { 973 for(String n: altNames) { 974 if(!n.equals(name)) { 975 getOverlay().setProperty(n, value); 976 getProps().setProperty(n, value); 977 updatingResource.put(n, new String[] {newSource}); 978 } 979 } 980 } 981 } 982 else { 983 String[] names = handleDeprecation(deprecationContext.get(), name); 984 String altSource = "because " + name + " is deprecated"; 985 for(String n : names) { 986 getOverlay().setProperty(n, value); 987 getProps().setProperty(n, value); 988 updatingResource.put(n, new String[] {altSource}); 989 } 990 } 991 } 992 993 private void warnOnceIfDeprecated(DeprecationContext deprecations, String name) { 994 DeprecatedKeyInfo keyInfo = deprecations.getDeprecatedKeyMap().get(name); 995 if (keyInfo != null && !keyInfo.getAndSetAccessed()) { 996 LOG_DEPRECATION.info(keyInfo.getWarningMessage(name)); 997 } 998 } 999 1000 /** 1001 * Unset a previously set property. 1002 */ 1003 public synchronized void unset(String name) { 1004 String[] names = null; 1005 if (!isDeprecated(name)) { 1006 names = getAlternativeNames(name); 1007 if(names == null) { 1008 names = new String[]{name}; 1009 } 1010 } 1011 else { 1012 names = handleDeprecation(deprecationContext.get(), name); 1013 } 1014 1015 for(String n: names) { 1016 getOverlay().remove(n); 1017 getProps().remove(n); 1018 } 1019 } 1020 1021 /** 1022 * Sets a property if it is currently unset. 1023 * @param name the property name 1024 * @param value the new value 1025 */ 1026 public synchronized void setIfUnset(String name, String value) { 1027 if (get(name) == null) { 1028 set(name, value); 1029 } 1030 } 1031 1032 private synchronized Properties getOverlay() { 1033 if (overlay==null){ 1034 overlay=new Properties(); 1035 } 1036 return overlay; 1037 } 1038 1039 /** 1040 * Get the value of the <code>name</code>. If the key is deprecated, 1041 * it returns the value of the first key which replaces the deprecated key 1042 * and is not null. 1043 * If no such property exists, 1044 * then <code>defaultValue</code> is returned. 1045 * 1046 * @param name property name. 1047 * @param defaultValue default value. 1048 * @return property value, or <code>defaultValue</code> if the property 1049 * doesn't exist. 1050 */ 1051 public String get(String name, String defaultValue) { 1052 String[] names = handleDeprecation(deprecationContext.get(), name); 1053 String result = null; 1054 for(String n : names) { 1055 result = substituteVars(getProps().getProperty(n, defaultValue)); 1056 } 1057 return result; 1058 } 1059 1060 /** 1061 * Get the value of the <code>name</code> property as an <code>int</code>. 1062 * 1063 * If no such property exists, the provided default value is returned, 1064 * or if the specified value is not a valid <code>int</code>, 1065 * then an error is thrown. 1066 * 1067 * @param name property name. 1068 * @param defaultValue default value. 1069 * @throws NumberFormatException when the value is invalid 1070 * @return property value as an <code>int</code>, 1071 * or <code>defaultValue</code>. 1072 */ 1073 public int getInt(String name, int defaultValue) { 1074 String valueString = getTrimmed(name); 1075 if (valueString == null) 1076 return defaultValue; 1077 String hexString = getHexDigits(valueString); 1078 if (hexString != null) { 1079 return Integer.parseInt(hexString, 16); 1080 } 1081 return Integer.parseInt(valueString); 1082 } 1083 1084 /** 1085 * Get the value of the <code>name</code> property as a set of comma-delimited 1086 * <code>int</code> values. 1087 * 1088 * If no such property exists, an empty array is returned. 1089 * 1090 * @param name property name 1091 * @return property value interpreted as an array of comma-delimited 1092 * <code>int</code> values 1093 */ 1094 public int[] getInts(String name) { 1095 String[] strings = getTrimmedStrings(name); 1096 int[] ints = new int[strings.length]; 1097 for (int i = 0; i < strings.length; i++) { 1098 ints[i] = Integer.parseInt(strings[i]); 1099 } 1100 return ints; 1101 } 1102 1103 /** 1104 * Set the value of the <code>name</code> property to an <code>int</code>. 1105 * 1106 * @param name property name. 1107 * @param value <code>int</code> value of the property. 1108 */ 1109 public void setInt(String name, int value) { 1110 set(name, Integer.toString(value)); 1111 } 1112 1113 1114 /** 1115 * Get the value of the <code>name</code> property as a <code>long</code>. 1116 * If no such property exists, the provided default value is returned, 1117 * or if the specified value is not a valid <code>long</code>, 1118 * then an error is thrown. 1119 * 1120 * @param name property name. 1121 * @param defaultValue default value. 1122 * @throws NumberFormatException when the value is invalid 1123 * @return property value as a <code>long</code>, 1124 * or <code>defaultValue</code>. 1125 */ 1126 public long getLong(String name, long defaultValue) { 1127 String valueString = getTrimmed(name); 1128 if (valueString == null) 1129 return defaultValue; 1130 String hexString = getHexDigits(valueString); 1131 if (hexString != null) { 1132 return Long.parseLong(hexString, 16); 1133 } 1134 return Long.parseLong(valueString); 1135 } 1136 1137 /** 1138 * Get the value of the <code>name</code> property as a <code>long</code> or 1139 * human readable format. If no such property exists, the provided default 1140 * value is returned, or if the specified value is not a valid 1141 * <code>long</code> or human readable format, then an error is thrown. You 1142 * can use the following suffix (case insensitive): k(kilo), m(mega), g(giga), 1143 * t(tera), p(peta), e(exa) 1144 * 1145 * @param name property name. 1146 * @param defaultValue default value. 1147 * @throws NumberFormatException when the value is invalid 1148 * @return property value as a <code>long</code>, 1149 * or <code>defaultValue</code>. 1150 */ 1151 public long getLongBytes(String name, long defaultValue) { 1152 String valueString = getTrimmed(name); 1153 if (valueString == null) 1154 return defaultValue; 1155 return StringUtils.TraditionalBinaryPrefix.string2long(valueString); 1156 } 1157 1158 private String getHexDigits(String value) { 1159 boolean negative = false; 1160 String str = value; 1161 String hexString = null; 1162 if (value.startsWith("-")) { 1163 negative = true; 1164 str = value.substring(1); 1165 } 1166 if (str.startsWith("0x") || str.startsWith("0X")) { 1167 hexString = str.substring(2); 1168 if (negative) { 1169 hexString = "-" + hexString; 1170 } 1171 return hexString; 1172 } 1173 return null; 1174 } 1175 1176 /** 1177 * Set the value of the <code>name</code> property to a <code>long</code>. 1178 * 1179 * @param name property name. 1180 * @param value <code>long</code> value of the property. 1181 */ 1182 public void setLong(String name, long value) { 1183 set(name, Long.toString(value)); 1184 } 1185 1186 /** 1187 * Get the value of the <code>name</code> property as a <code>float</code>. 1188 * If no such property exists, the provided default value is returned, 1189 * or if the specified value is not a valid <code>float</code>, 1190 * then an error is thrown. 1191 * 1192 * @param name property name. 1193 * @param defaultValue default value. 1194 * @throws NumberFormatException when the value is invalid 1195 * @return property value as a <code>float</code>, 1196 * or <code>defaultValue</code>. 1197 */ 1198 public float getFloat(String name, float defaultValue) { 1199 String valueString = getTrimmed(name); 1200 if (valueString == null) 1201 return defaultValue; 1202 return Float.parseFloat(valueString); 1203 } 1204 1205 /** 1206 * Set the value of the <code>name</code> property to a <code>float</code>. 1207 * 1208 * @param name property name. 1209 * @param value property value. 1210 */ 1211 public void setFloat(String name, float value) { 1212 set(name,Float.toString(value)); 1213 } 1214 1215 /** 1216 * Get the value of the <code>name</code> property as a <code>double</code>. 1217 * If no such property exists, the provided default value is returned, 1218 * or if the specified value is not a valid <code>double</code>, 1219 * then an error is thrown. 1220 * 1221 * @param name property name. 1222 * @param defaultValue default value. 1223 * @throws NumberFormatException when the value is invalid 1224 * @return property value as a <code>double</code>, 1225 * or <code>defaultValue</code>. 1226 */ 1227 public double getDouble(String name, double defaultValue) { 1228 String valueString = getTrimmed(name); 1229 if (valueString == null) 1230 return defaultValue; 1231 return Double.parseDouble(valueString); 1232 } 1233 1234 /** 1235 * Set the value of the <code>name</code> property to a <code>double</code>. 1236 * 1237 * @param name property name. 1238 * @param value property value. 1239 */ 1240 public void setDouble(String name, double value) { 1241 set(name,Double.toString(value)); 1242 } 1243 1244 /** 1245 * Get the value of the <code>name</code> property as a <code>boolean</code>. 1246 * If no such property is specified, or if the specified value is not a valid 1247 * <code>boolean</code>, then <code>defaultValue</code> is returned. 1248 * 1249 * @param name property name. 1250 * @param defaultValue default value. 1251 * @return property value as a <code>boolean</code>, 1252 * or <code>defaultValue</code>. 1253 */ 1254 public boolean getBoolean(String name, boolean defaultValue) { 1255 String valueString = getTrimmed(name); 1256 if (null == valueString || valueString.isEmpty()) { 1257 return defaultValue; 1258 } 1259 1260 valueString = valueString.toLowerCase(); 1261 1262 if ("true".equals(valueString)) 1263 return true; 1264 else if ("false".equals(valueString)) 1265 return false; 1266 else return defaultValue; 1267 } 1268 1269 /** 1270 * Set the value of the <code>name</code> property to a <code>boolean</code>. 1271 * 1272 * @param name property name. 1273 * @param value <code>boolean</code> value of the property. 1274 */ 1275 public void setBoolean(String name, boolean value) { 1276 set(name, Boolean.toString(value)); 1277 } 1278 1279 /** 1280 * Set the given property, if it is currently unset. 1281 * @param name property name 1282 * @param value new value 1283 */ 1284 public void setBooleanIfUnset(String name, boolean value) { 1285 setIfUnset(name, Boolean.toString(value)); 1286 } 1287 1288 /** 1289 * Set the value of the <code>name</code> property to the given type. This 1290 * is equivalent to <code>set(<name>, value.toString())</code>. 1291 * @param name property name 1292 * @param value new value 1293 */ 1294 public <T extends Enum<T>> void setEnum(String name, T value) { 1295 set(name, value.toString()); 1296 } 1297 1298 /** 1299 * Return value matching this enumerated type. 1300 * @param name Property name 1301 * @param defaultValue Value returned if no mapping exists 1302 * @throws IllegalArgumentException If mapping is illegal for the type 1303 * provided 1304 */ 1305 public <T extends Enum<T>> T getEnum(String name, T defaultValue) { 1306 final String val = get(name); 1307 return null == val 1308 ? defaultValue 1309 : Enum.valueOf(defaultValue.getDeclaringClass(), val); 1310 } 1311 1312 enum ParsedTimeDuration { 1313 NS { 1314 TimeUnit unit() { return TimeUnit.NANOSECONDS; } 1315 String suffix() { return "ns"; } 1316 }, 1317 US { 1318 TimeUnit unit() { return TimeUnit.MICROSECONDS; } 1319 String suffix() { return "us"; } 1320 }, 1321 MS { 1322 TimeUnit unit() { return TimeUnit.MILLISECONDS; } 1323 String suffix() { return "ms"; } 1324 }, 1325 S { 1326 TimeUnit unit() { return TimeUnit.SECONDS; } 1327 String suffix() { return "s"; } 1328 }, 1329 M { 1330 TimeUnit unit() { return TimeUnit.MINUTES; } 1331 String suffix() { return "m"; } 1332 }, 1333 H { 1334 TimeUnit unit() { return TimeUnit.HOURS; } 1335 String suffix() { return "h"; } 1336 }, 1337 D { 1338 TimeUnit unit() { return TimeUnit.DAYS; } 1339 String suffix() { return "d"; } 1340 }; 1341 abstract TimeUnit unit(); 1342 abstract String suffix(); 1343 static ParsedTimeDuration unitFor(String s) { 1344 for (ParsedTimeDuration ptd : values()) { 1345 // iteration order is in decl order, so SECONDS matched last 1346 if (s.endsWith(ptd.suffix())) { 1347 return ptd; 1348 } 1349 } 1350 return null; 1351 } 1352 static ParsedTimeDuration unitFor(TimeUnit unit) { 1353 for (ParsedTimeDuration ptd : values()) { 1354 if (ptd.unit() == unit) { 1355 return ptd; 1356 } 1357 } 1358 return null; 1359 } 1360 } 1361 1362 /** 1363 * Set the value of <code>name</code> to the given time duration. This 1364 * is equivalent to <code>set(<name>, value + <time suffix>)</code>. 1365 * @param name Property name 1366 * @param value Time duration 1367 * @param unit Unit of time 1368 */ 1369 public void setTimeDuration(String name, long value, TimeUnit unit) { 1370 set(name, value + ParsedTimeDuration.unitFor(unit).suffix()); 1371 } 1372 1373 /** 1374 * Return time duration in the given time unit. Valid units are encoded in 1375 * properties as suffixes: nanoseconds (ns), microseconds (us), milliseconds 1376 * (ms), seconds (s), minutes (m), hours (h), and days (d). 1377 * @param name Property name 1378 * @param defaultValue Value returned if no mapping exists. 1379 * @param unit Unit to convert the stored property, if it exists. 1380 * @throws NumberFormatException If the property stripped of its unit is not 1381 * a number 1382 */ 1383 public long getTimeDuration(String name, long defaultValue, TimeUnit unit) { 1384 String vStr = get(name); 1385 if (null == vStr) { 1386 return defaultValue; 1387 } 1388 vStr = vStr.trim(); 1389 ParsedTimeDuration vUnit = ParsedTimeDuration.unitFor(vStr); 1390 if (null == vUnit) { 1391 LOG.warn("No unit for " + name + "(" + vStr + ") assuming " + unit); 1392 vUnit = ParsedTimeDuration.unitFor(unit); 1393 } else { 1394 vStr = vStr.substring(0, vStr.lastIndexOf(vUnit.suffix())); 1395 } 1396 return unit.convert(Long.parseLong(vStr), vUnit.unit()); 1397 } 1398 1399 /** 1400 * Get the value of the <code>name</code> property as a <code>Pattern</code>. 1401 * If no such property is specified, or if the specified value is not a valid 1402 * <code>Pattern</code>, then <code>DefaultValue</code> is returned. 1403 * 1404 * @param name property name 1405 * @param defaultValue default value 1406 * @return property value as a compiled Pattern, or defaultValue 1407 */ 1408 public Pattern getPattern(String name, Pattern defaultValue) { 1409 String valString = get(name); 1410 if (null == valString || valString.isEmpty()) { 1411 return defaultValue; 1412 } 1413 try { 1414 return Pattern.compile(valString); 1415 } catch (PatternSyntaxException pse) { 1416 LOG.warn("Regular expression '" + valString + "' for property '" + 1417 name + "' not valid. Using default", pse); 1418 return defaultValue; 1419 } 1420 } 1421 1422 /** 1423 * Set the given property to <code>Pattern</code>. 1424 * If the pattern is passed as null, sets the empty pattern which results in 1425 * further calls to getPattern(...) returning the default value. 1426 * 1427 * @param name property name 1428 * @param pattern new value 1429 */ 1430 public void setPattern(String name, Pattern pattern) { 1431 if (null == pattern) { 1432 set(name, null); 1433 } else { 1434 set(name, pattern.pattern()); 1435 } 1436 } 1437 1438 /** 1439 * Gets information about why a property was set. Typically this is the 1440 * path to the resource objects (file, URL, etc.) the property came from, but 1441 * it can also indicate that it was set programatically, or because of the 1442 * command line. 1443 * 1444 * @param name - The property name to get the source of. 1445 * @return null - If the property or its source wasn't found. Otherwise, 1446 * returns a list of the sources of the resource. The older sources are 1447 * the first ones in the list. So for example if a configuration is set from 1448 * the command line, and then written out to a file that is read back in the 1449 * first entry would indicate that it was set from the command line, while 1450 * the second one would indicate the file that the new configuration was read 1451 * in from. 1452 */ 1453 @InterfaceStability.Unstable 1454 public synchronized String[] getPropertySources(String name) { 1455 if (properties == null) { 1456 // If properties is null, it means a resource was newly added 1457 // but the props were cleared so as to load it upon future 1458 // requests. So lets force a load by asking a properties list. 1459 getProps(); 1460 } 1461 // Return a null right away if our properties still 1462 // haven't loaded or the resource mapping isn't defined 1463 if (properties == null || updatingResource == null) { 1464 return null; 1465 } else { 1466 String[] source = updatingResource.get(name); 1467 if(source == null) { 1468 return null; 1469 } else { 1470 return Arrays.copyOf(source, source.length); 1471 } 1472 } 1473 } 1474 1475 /** 1476 * A class that represents a set of positive integer ranges. It parses 1477 * strings of the form: "2-3,5,7-" where ranges are separated by comma and 1478 * the lower/upper bounds are separated by dash. Either the lower or upper 1479 * bound may be omitted meaning all values up to or over. So the string 1480 * above means 2, 3, 5, and 7, 8, 9, ... 1481 */ 1482 public static class IntegerRanges implements Iterable<Integer>{ 1483 private static class Range { 1484 int start; 1485 int end; 1486 } 1487 1488 private static class RangeNumberIterator implements Iterator<Integer> { 1489 Iterator<Range> internal; 1490 int at; 1491 int end; 1492 1493 public RangeNumberIterator(List<Range> ranges) { 1494 if (ranges != null) { 1495 internal = ranges.iterator(); 1496 } 1497 at = -1; 1498 end = -2; 1499 } 1500 1501 @Override 1502 public boolean hasNext() { 1503 if (at <= end) { 1504 return true; 1505 } else if (internal != null){ 1506 return internal.hasNext(); 1507 } 1508 return false; 1509 } 1510 1511 @Override 1512 public Integer next() { 1513 if (at <= end) { 1514 at++; 1515 return at - 1; 1516 } else if (internal != null){ 1517 Range found = internal.next(); 1518 if (found != null) { 1519 at = found.start; 1520 end = found.end; 1521 at++; 1522 return at - 1; 1523 } 1524 } 1525 return null; 1526 } 1527 1528 @Override 1529 public void remove() { 1530 throw new UnsupportedOperationException(); 1531 } 1532 }; 1533 1534 List<Range> ranges = new ArrayList<Range>(); 1535 1536 public IntegerRanges() { 1537 } 1538 1539 public IntegerRanges(String newValue) { 1540 StringTokenizer itr = new StringTokenizer(newValue, ","); 1541 while (itr.hasMoreTokens()) { 1542 String rng = itr.nextToken().trim(); 1543 String[] parts = rng.split("-", 3); 1544 if (parts.length < 1 || parts.length > 2) { 1545 throw new IllegalArgumentException("integer range badly formed: " + 1546 rng); 1547 } 1548 Range r = new Range(); 1549 r.start = convertToInt(parts[0], 0); 1550 if (parts.length == 2) { 1551 r.end = convertToInt(parts[1], Integer.MAX_VALUE); 1552 } else { 1553 r.end = r.start; 1554 } 1555 if (r.start > r.end) { 1556 throw new IllegalArgumentException("IntegerRange from " + r.start + 1557 " to " + r.end + " is invalid"); 1558 } 1559 ranges.add(r); 1560 } 1561 } 1562 1563 /** 1564 * Convert a string to an int treating empty strings as the default value. 1565 * @param value the string value 1566 * @param defaultValue the value for if the string is empty 1567 * @return the desired integer 1568 */ 1569 private static int convertToInt(String value, int defaultValue) { 1570 String trim = value.trim(); 1571 if (trim.length() == 0) { 1572 return defaultValue; 1573 } 1574 return Integer.parseInt(trim); 1575 } 1576 1577 /** 1578 * Is the given value in the set of ranges 1579 * @param value the value to check 1580 * @return is the value in the ranges? 1581 */ 1582 public boolean isIncluded(int value) { 1583 for(Range r: ranges) { 1584 if (r.start <= value && value <= r.end) { 1585 return true; 1586 } 1587 } 1588 return false; 1589 } 1590 1591 /** 1592 * @return true if there are no values in this range, else false. 1593 */ 1594 public boolean isEmpty() { 1595 return ranges == null || ranges.isEmpty(); 1596 } 1597 1598 @Override 1599 public String toString() { 1600 StringBuilder result = new StringBuilder(); 1601 boolean first = true; 1602 for(Range r: ranges) { 1603 if (first) { 1604 first = false; 1605 } else { 1606 result.append(','); 1607 } 1608 result.append(r.start); 1609 result.append('-'); 1610 result.append(r.end); 1611 } 1612 return result.toString(); 1613 } 1614 1615 @Override 1616 public Iterator<Integer> iterator() { 1617 return new RangeNumberIterator(ranges); 1618 } 1619 1620 } 1621 1622 /** 1623 * Parse the given attribute as a set of integer ranges 1624 * @param name the attribute name 1625 * @param defaultValue the default value if it is not set 1626 * @return a new set of ranges from the configured value 1627 */ 1628 public IntegerRanges getRange(String name, String defaultValue) { 1629 return new IntegerRanges(get(name, defaultValue)); 1630 } 1631 1632 /** 1633 * Get the comma delimited values of the <code>name</code> property as 1634 * a collection of <code>String</code>s. 1635 * If no such property is specified then empty collection is returned. 1636 * <p> 1637 * This is an optimized version of {@link #getStrings(String)} 1638 * 1639 * @param name property name. 1640 * @return property value as a collection of <code>String</code>s. 1641 */ 1642 public Collection<String> getStringCollection(String name) { 1643 String valueString = get(name); 1644 return StringUtils.getStringCollection(valueString); 1645 } 1646 1647 /** 1648 * Get the comma delimited values of the <code>name</code> property as 1649 * an array of <code>String</code>s. 1650 * If no such property is specified then <code>null</code> is returned. 1651 * 1652 * @param name property name. 1653 * @return property value as an array of <code>String</code>s, 1654 * or <code>null</code>. 1655 */ 1656 public String[] getStrings(String name) { 1657 String valueString = get(name); 1658 return StringUtils.getStrings(valueString); 1659 } 1660 1661 /** 1662 * Get the comma delimited values of the <code>name</code> property as 1663 * an array of <code>String</code>s. 1664 * If no such property is specified then default value is returned. 1665 * 1666 * @param name property name. 1667 * @param defaultValue The default value 1668 * @return property value as an array of <code>String</code>s, 1669 * or default value. 1670 */ 1671 public String[] getStrings(String name, String... defaultValue) { 1672 String valueString = get(name); 1673 if (valueString == null) { 1674 return defaultValue; 1675 } else { 1676 return StringUtils.getStrings(valueString); 1677 } 1678 } 1679 1680 /** 1681 * Get the comma delimited values of the <code>name</code> property as 1682 * a collection of <code>String</code>s, trimmed of the leading and trailing whitespace. 1683 * If no such property is specified then empty <code>Collection</code> is returned. 1684 * 1685 * @param name property name. 1686 * @return property value as a collection of <code>String</code>s, or empty <code>Collection</code> 1687 */ 1688 public Collection<String> getTrimmedStringCollection(String name) { 1689 String valueString = get(name); 1690 if (null == valueString) { 1691 Collection<String> empty = new ArrayList<String>(); 1692 return empty; 1693 } 1694 return StringUtils.getTrimmedStringCollection(valueString); 1695 } 1696 1697 /** 1698 * Get the comma delimited values of the <code>name</code> property as 1699 * an array of <code>String</code>s, trimmed of the leading and trailing whitespace. 1700 * If no such property is specified then an empty array is returned. 1701 * 1702 * @param name property name. 1703 * @return property value as an array of trimmed <code>String</code>s, 1704 * or empty array. 1705 */ 1706 public String[] getTrimmedStrings(String name) { 1707 String valueString = get(name); 1708 return StringUtils.getTrimmedStrings(valueString); 1709 } 1710 1711 /** 1712 * Get the comma delimited values of the <code>name</code> property as 1713 * an array of <code>String</code>s, trimmed of the leading and trailing whitespace. 1714 * If no such property is specified then default value is returned. 1715 * 1716 * @param name property name. 1717 * @param defaultValue The default value 1718 * @return property value as an array of trimmed <code>String</code>s, 1719 * or default value. 1720 */ 1721 public String[] getTrimmedStrings(String name, String... defaultValue) { 1722 String valueString = get(name); 1723 if (null == valueString) { 1724 return defaultValue; 1725 } else { 1726 return StringUtils.getTrimmedStrings(valueString); 1727 } 1728 } 1729 1730 /** 1731 * Set the array of string values for the <code>name</code> property as 1732 * as comma delimited values. 1733 * 1734 * @param name property name. 1735 * @param values The values 1736 */ 1737 public void setStrings(String name, String... values) { 1738 set(name, StringUtils.arrayToString(values)); 1739 } 1740 1741 /** 1742 * Get the socket address for <code>name</code> property as a 1743 * <code>InetSocketAddress</code>. 1744 * @param name property name. 1745 * @param defaultAddress the default value 1746 * @param defaultPort the default port 1747 * @return InetSocketAddress 1748 */ 1749 public InetSocketAddress getSocketAddr( 1750 String name, String defaultAddress, int defaultPort) { 1751 final String address = get(name, defaultAddress); 1752 return NetUtils.createSocketAddr(address, defaultPort, name); 1753 } 1754 1755 /** 1756 * Set the socket address for the <code>name</code> property as 1757 * a <code>host:port</code>. 1758 */ 1759 public void setSocketAddr(String name, InetSocketAddress addr) { 1760 set(name, NetUtils.getHostPortString(addr)); 1761 } 1762 1763 /** 1764 * Set the socket address a client can use to connect for the 1765 * <code>name</code> property as a <code>host:port</code>. The wildcard 1766 * address is replaced with the local host's address. 1767 * @param name property name. 1768 * @param addr InetSocketAddress of a listener to store in the given property 1769 * @return InetSocketAddress for clients to connect 1770 */ 1771 public InetSocketAddress updateConnectAddr(String name, 1772 InetSocketAddress addr) { 1773 final InetSocketAddress connectAddr = NetUtils.getConnectAddress(addr); 1774 setSocketAddr(name, connectAddr); 1775 return connectAddr; 1776 } 1777 1778 /** 1779 * Load a class by name. 1780 * 1781 * @param name the class name. 1782 * @return the class object. 1783 * @throws ClassNotFoundException if the class is not found. 1784 */ 1785 public Class<?> getClassByName(String name) throws ClassNotFoundException { 1786 Class<?> ret = getClassByNameOrNull(name); 1787 if (ret == null) { 1788 throw new ClassNotFoundException("Class " + name + " not found"); 1789 } 1790 return ret; 1791 } 1792 1793 /** 1794 * Load a class by name, returning null rather than throwing an exception 1795 * if it couldn't be loaded. This is to avoid the overhead of creating 1796 * an exception. 1797 * 1798 * @param name the class name 1799 * @return the class object, or null if it could not be found. 1800 */ 1801 public Class<?> getClassByNameOrNull(String name) { 1802 Map<String, WeakReference<Class<?>>> map; 1803 1804 synchronized (CACHE_CLASSES) { 1805 map = CACHE_CLASSES.get(classLoader); 1806 if (map == null) { 1807 map = Collections.synchronizedMap( 1808 new WeakHashMap<String, WeakReference<Class<?>>>()); 1809 CACHE_CLASSES.put(classLoader, map); 1810 } 1811 } 1812 1813 Class<?> clazz = null; 1814 WeakReference<Class<?>> ref = map.get(name); 1815 if (ref != null) { 1816 clazz = ref.get(); 1817 } 1818 1819 if (clazz == null) { 1820 try { 1821 clazz = Class.forName(name, true, classLoader); 1822 } catch (ClassNotFoundException e) { 1823 // Leave a marker that the class isn't found 1824 map.put(name, new WeakReference<Class<?>>(NEGATIVE_CACHE_SENTINEL)); 1825 return null; 1826 } 1827 // two putters can race here, but they'll put the same class 1828 map.put(name, new WeakReference<Class<?>>(clazz)); 1829 return clazz; 1830 } else if (clazz == NEGATIVE_CACHE_SENTINEL) { 1831 return null; // not found 1832 } else { 1833 // cache hit 1834 return clazz; 1835 } 1836 } 1837 1838 /** 1839 * Get the value of the <code>name</code> property 1840 * as an array of <code>Class</code>. 1841 * The value of the property specifies a list of comma separated class names. 1842 * If no such property is specified, then <code>defaultValue</code> is 1843 * returned. 1844 * 1845 * @param name the property name. 1846 * @param defaultValue default value. 1847 * @return property value as a <code>Class[]</code>, 1848 * or <code>defaultValue</code>. 1849 */ 1850 public Class<?>[] getClasses(String name, Class<?> ... defaultValue) { 1851 String[] classnames = getTrimmedStrings(name); 1852 if (classnames == null) 1853 return defaultValue; 1854 try { 1855 Class<?>[] classes = new Class<?>[classnames.length]; 1856 for(int i = 0; i < classnames.length; i++) { 1857 classes[i] = getClassByName(classnames[i]); 1858 } 1859 return classes; 1860 } catch (ClassNotFoundException e) { 1861 throw new RuntimeException(e); 1862 } 1863 } 1864 1865 /** 1866 * Get the value of the <code>name</code> property as a <code>Class</code>. 1867 * If no such property is specified, then <code>defaultValue</code> is 1868 * returned. 1869 * 1870 * @param name the class name. 1871 * @param defaultValue default value. 1872 * @return property value as a <code>Class</code>, 1873 * or <code>defaultValue</code>. 1874 */ 1875 public Class<?> getClass(String name, Class<?> defaultValue) { 1876 String valueString = getTrimmed(name); 1877 if (valueString == null) 1878 return defaultValue; 1879 try { 1880 return getClassByName(valueString); 1881 } catch (ClassNotFoundException e) { 1882 throw new RuntimeException(e); 1883 } 1884 } 1885 1886 /** 1887 * Get the value of the <code>name</code> property as a <code>Class</code> 1888 * implementing the interface specified by <code>xface</code>. 1889 * 1890 * If no such property is specified, then <code>defaultValue</code> is 1891 * returned. 1892 * 1893 * An exception is thrown if the returned class does not implement the named 1894 * interface. 1895 * 1896 * @param name the class name. 1897 * @param defaultValue default value. 1898 * @param xface the interface implemented by the named class. 1899 * @return property value as a <code>Class</code>, 1900 * or <code>defaultValue</code>. 1901 */ 1902 public <U> Class<? extends U> getClass(String name, 1903 Class<? extends U> defaultValue, 1904 Class<U> xface) { 1905 try { 1906 Class<?> theClass = getClass(name, defaultValue); 1907 if (theClass != null && !xface.isAssignableFrom(theClass)) 1908 throw new RuntimeException(theClass+" not "+xface.getName()); 1909 else if (theClass != null) 1910 return theClass.asSubclass(xface); 1911 else 1912 return null; 1913 } catch (Exception e) { 1914 throw new RuntimeException(e); 1915 } 1916 } 1917 1918 /** 1919 * Get the value of the <code>name</code> property as a <code>List</code> 1920 * of objects implementing the interface specified by <code>xface</code>. 1921 * 1922 * An exception is thrown if any of the classes does not exist, or if it does 1923 * not implement the named interface. 1924 * 1925 * @param name the property name. 1926 * @param xface the interface implemented by the classes named by 1927 * <code>name</code>. 1928 * @return a <code>List</code> of objects implementing <code>xface</code>. 1929 */ 1930 @SuppressWarnings("unchecked") 1931 public <U> List<U> getInstances(String name, Class<U> xface) { 1932 List<U> ret = new ArrayList<U>(); 1933 Class<?>[] classes = getClasses(name); 1934 for (Class<?> cl: classes) { 1935 if (!xface.isAssignableFrom(cl)) { 1936 throw new RuntimeException(cl + " does not implement " + xface); 1937 } 1938 ret.add((U)ReflectionUtils.newInstance(cl, this)); 1939 } 1940 return ret; 1941 } 1942 1943 /** 1944 * Set the value of the <code>name</code> property to the name of a 1945 * <code>theClass</code> implementing the given interface <code>xface</code>. 1946 * 1947 * An exception is thrown if <code>theClass</code> does not implement the 1948 * interface <code>xface</code>. 1949 * 1950 * @param name property name. 1951 * @param theClass property value. 1952 * @param xface the interface implemented by the named class. 1953 */ 1954 public void setClass(String name, Class<?> theClass, Class<?> xface) { 1955 if (!xface.isAssignableFrom(theClass)) 1956 throw new RuntimeException(theClass+" not "+xface.getName()); 1957 set(name, theClass.getName()); 1958 } 1959 1960 /** 1961 * Get a local file under a directory named by <i>dirsProp</i> with 1962 * the given <i>path</i>. If <i>dirsProp</i> contains multiple directories, 1963 * then one is chosen based on <i>path</i>'s hash code. If the selected 1964 * directory does not exist, an attempt is made to create it. 1965 * 1966 * @param dirsProp directory in which to locate the file. 1967 * @param path file-path. 1968 * @return local file under the directory with the given path. 1969 */ 1970 public Path getLocalPath(String dirsProp, String path) 1971 throws IOException { 1972 String[] dirs = getTrimmedStrings(dirsProp); 1973 int hashCode = path.hashCode(); 1974 FileSystem fs = FileSystem.getLocal(this); 1975 for (int i = 0; i < dirs.length; i++) { // try each local dir 1976 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length; 1977 Path file = new Path(dirs[index], path); 1978 Path dir = file.getParent(); 1979 if (fs.mkdirs(dir) || fs.exists(dir)) { 1980 return file; 1981 } 1982 } 1983 LOG.warn("Could not make " + path + 1984 " in local directories from " + dirsProp); 1985 for(int i=0; i < dirs.length; i++) { 1986 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length; 1987 LOG.warn(dirsProp + "[" + index + "]=" + dirs[index]); 1988 } 1989 throw new IOException("No valid local directories in property: "+dirsProp); 1990 } 1991 1992 /** 1993 * Get a local file name under a directory named in <i>dirsProp</i> with 1994 * the given <i>path</i>. If <i>dirsProp</i> contains multiple directories, 1995 * then one is chosen based on <i>path</i>'s hash code. If the selected 1996 * directory does not exist, an attempt is made to create it. 1997 * 1998 * @param dirsProp directory in which to locate the file. 1999 * @param path file-path. 2000 * @return local file under the directory with the given path. 2001 */ 2002 public File getFile(String dirsProp, String path) 2003 throws IOException { 2004 String[] dirs = getTrimmedStrings(dirsProp); 2005 int hashCode = path.hashCode(); 2006 for (int i = 0; i < dirs.length; i++) { // try each local dir 2007 int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length; 2008 File file = new File(dirs[index], path); 2009 File dir = file.getParentFile(); 2010 if (dir.exists() || dir.mkdirs()) { 2011 return file; 2012 } 2013 } 2014 throw new IOException("No valid local directories in property: "+dirsProp); 2015 } 2016 2017 /** 2018 * Get the {@link URL} for the named resource. 2019 * 2020 * @param name resource name. 2021 * @return the url for the named resource. 2022 */ 2023 public URL getResource(String name) { 2024 return classLoader.getResource(name); 2025 } 2026 2027 /** 2028 * Get an input stream attached to the configuration resource with the 2029 * given <code>name</code>. 2030 * 2031 * @param name configuration resource name. 2032 * @return an input stream attached to the resource. 2033 */ 2034 public InputStream getConfResourceAsInputStream(String name) { 2035 try { 2036 URL url= getResource(name); 2037 2038 if (url == null) { 2039 LOG.info(name + " not found"); 2040 return null; 2041 } else { 2042 LOG.info("found resource " + name + " at " + url); 2043 } 2044 2045 return url.openStream(); 2046 } catch (Exception e) { 2047 return null; 2048 } 2049 } 2050 2051 /** 2052 * Get a {@link Reader} attached to the configuration resource with the 2053 * given <code>name</code>. 2054 * 2055 * @param name configuration resource name. 2056 * @return a reader attached to the resource. 2057 */ 2058 public Reader getConfResourceAsReader(String name) { 2059 try { 2060 URL url= getResource(name); 2061 2062 if (url == null) { 2063 LOG.info(name + " not found"); 2064 return null; 2065 } else { 2066 LOG.info("found resource " + name + " at " + url); 2067 } 2068 2069 return new InputStreamReader(url.openStream()); 2070 } catch (Exception e) { 2071 return null; 2072 } 2073 } 2074 2075 /** 2076 * Get the set of parameters marked final. 2077 * 2078 * @return final parameter set. 2079 */ 2080 public Set<String> getFinalParameters() { 2081 return new HashSet<String>(finalParameters); 2082 } 2083 2084 protected synchronized Properties getProps() { 2085 if (properties == null) { 2086 properties = new Properties(); 2087 HashMap<String, String[]> backup = 2088 new HashMap<String, String[]>(updatingResource); 2089 loadResources(properties, resources, quietmode); 2090 if (overlay!= null) { 2091 properties.putAll(overlay); 2092 for (Map.Entry<Object,Object> item: overlay.entrySet()) { 2093 String key = (String)item.getKey(); 2094 updatingResource.put(key, backup.get(key)); 2095 } 2096 } 2097 } 2098 return properties; 2099 } 2100 2101 /** 2102 * Return the number of keys in the configuration. 2103 * 2104 * @return number of keys in the configuration. 2105 */ 2106 public int size() { 2107 return getProps().size(); 2108 } 2109 2110 /** 2111 * Clears all keys from the configuration. 2112 */ 2113 public void clear() { 2114 getProps().clear(); 2115 getOverlay().clear(); 2116 } 2117 2118 /** 2119 * Get an {@link Iterator} to go through the list of <code>String</code> 2120 * key-value pairs in the configuration. 2121 * 2122 * @return an iterator over the entries. 2123 */ 2124 @Override 2125 public Iterator<Map.Entry<String, String>> iterator() { 2126 // Get a copy of just the string to string pairs. After the old object 2127 // methods that allow non-strings to be put into configurations are removed, 2128 // we could replace properties with a Map<String,String> and get rid of this 2129 // code. 2130 Map<String,String> result = new HashMap<String,String>(); 2131 for(Map.Entry<Object,Object> item: getProps().entrySet()) { 2132 if (item.getKey() instanceof String && 2133 item.getValue() instanceof String) { 2134 result.put((String) item.getKey(), (String) item.getValue()); 2135 } 2136 } 2137 return result.entrySet().iterator(); 2138 } 2139 2140 private Document parse(DocumentBuilder builder, URL url) 2141 throws IOException, SAXException { 2142 if (!quietmode) { 2143 LOG.debug("parsing URL " + url); 2144 } 2145 if (url == null) { 2146 return null; 2147 } 2148 return parse(builder, url.openStream(), url.toString()); 2149 } 2150 2151 private Document parse(DocumentBuilder builder, InputStream is, 2152 String systemId) throws IOException, SAXException { 2153 if (!quietmode) { 2154 LOG.debug("parsing input stream " + is); 2155 } 2156 if (is == null) { 2157 return null; 2158 } 2159 try { 2160 return (systemId == null) ? builder.parse(is) : builder.parse(is, 2161 systemId); 2162 } finally { 2163 is.close(); 2164 } 2165 } 2166 2167 private void loadResources(Properties properties, 2168 ArrayList<Resource> resources, 2169 boolean quiet) { 2170 if(loadDefaults) { 2171 for (String resource : defaultResources) { 2172 loadResource(properties, new Resource(resource), quiet); 2173 } 2174 2175 //support the hadoop-site.xml as a deprecated case 2176 if(getResource("hadoop-site.xml")!=null) { 2177 loadResource(properties, new Resource("hadoop-site.xml"), quiet); 2178 } 2179 } 2180 2181 for (int i = 0; i < resources.size(); i++) { 2182 Resource ret = loadResource(properties, resources.get(i), quiet); 2183 if (ret != null) { 2184 resources.set(i, ret); 2185 } 2186 } 2187 } 2188 2189 private Resource loadResource(Properties properties, Resource wrapper, boolean quiet) { 2190 String name = UNKNOWN_RESOURCE; 2191 try { 2192 Object resource = wrapper.getResource(); 2193 name = wrapper.getName(); 2194 2195 DocumentBuilderFactory docBuilderFactory 2196 = DocumentBuilderFactory.newInstance(); 2197 //ignore all comments inside the xml file 2198 docBuilderFactory.setIgnoringComments(true); 2199 2200 //allow includes in the xml file 2201 docBuilderFactory.setNamespaceAware(true); 2202 try { 2203 docBuilderFactory.setXIncludeAware(true); 2204 } catch (UnsupportedOperationException e) { 2205 LOG.error("Failed to set setXIncludeAware(true) for parser " 2206 + docBuilderFactory 2207 + ":" + e, 2208 e); 2209 } 2210 DocumentBuilder builder = docBuilderFactory.newDocumentBuilder(); 2211 Document doc = null; 2212 Element root = null; 2213 boolean returnCachedProperties = false; 2214 2215 if (resource instanceof URL) { // an URL resource 2216 doc = parse(builder, (URL)resource); 2217 } else if (resource instanceof String) { // a CLASSPATH resource 2218 URL url = getResource((String)resource); 2219 doc = parse(builder, url); 2220 } else if (resource instanceof Path) { // a file resource 2221 // Can't use FileSystem API or we get an infinite loop 2222 // since FileSystem uses Configuration API. Use java.io.File instead. 2223 File file = new File(((Path)resource).toUri().getPath()) 2224 .getAbsoluteFile(); 2225 if (file.exists()) { 2226 if (!quiet) { 2227 LOG.debug("parsing File " + file); 2228 } 2229 doc = parse(builder, new BufferedInputStream( 2230 new FileInputStream(file)), ((Path)resource).toString()); 2231 } 2232 } else if (resource instanceof InputStream) { 2233 doc = parse(builder, (InputStream) resource, null); 2234 returnCachedProperties = true; 2235 } else if (resource instanceof Properties) { 2236 overlay(properties, (Properties)resource); 2237 } else if (resource instanceof Element) { 2238 root = (Element)resource; 2239 } 2240 2241 if (doc == null && root == null) { 2242 if (quiet) 2243 return null; 2244 throw new RuntimeException(resource + " not found"); 2245 } 2246 2247 if (root == null) { 2248 root = doc.getDocumentElement(); 2249 } 2250 Properties toAddTo = properties; 2251 if(returnCachedProperties) { 2252 toAddTo = new Properties(); 2253 } 2254 if (!"configuration".equals(root.getTagName())) 2255 LOG.fatal("bad conf file: top-level element not <configuration>"); 2256 NodeList props = root.getChildNodes(); 2257 DeprecationContext deprecations = deprecationContext.get(); 2258 for (int i = 0; i < props.getLength(); i++) { 2259 Node propNode = props.item(i); 2260 if (!(propNode instanceof Element)) 2261 continue; 2262 Element prop = (Element)propNode; 2263 if ("configuration".equals(prop.getTagName())) { 2264 loadResource(toAddTo, new Resource(prop, name), quiet); 2265 continue; 2266 } 2267 if (!"property".equals(prop.getTagName())) 2268 LOG.warn("bad conf file: element not <property>"); 2269 NodeList fields = prop.getChildNodes(); 2270 String attr = null; 2271 String value = null; 2272 boolean finalParameter = false; 2273 LinkedList<String> source = new LinkedList<String>(); 2274 for (int j = 0; j < fields.getLength(); j++) { 2275 Node fieldNode = fields.item(j); 2276 if (!(fieldNode instanceof Element)) 2277 continue; 2278 Element field = (Element)fieldNode; 2279 if ("name".equals(field.getTagName()) && field.hasChildNodes()) 2280 attr = StringInterner.weakIntern( 2281 ((Text)field.getFirstChild()).getData().trim()); 2282 if ("value".equals(field.getTagName()) && field.hasChildNodes()) 2283 value = StringInterner.weakIntern( 2284 ((Text)field.getFirstChild()).getData()); 2285 if ("final".equals(field.getTagName()) && field.hasChildNodes()) 2286 finalParameter = "true".equals(((Text)field.getFirstChild()).getData()); 2287 if ("source".equals(field.getTagName()) && field.hasChildNodes()) 2288 source.add(StringInterner.weakIntern( 2289 ((Text)field.getFirstChild()).getData())); 2290 } 2291 source.add(name); 2292 2293 // Ignore this parameter if it has already been marked as 'final' 2294 if (attr != null) { 2295 if (deprecations.getDeprecatedKeyMap().containsKey(attr)) { 2296 DeprecatedKeyInfo keyInfo = 2297 deprecations.getDeprecatedKeyMap().get(attr); 2298 keyInfo.clearAccessed(); 2299 for (String key:keyInfo.newKeys) { 2300 // update new keys with deprecated key's value 2301 loadProperty(toAddTo, name, key, value, finalParameter, 2302 source.toArray(new String[source.size()])); 2303 } 2304 } 2305 else { 2306 loadProperty(toAddTo, name, attr, value, finalParameter, 2307 source.toArray(new String[source.size()])); 2308 } 2309 } 2310 } 2311 2312 if (returnCachedProperties) { 2313 overlay(properties, toAddTo); 2314 return new Resource(toAddTo, name); 2315 } 2316 return null; 2317 } catch (IOException e) { 2318 LOG.fatal("error parsing conf " + name, e); 2319 throw new RuntimeException(e); 2320 } catch (DOMException e) { 2321 LOG.fatal("error parsing conf " + name, e); 2322 throw new RuntimeException(e); 2323 } catch (SAXException e) { 2324 LOG.fatal("error parsing conf " + name, e); 2325 throw new RuntimeException(e); 2326 } catch (ParserConfigurationException e) { 2327 LOG.fatal("error parsing conf " + name , e); 2328 throw new RuntimeException(e); 2329 } 2330 } 2331 2332 private void overlay(Properties to, Properties from) { 2333 for (Entry<Object, Object> entry: from.entrySet()) { 2334 to.put(entry.getKey(), entry.getValue()); 2335 } 2336 } 2337 2338 private void loadProperty(Properties properties, String name, String attr, 2339 String value, boolean finalParameter, String[] source) { 2340 if (value != null) { 2341 if (!finalParameters.contains(attr)) { 2342 properties.setProperty(attr, value); 2343 updatingResource.put(attr, source); 2344 } else { 2345 LOG.warn(name+":an attempt to override final parameter: "+attr 2346 +"; Ignoring."); 2347 } 2348 } 2349 if (finalParameter) { 2350 finalParameters.add(attr); 2351 } 2352 } 2353 2354 /** 2355 * Write out the non-default properties in this configuration to the given 2356 * {@link OutputStream} using UTF-8 encoding. 2357 * 2358 * @param out the output stream to write to. 2359 */ 2360 public void writeXml(OutputStream out) throws IOException { 2361 writeXml(new OutputStreamWriter(out, "UTF-8")); 2362 } 2363 2364 /** 2365 * Write out the non-default properties in this configuration to the given 2366 * {@link Writer}. 2367 * 2368 * @param out the writer to write to. 2369 */ 2370 public void writeXml(Writer out) throws IOException { 2371 Document doc = asXmlDocument(); 2372 2373 try { 2374 DOMSource source = new DOMSource(doc); 2375 StreamResult result = new StreamResult(out); 2376 TransformerFactory transFactory = TransformerFactory.newInstance(); 2377 Transformer transformer = transFactory.newTransformer(); 2378 2379 // Important to not hold Configuration log while writing result, since 2380 // 'out' may be an HDFS stream which needs to lock this configuration 2381 // from another thread. 2382 transformer.transform(source, result); 2383 } catch (TransformerException te) { 2384 throw new IOException(te); 2385 } 2386 } 2387 2388 /** 2389 * Return the XML DOM corresponding to this Configuration. 2390 */ 2391 private synchronized Document asXmlDocument() throws IOException { 2392 Document doc; 2393 try { 2394 doc = 2395 DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument(); 2396 } catch (ParserConfigurationException pe) { 2397 throw new IOException(pe); 2398 } 2399 Element conf = doc.createElement("configuration"); 2400 doc.appendChild(conf); 2401 conf.appendChild(doc.createTextNode("\n")); 2402 handleDeprecation(); //ensure properties is set and deprecation is handled 2403 for (Enumeration<Object> e = properties.keys(); e.hasMoreElements();) { 2404 String name = (String)e.nextElement(); 2405 Object object = properties.get(name); 2406 String value = null; 2407 if (object instanceof String) { 2408 value = (String) object; 2409 }else { 2410 continue; 2411 } 2412 Element propNode = doc.createElement("property"); 2413 conf.appendChild(propNode); 2414 2415 Element nameNode = doc.createElement("name"); 2416 nameNode.appendChild(doc.createTextNode(name)); 2417 propNode.appendChild(nameNode); 2418 2419 Element valueNode = doc.createElement("value"); 2420 valueNode.appendChild(doc.createTextNode(value)); 2421 propNode.appendChild(valueNode); 2422 2423 if (updatingResource != null) { 2424 String[] sources = updatingResource.get(name); 2425 if(sources != null) { 2426 for(String s : sources) { 2427 Element sourceNode = doc.createElement("source"); 2428 sourceNode.appendChild(doc.createTextNode(s)); 2429 propNode.appendChild(sourceNode); 2430 } 2431 } 2432 } 2433 2434 conf.appendChild(doc.createTextNode("\n")); 2435 } 2436 return doc; 2437 } 2438 2439 /** 2440 * Writes out all the parameters and their properties (final and resource) to 2441 * the given {@link Writer} 2442 * The format of the output would be 2443 * { "properties" : [ {key1,value1,key1.isFinal,key1.resource}, {key2,value2, 2444 * key2.isFinal,key2.resource}... ] } 2445 * It does not output the parameters of the configuration object which is 2446 * loaded from an input stream. 2447 * @param out the Writer to write to 2448 * @throws IOException 2449 */ 2450 public static void dumpConfiguration(Configuration config, 2451 Writer out) throws IOException { 2452 JsonFactory dumpFactory = new JsonFactory(); 2453 JsonGenerator dumpGenerator = dumpFactory.createJsonGenerator(out); 2454 dumpGenerator.writeStartObject(); 2455 dumpGenerator.writeFieldName("properties"); 2456 dumpGenerator.writeStartArray(); 2457 dumpGenerator.flush(); 2458 synchronized (config) { 2459 for (Map.Entry<Object,Object> item: config.getProps().entrySet()) { 2460 dumpGenerator.writeStartObject(); 2461 dumpGenerator.writeStringField("key", (String) item.getKey()); 2462 dumpGenerator.writeStringField("value", 2463 config.get((String) item.getKey())); 2464 dumpGenerator.writeBooleanField("isFinal", 2465 config.finalParameters.contains(item.getKey())); 2466 String[] resources = config.updatingResource.get(item.getKey()); 2467 String resource = UNKNOWN_RESOURCE; 2468 if(resources != null && resources.length > 0) { 2469 resource = resources[0]; 2470 } 2471 dumpGenerator.writeStringField("resource", resource); 2472 dumpGenerator.writeEndObject(); 2473 } 2474 } 2475 dumpGenerator.writeEndArray(); 2476 dumpGenerator.writeEndObject(); 2477 dumpGenerator.flush(); 2478 } 2479 2480 /** 2481 * Get the {@link ClassLoader} for this job. 2482 * 2483 * @return the correct class loader. 2484 */ 2485 public ClassLoader getClassLoader() { 2486 return classLoader; 2487 } 2488 2489 /** 2490 * Set the class loader that will be used to load the various objects. 2491 * 2492 * @param classLoader the new class loader. 2493 */ 2494 public void setClassLoader(ClassLoader classLoader) { 2495 this.classLoader = classLoader; 2496 } 2497 2498 @Override 2499 public String toString() { 2500 StringBuilder sb = new StringBuilder(); 2501 sb.append("Configuration: "); 2502 if(loadDefaults) { 2503 toString(defaultResources, sb); 2504 if(resources.size()>0) { 2505 sb.append(", "); 2506 } 2507 } 2508 toString(resources, sb); 2509 return sb.toString(); 2510 } 2511 2512 private <T> void toString(List<T> resources, StringBuilder sb) { 2513 ListIterator<T> i = resources.listIterator(); 2514 while (i.hasNext()) { 2515 if (i.nextIndex() != 0) { 2516 sb.append(", "); 2517 } 2518 sb.append(i.next()); 2519 } 2520 } 2521 2522 /** 2523 * Set the quietness-mode. 2524 * 2525 * In the quiet-mode, error and informational messages might not be logged. 2526 * 2527 * @param quietmode <code>true</code> to set quiet-mode on, <code>false</code> 2528 * to turn it off. 2529 */ 2530 public synchronized void setQuietMode(boolean quietmode) { 2531 this.quietmode = quietmode; 2532 } 2533 2534 synchronized boolean getQuietMode() { 2535 return this.quietmode; 2536 } 2537 2538 /** For debugging. List non-default properties to the terminal and exit. */ 2539 public static void main(String[] args) throws Exception { 2540 new Configuration().writeXml(System.out); 2541 } 2542 2543 @Override 2544 public void readFields(DataInput in) throws IOException { 2545 clear(); 2546 int size = WritableUtils.readVInt(in); 2547 for(int i=0; i < size; ++i) { 2548 String key = org.apache.hadoop.io.Text.readString(in); 2549 String value = org.apache.hadoop.io.Text.readString(in); 2550 set(key, value); 2551 String sources[] = WritableUtils.readCompressedStringArray(in); 2552 updatingResource.put(key, sources); 2553 } 2554 } 2555 2556 //@Override 2557 @Override 2558 public void write(DataOutput out) throws IOException { 2559 Properties props = getProps(); 2560 WritableUtils.writeVInt(out, props.size()); 2561 for(Map.Entry<Object, Object> item: props.entrySet()) { 2562 org.apache.hadoop.io.Text.writeString(out, (String) item.getKey()); 2563 org.apache.hadoop.io.Text.writeString(out, (String) item.getValue()); 2564 WritableUtils.writeCompressedStringArray(out, 2565 updatingResource.get(item.getKey())); 2566 } 2567 } 2568 2569 /** 2570 * get keys matching the the regex 2571 * @param regex 2572 * @return Map<String,String> with matching keys 2573 */ 2574 public Map<String,String> getValByRegex(String regex) { 2575 Pattern p = Pattern.compile(regex); 2576 2577 Map<String,String> result = new HashMap<String,String>(); 2578 Matcher m; 2579 2580 for(Map.Entry<Object,Object> item: getProps().entrySet()) { 2581 if (item.getKey() instanceof String && 2582 item.getValue() instanceof String) { 2583 m = p.matcher((String)item.getKey()); 2584 if(m.find()) { // match 2585 result.put((String) item.getKey(), (String) item.getValue()); 2586 } 2587 } 2588 } 2589 return result; 2590 } 2591 2592 /** 2593 * A unique class which is used as a sentinel value in the caching 2594 * for getClassByName. {@see Configuration#getClassByNameOrNull(String)} 2595 */ 2596 private static abstract class NegativeCacheSentinel {} 2597 2598 public static void dumpDeprecatedKeys() { 2599 DeprecationContext deprecations = deprecationContext.get(); 2600 for (Map.Entry<String, DeprecatedKeyInfo> entry : 2601 deprecations.getDeprecatedKeyMap().entrySet()) { 2602 StringBuilder newKeys = new StringBuilder(); 2603 for (String newKey : entry.getValue().newKeys) { 2604 newKeys.append(newKey).append("\t"); 2605 } 2606 System.out.println(entry.getKey() + "\t" + newKeys.toString()); 2607 } 2608 } 2609 2610 /** 2611 * Returns whether or not a deprecated name has been warned. If the name is not 2612 * deprecated then always return false 2613 */ 2614 public static boolean hasWarnedDeprecation(String name) { 2615 DeprecationContext deprecations = deprecationContext.get(); 2616 if(deprecations.getDeprecatedKeyMap().containsKey(name)) { 2617 if(deprecations.getDeprecatedKeyMap().get(name).accessed.get()) { 2618 return true; 2619 } 2620 } 2621 return false; 2622 } 2623 }