Configuration.java
上传用户:quxuerui
上传日期:2018-01-08
资源大小:41811k
文件大小:41k
源码类别:

网格计算

开发平台:

Java

  1. /**
  2.  * Licensed to the Apache Software Foundation (ASF) under one
  3.  * or more contributor license agreements.  See the NOTICE file
  4.  * distributed with this work for additional information
  5.  * regarding copyright ownership.  The ASF licenses this file
  6.  * to you under the Apache License, Version 2.0 (the
  7.  * "License"); you may not use this file except in compliance
  8.  * with the License.  You may obtain a copy of the License at
  9.  *
  10.  *     http://www.apache.org/licenses/LICENSE-2.0
  11.  *
  12.  * Unless required by applicable law or agreed to in writing, software
  13.  * distributed under the License is distributed on an "AS IS" BASIS,
  14.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15.  * See the License for the specific language governing permissions and
  16.  * limitations under the License.
  17.  */
  18. package org.apache.hadoop.conf;
  19. import java.io.BufferedInputStream;
  20. import java.io.DataInput;
  21. import java.io.DataOutput;
  22. import java.io.File;
  23. import java.io.FileInputStream;
  24. import java.io.IOException;
  25. import java.io.InputStream;
  26. import java.io.InputStreamReader;
  27. import java.io.OutputStream;
  28. import java.io.Reader;
  29. import java.net.URL;
  30. import java.util.ArrayList;
  31. import java.util.Collection;
  32. import java.util.Enumeration;
  33. import java.util.HashMap;
  34. import java.util.HashSet;
  35. import java.util.Iterator;
  36. import java.util.List;
  37. import java.util.ListIterator;
  38. import java.util.Map;
  39. import java.util.Properties;
  40. import java.util.Set;
  41. import java.util.StringTokenizer;
  42. import java.util.WeakHashMap;
  43. import java.util.regex.Matcher;
  44. import java.util.regex.Pattern;
  45. import javax.xml.parsers.DocumentBuilder;
  46. import javax.xml.parsers.DocumentBuilderFactory;
  47. import javax.xml.parsers.ParserConfigurationException;
  48. import javax.xml.transform.Transformer;
  49. import javax.xml.transform.TransformerFactory;
  50. import javax.xml.transform.dom.DOMSource;
  51. import javax.xml.transform.stream.StreamResult;
  52. import org.apache.commons.logging.Log;
  53. import org.apache.commons.logging.LogFactory;
  54. import org.apache.hadoop.fs.FileSystem;
  55. import org.apache.hadoop.fs.Path;
  56. import org.apache.hadoop.io.Writable;
  57. import org.apache.hadoop.io.WritableUtils;
  58. import org.apache.hadoop.util.StringUtils;
  59. import org.w3c.dom.DOMException;
  60. import org.w3c.dom.Document;
  61. import org.w3c.dom.Element;
  62. import org.w3c.dom.Node;
  63. import org.w3c.dom.NodeList;
  64. import org.w3c.dom.Text;
  65. import org.xml.sax.SAXException;
  66. /** 
  67.  * Provides access to configuration parameters.
  68.  *
  69.  * <h4 id="Resources">Resources</h4>
  70.  *
  71.  * <p>Configurations are specified by resources. A resource contains a set of
  72.  * name/value pairs as XML data. Each resource is named by either a 
  73.  * <code>String</code> or by a {@link Path}. If named by a <code>String</code>, 
  74.  * then the classpath is examined for a file with that name.  If named by a 
  75.  * <code>Path</code>, then the local filesystem is examined directly, without 
  76.  * referring to the classpath.
  77.  *
  78.  * <p>Unless explicitly turned off, Hadoop by default specifies two 
  79.  * resources, loaded in-order from the classpath: <ol>
  80.  * <li><tt><a href="{@docRoot}/../core-default.html">core-default.xml</a>
  81.  * </tt>: Read-only defaults for hadoop.</li>
  82.  * <li><tt>core-site.xml</tt>: Site-specific configuration for a given hadoop
  83.  * installation.</li>
  84.  * </ol>
  85.  * Applications may add additional resources, which are loaded
  86.  * subsequent to these resources in the order they are added.
  87.  * 
  88.  * <h4 id="FinalParams">Final Parameters</h4>
  89.  *
  90.  * <p>Configuration parameters may be declared <i>final</i>. 
  91.  * Once a resource declares a value final, no subsequently-loaded 
  92.  * resource can alter that value.  
  93.  * For example, one might define a final parameter with:
  94.  * <tt><pre>
  95.  *  &lt;property&gt;
  96.  *    &lt;name&gt;dfs.client.buffer.dir&lt;/name&gt;
  97.  *    &lt;value&gt;/tmp/hadoop/dfs/client&lt;/value&gt;
  98.  *    <b>&lt;final&gt;true&lt;/final&gt;</b>
  99.  *  &lt;/property&gt;</pre></tt>
  100.  *
  101.  * Administrators typically define parameters as final in 
  102.  * <tt>core-site.xml</tt> for values that user applications may not alter.
  103.  *
  104.  * <h4 id="VariableExpansion">Variable Expansion</h4>
  105.  *
  106.  * <p>Value strings are first processed for <i>variable expansion</i>. The
  107.  * available properties are:<ol>
  108.  * <li>Other properties defined in this Configuration; and, if a name is
  109.  * undefined here,</li>
  110.  * <li>Properties in {@link System#getProperties()}.</li>
  111.  * </ol>
  112.  *
  113.  * <p>For example, if a configuration resource contains the following property
  114.  * definitions: 
  115.  * <tt><pre>
  116.  *  &lt;property&gt;
  117.  *    &lt;name&gt;basedir&lt;/name&gt;
  118.  *    &lt;value&gt;/user/${<i>user.name</i>}&lt;/value&gt;
  119.  *  &lt;/property&gt;
  120.  *  
  121.  *  &lt;property&gt;
  122.  *    &lt;name&gt;tempdir&lt;/name&gt;
  123.  *    &lt;value&gt;${<i>basedir</i>}/tmp&lt;/value&gt;
  124.  *  &lt;/property&gt;</pre></tt>
  125.  *
  126.  * When <tt>conf.get("tempdir")</tt> is called, then <tt>${<i>basedir</i>}</tt>
  127.  * will be resolved to another property in this Configuration, while
  128.  * <tt>${<i>user.name</i>}</tt> would then ordinarily be resolved to the value
  129.  * of the System property with that name.
  130.  */
  131. public class Configuration implements Iterable<Map.Entry<String,String>>,
  132.                                       Writable {
  133.   private static final Log LOG =
  134.     LogFactory.getLog(Configuration.class);
  135.   private boolean quietmode = true;
  136.   
  137.   /**
  138.    * List of configuration resources.
  139.    */
  140.   private ArrayList<Object> resources = new ArrayList<Object>();
  141.   /**
  142.    * List of configuration parameters marked <b>final</b>. 
  143.    */
  144.   private Set<String> finalParameters = new HashSet<String>();
  145.   
  146.   private boolean loadDefaults = true;
  147.   
  148.   /**
  149.    * Configurtion objects
  150.    */
  151.   private static final WeakHashMap<Configuration,Object> REGISTRY = 
  152.     new WeakHashMap<Configuration,Object>();
  153.   
  154.   /**
  155.    * List of default Resources. Resources are loaded in the order of the list 
  156.    * entries
  157.    */
  158.   private static final ArrayList<String> defaultResources = 
  159.     new ArrayList<String>();
  160.   
  161.   static{
  162.     //print deprecation warning if hadoop-site.xml is found in classpath
  163.     ClassLoader cL = Thread.currentThread().getContextClassLoader();
  164.     if (cL == null) {
  165.       cL = Configuration.class.getClassLoader();
  166.     }
  167.     if(cL.getResource("hadoop-site.xml")!=null) {
  168.       LOG.warn("DEPRECATED: hadoop-site.xml found in the classpath. " +
  169.           "Usage of hadoop-site.xml is deprecated. Instead use core-site.xml, "
  170.           + "mapred-site.xml and hdfs-site.xml to override properties of " +
  171.           "core-default.xml, mapred-default.xml and hdfs-default.xml " +
  172.           "respectively");
  173.     }
  174.     addDefaultResource("core-default.xml");
  175.     addDefaultResource("core-site.xml");
  176.   }
  177.   
  178.   private Properties properties;
  179.   private Properties overlay;
  180.   private ClassLoader classLoader;
  181.   {
  182.     classLoader = Thread.currentThread().getContextClassLoader();
  183.     if (classLoader == null) {
  184.       classLoader = Configuration.class.getClassLoader();
  185.     }
  186.   }
  187.   
  188.   /** A new configuration. */
  189.   public Configuration() {
  190.     this(true);
  191.   }
  192.   /** A new configuration where the behavior of reading from the default 
  193.    * resources can be turned off.
  194.    * 
  195.    * If the parameter {@code loadDefaults} is false, the new instance
  196.    * will not load resources from the default files. 
  197.    * @param loadDefaults specifies whether to load from the default files
  198.    */
  199.   public Configuration(boolean loadDefaults) {
  200.     this.loadDefaults = loadDefaults;
  201.     if (LOG.isDebugEnabled()) {
  202.       LOG.debug(StringUtils.stringifyException(new IOException("config()")));
  203.     }
  204.     synchronized(Configuration.class) {
  205.       REGISTRY.put(this, null);
  206.     }
  207.   }
  208.   
  209.   /** 
  210.    * A new configuration with the same settings cloned from another.
  211.    * 
  212.    * @param other the configuration from which to clone settings.
  213.    */
  214.   @SuppressWarnings("unchecked")
  215.   public Configuration(Configuration other) {
  216.     if (LOG.isDebugEnabled()) {
  217.       LOG.debug(StringUtils.stringifyException
  218.                 (new IOException("config(config)")));
  219.     }
  220.    
  221.    this.resources = (ArrayList)other.resources.clone();
  222.    synchronized(other) {
  223.      if (other.properties != null) {
  224.        this.properties = (Properties)other.properties.clone();
  225.      }
  226.      if (other.overlay!=null) {
  227.        this.overlay = (Properties)other.overlay.clone();
  228.      }
  229.    }
  230.    
  231.     this.finalParameters = new HashSet<String>(other.finalParameters);
  232.     synchronized(Configuration.class) {
  233.       REGISTRY.put(this, null);
  234.     }
  235.   }
  236.   
  237.   /**
  238.    * Add a default resource. Resources are loaded in the order of the resources 
  239.    * added.
  240.    * @param name file name. File should be present in the classpath.
  241.    */
  242.   public static synchronized void addDefaultResource(String name) {
  243.     if(!defaultResources.contains(name)) {
  244.       defaultResources.add(name);
  245.       for(Configuration conf : REGISTRY.keySet()) {
  246.         if(conf.loadDefaults) {
  247.           conf.reloadConfiguration();
  248.         }
  249.       }
  250.     }
  251.   }
  252.   /**
  253.    * Add a configuration resource. 
  254.    * 
  255.    * The properties of this resource will override properties of previously 
  256.    * added resources, unless they were marked <a href="#Final">final</a>. 
  257.    * 
  258.    * @param name resource to be added, the classpath is examined for a file 
  259.    *             with that name.
  260.    */
  261.   public void addResource(String name) {
  262.     addResourceObject(name);
  263.   }
  264.   /**
  265.    * Add a configuration resource. 
  266.    * 
  267.    * The properties of this resource will override properties of previously 
  268.    * added resources, unless they were marked <a href="#Final">final</a>. 
  269.    * 
  270.    * @param url url of the resource to be added, the local filesystem is 
  271.    *            examined directly to find the resource, without referring to 
  272.    *            the classpath.
  273.    */
  274.   public void addResource(URL url) {
  275.     addResourceObject(url);
  276.   }
  277.   /**
  278.    * Add a configuration resource. 
  279.    * 
  280.    * The properties of this resource will override properties of previously 
  281.    * added resources, unless they were marked <a href="#Final">final</a>. 
  282.    * 
  283.    * @param file file-path of resource to be added, the local filesystem is
  284.    *             examined directly to find the resource, without referring to 
  285.    *             the classpath.
  286.    */
  287.   public void addResource(Path file) {
  288.     addResourceObject(file);
  289.   }
  290.   /**
  291.    * Add a configuration resource. 
  292.    * 
  293.    * The properties of this resource will override properties of previously 
  294.    * added resources, unless they were marked <a href="#Final">final</a>. 
  295.    * 
  296.    * @param in InputStream to deserialize the object from. 
  297.    */
  298.   public void addResource(InputStream in) {
  299.     addResourceObject(in);
  300.   }
  301.   
  302.   
  303.   /**
  304.    * Reload configuration from previously added resources.
  305.    *
  306.    * This method will clear all the configuration read from the added 
  307.    * resources, and final parameters. This will make the resources to 
  308.    * be read again before accessing the values. Values that are added
  309.    * via set methods will overlay values read from the resources.
  310.    */
  311.   public synchronized void reloadConfiguration() {
  312.     properties = null;                            // trigger reload
  313.     finalParameters.clear();                      // clear site-limits
  314.   }
  315.   
  316.   private synchronized void addResourceObject(Object resource) {
  317.     resources.add(resource);                      // add to resources
  318.     reloadConfiguration();
  319.   }
  320.   
  321.   private static Pattern varPat = Pattern.compile("\$\{[^\}\$u0020]+\}");
  322.   private static int MAX_SUBST = 20;
  323.   private String substituteVars(String expr) {
  324.     if (expr == null) {
  325.       return null;
  326.     }
  327.     Matcher match = varPat.matcher("");
  328.     String eval = expr;
  329.     for(int s=0; s<MAX_SUBST; s++) {
  330.       match.reset(eval);
  331.       if (!match.find()) {
  332.         return eval;
  333.       }
  334.       String var = match.group();
  335.       var = var.substring(2, var.length()-1); // remove ${ .. }
  336.       String val = null;
  337.       try {
  338.         val = System.getProperty(var);
  339.       } catch(SecurityException se) {
  340.         LOG.warn("Unexpected SecurityException in Configuration", se);
  341.       }
  342.       if (val == null) {
  343.         val = getRaw(var);
  344.       }
  345.       if (val == null) {
  346.         return eval; // return literal ${var}: var is unbound
  347.       }
  348.       // substitute
  349.       eval = eval.substring(0, match.start())+val+eval.substring(match.end());
  350.     }
  351.     throw new IllegalStateException("Variable substitution depth too large: " 
  352.                                     + MAX_SUBST + " " + expr);
  353.   }
  354.   
  355.   /**
  356.    * Get the value of the <code>name</code> property, <code>null</code> if
  357.    * no such property exists.
  358.    * 
  359.    * Values are processed for <a href="#VariableExpansion">variable expansion</a> 
  360.    * before being returned. 
  361.    * 
  362.    * @param name the property name.
  363.    * @return the value of the <code>name</code> property, 
  364.    *         or null if no such property exists.
  365.    */
  366.   public String get(String name) {
  367.     return substituteVars(getProps().getProperty(name));
  368.   }
  369.   /**
  370.    * Get the value of the <code>name</code> property, without doing
  371.    * <a href="#VariableExpansion">variable expansion</a>.
  372.    * 
  373.    * @param name the property name.
  374.    * @return the value of the <code>name</code> property, 
  375.    *         or null if no such property exists.
  376.    */
  377.   public String getRaw(String name) {
  378.     return getProps().getProperty(name);
  379.   }
  380.   /** 
  381.    * Set the <code>value</code> of the <code>name</code> property.
  382.    * 
  383.    * @param name property name.
  384.    * @param value property value.
  385.    */
  386.   public void set(String name, String value) {
  387.     getOverlay().setProperty(name, value);
  388.     getProps().setProperty(name, value);
  389.   }
  390.   
  391.   /**
  392.    * Sets a property if it is currently unset.
  393.    * @param name the property name
  394.    * @param value the new value
  395.    */
  396.   public void setIfUnset(String name, String value) {
  397.     if (get(name) == null) {
  398.       set(name, value);
  399.     }
  400.   }
  401.   
  402.   private synchronized Properties getOverlay() {
  403.     if (overlay==null){
  404.       overlay=new Properties();
  405.     }
  406.     return overlay;
  407.   }
  408.   /** 
  409.    * Get the value of the <code>name</code> property. If no such property 
  410.    * exists, then <code>defaultValue</code> is returned.
  411.    * 
  412.    * @param name property name.
  413.    * @param defaultValue default value.
  414.    * @return property value, or <code>defaultValue</code> if the property 
  415.    *         doesn't exist.                    
  416.    */
  417.   public String get(String name, String defaultValue) {
  418.     return substituteVars(getProps().getProperty(name, defaultValue));
  419.   }
  420.     
  421.   /** 
  422.    * Get the value of the <code>name</code> property as an <code>int</code>.
  423.    *   
  424.    * If no such property exists, or if the specified value is not a valid
  425.    * <code>int</code>, then <code>defaultValue</code> is returned.
  426.    * 
  427.    * @param name property name.
  428.    * @param defaultValue default value.
  429.    * @return property value as an <code>int</code>, 
  430.    *         or <code>defaultValue</code>. 
  431.    */
  432.   public int getInt(String name, int defaultValue) {
  433.     String valueString = get(name);
  434.     if (valueString == null)
  435.       return defaultValue;
  436.     try {
  437.       String hexString = getHexDigits(valueString);
  438.       if (hexString != null) {
  439.         return Integer.parseInt(hexString, 16);
  440.       }
  441.       return Integer.parseInt(valueString);
  442.     } catch (NumberFormatException e) {
  443.       return defaultValue;
  444.     }
  445.   }
  446.   /** 
  447.    * Set the value of the <code>name</code> property to an <code>int</code>.
  448.    * 
  449.    * @param name property name.
  450.    * @param value <code>int</code> value of the property.
  451.    */
  452.   public void setInt(String name, int value) {
  453.     set(name, Integer.toString(value));
  454.   }
  455.   /** 
  456.    * Get the value of the <code>name</code> property as a <code>long</code>.  
  457.    * If no such property is specified, or if the specified value is not a valid
  458.    * <code>long</code>, then <code>defaultValue</code> is returned.
  459.    * 
  460.    * @param name property name.
  461.    * @param defaultValue default value.
  462.    * @return property value as a <code>long</code>, 
  463.    *         or <code>defaultValue</code>. 
  464.    */
  465.   public long getLong(String name, long defaultValue) {
  466.     String valueString = get(name);
  467.     if (valueString == null)
  468.       return defaultValue;
  469.     try {
  470.       String hexString = getHexDigits(valueString);
  471.       if (hexString != null) {
  472.         return Long.parseLong(hexString, 16);
  473.       }
  474.       return Long.parseLong(valueString);
  475.     } catch (NumberFormatException e) {
  476.       return defaultValue;
  477.     }
  478.   }
  479.   private String getHexDigits(String value) {
  480.     boolean negative = false;
  481.     String str = value;
  482.     String hexString = null;
  483.     if (value.startsWith("-")) {
  484.       negative = true;
  485.       str = value.substring(1);
  486.     }
  487.     if (str.startsWith("0x") || str.startsWith("0X")) {
  488.       hexString = str.substring(2);
  489.       if (negative) {
  490.         hexString = "-" + hexString;
  491.       }
  492.       return hexString;
  493.     }
  494.     return null;
  495.   }
  496.   
  497.   /** 
  498.    * Set the value of the <code>name</code> property to a <code>long</code>.
  499.    * 
  500.    * @param name property name.
  501.    * @param value <code>long</code> value of the property.
  502.    */
  503.   public void setLong(String name, long value) {
  504.     set(name, Long.toString(value));
  505.   }
  506.   /** 
  507.    * Get the value of the <code>name</code> property as a <code>float</code>.  
  508.    * If no such property is specified, or if the specified value is not a valid
  509.    * <code>float</code>, then <code>defaultValue</code> is returned.
  510.    * 
  511.    * @param name property name.
  512.    * @param defaultValue default value.
  513.    * @return property value as a <code>float</code>, 
  514.    *         or <code>defaultValue</code>. 
  515.    */
  516.   public float getFloat(String name, float defaultValue) {
  517.     String valueString = get(name);
  518.     if (valueString == null)
  519.       return defaultValue;
  520.     try {
  521.       return Float.parseFloat(valueString);
  522.     } catch (NumberFormatException e) {
  523.       return defaultValue;
  524.     }
  525.   }
  526.   /**
  527.    * Set the value of the <code>name</code> property to a <code>float</code>.
  528.    * 
  529.    * @param name property name.
  530.    * @param value property value.
  531.    */
  532.   public void setFloat(String name, float value) {
  533.     set(name,Float.toString(value));
  534.   }
  535.  
  536.   /** 
  537.    * Get the value of the <code>name</code> property as a <code>boolean</code>.  
  538.    * If no such property is specified, or if the specified value is not a valid
  539.    * <code>boolean</code>, then <code>defaultValue</code> is returned.
  540.    * 
  541.    * @param name property name.
  542.    * @param defaultValue default value.
  543.    * @return property value as a <code>boolean</code>, 
  544.    *         or <code>defaultValue</code>. 
  545.    */
  546.   public boolean getBoolean(String name, boolean defaultValue) {
  547.     String valueString = get(name);
  548.     if ("true".equals(valueString))
  549.       return true;
  550.     else if ("false".equals(valueString))
  551.       return false;
  552.     else return defaultValue;
  553.   }
  554.   /** 
  555.    * Set the value of the <code>name</code> property to a <code>boolean</code>.
  556.    * 
  557.    * @param name property name.
  558.    * @param value <code>boolean</code> value of the property.
  559.    */
  560.   public void setBoolean(String name, boolean value) {
  561.     set(name, Boolean.toString(value));
  562.   }
  563.   /**
  564.    * Set the given property, if it is currently unset.
  565.    * @param name property name
  566.    * @param value new value
  567.    */
  568.   public void setBooleanIfUnset(String name, boolean value) {
  569.     setIfUnset(name, Boolean.toString(value));
  570.   }
  571.   /**
  572.    * A class that represents a set of positive integer ranges. It parses 
  573.    * strings of the form: "2-3,5,7-" where ranges are separated by comma and 
  574.    * the lower/upper bounds are separated by dash. Either the lower or upper 
  575.    * bound may be omitted meaning all values up to or over. So the string 
  576.    * above means 2, 3, 5, and 7, 8, 9, ...
  577.    */
  578.   public static class IntegerRanges {
  579.     private static class Range {
  580.       int start;
  581.       int end;
  582.     }
  583.     List<Range> ranges = new ArrayList<Range>();
  584.     
  585.     public IntegerRanges() {
  586.     }
  587.     
  588.     public IntegerRanges(String newValue) {
  589.       StringTokenizer itr = new StringTokenizer(newValue, ",");
  590.       while (itr.hasMoreTokens()) {
  591.         String rng = itr.nextToken().trim();
  592.         String[] parts = rng.split("-", 3);
  593.         if (parts.length < 1 || parts.length > 2) {
  594.           throw new IllegalArgumentException("integer range badly formed: " + 
  595.                                              rng);
  596.         }
  597.         Range r = new Range();
  598.         r.start = convertToInt(parts[0], 0);
  599.         if (parts.length == 2) {
  600.           r.end = convertToInt(parts[1], Integer.MAX_VALUE);
  601.         } else {
  602.           r.end = r.start;
  603.         }
  604.         if (r.start > r.end) {
  605.           throw new IllegalArgumentException("IntegerRange from " + r.start + 
  606.                                              " to " + r.end + " is invalid");
  607.         }
  608.         ranges.add(r);
  609.       }
  610.     }
  611.     /**
  612.      * Convert a string to an int treating empty strings as the default value.
  613.      * @param value the string value
  614.      * @param defaultValue the value for if the string is empty
  615.      * @return the desired integer
  616.      */
  617.     private static int convertToInt(String value, int defaultValue) {
  618.       String trim = value.trim();
  619.       if (trim.length() == 0) {
  620.         return defaultValue;
  621.       }
  622.       return Integer.parseInt(trim);
  623.     }
  624.     /**
  625.      * Is the given value in the set of ranges
  626.      * @param value the value to check
  627.      * @return is the value in the ranges?
  628.      */
  629.     public boolean isIncluded(int value) {
  630.       for(Range r: ranges) {
  631.         if (r.start <= value && value <= r.end) {
  632.           return true;
  633.         }
  634.       }
  635.       return false;
  636.     }
  637.     
  638.     @Override
  639.     public String toString() {
  640.       StringBuffer result = new StringBuffer();
  641.       boolean first = true;
  642.       for(Range r: ranges) {
  643.         if (first) {
  644.           first = false;
  645.         } else {
  646.           result.append(',');
  647.         }
  648.         result.append(r.start);
  649.         result.append('-');
  650.         result.append(r.end);
  651.       }
  652.       return result.toString();
  653.     }
  654.   }
  655.   /**
  656.    * Parse the given attribute as a set of integer ranges
  657.    * @param name the attribute name
  658.    * @param defaultValue the default value if it is not set
  659.    * @return a new set of ranges from the configured value
  660.    */
  661.   public IntegerRanges getRange(String name, String defaultValue) {
  662.     return new IntegerRanges(get(name, defaultValue));
  663.   }
  664.   /** 
  665.    * Get the comma delimited values of the <code>name</code> property as 
  666.    * a collection of <code>String</code>s.  
  667.    * If no such property is specified then empty collection is returned.
  668.    * <p>
  669.    * This is an optimized version of {@link #getStrings(String)}
  670.    * 
  671.    * @param name property name.
  672.    * @return property value as a collection of <code>String</code>s. 
  673.    */
  674.   public Collection<String> getStringCollection(String name) {
  675.     String valueString = get(name);
  676.     return StringUtils.getStringCollection(valueString);
  677.   }
  678.   /** 
  679.    * Get the comma delimited values of the <code>name</code> property as 
  680.    * an array of <code>String</code>s.  
  681.    * If no such property is specified then <code>null</code> is returned.
  682.    * 
  683.    * @param name property name.
  684.    * @return property value as an array of <code>String</code>s, 
  685.    *         or <code>null</code>. 
  686.    */
  687.   public String[] getStrings(String name) {
  688.     String valueString = get(name);
  689.     return StringUtils.getStrings(valueString);
  690.   }
  691.   /** 
  692.    * Get the comma delimited values of the <code>name</code> property as 
  693.    * an array of <code>String</code>s.  
  694.    * If no such property is specified then default value is returned.
  695.    * 
  696.    * @param name property name.
  697.    * @param defaultValue The default value
  698.    * @return property value as an array of <code>String</code>s, 
  699.    *         or default value. 
  700.    */
  701.   public String[] getStrings(String name, String... defaultValue) {
  702.     String valueString = get(name);
  703.     if (valueString == null) {
  704.       return defaultValue;
  705.     } else {
  706.       return StringUtils.getStrings(valueString);
  707.     }
  708.   }
  709.   /** 
  710.    * Set the array of string values for the <code>name</code> property as 
  711.    * as comma delimited values.  
  712.    * 
  713.    * @param name property name.
  714.    * @param values The values
  715.    */
  716.   public void setStrings(String name, String... values) {
  717.     set(name, StringUtils.arrayToString(values));
  718.   }
  719.  
  720.   /**
  721.    * Load a class by name.
  722.    * 
  723.    * @param name the class name.
  724.    * @return the class object.
  725.    * @throws ClassNotFoundException if the class is not found.
  726.    */
  727.   public Class<?> getClassByName(String name) throws ClassNotFoundException {
  728.     return Class.forName(name, true, classLoader);
  729.   }
  730.   /** 
  731.    * Get the value of the <code>name</code> property
  732.    * as an array of <code>Class</code>.
  733.    * The value of the property specifies a list of comma separated class names.  
  734.    * If no such property is specified, then <code>defaultValue</code> is 
  735.    * returned.
  736.    * 
  737.    * @param name the property name.
  738.    * @param defaultValue default value.
  739.    * @return property value as a <code>Class[]</code>, 
  740.    *         or <code>defaultValue</code>. 
  741.    */
  742.   public Class<?>[] getClasses(String name, Class<?> ... defaultValue) {
  743.     String[] classnames = getStrings(name);
  744.     if (classnames == null)
  745.       return defaultValue;
  746.     try {
  747.       Class<?>[] classes = new Class<?>[classnames.length];
  748.       for(int i = 0; i < classnames.length; i++) {
  749.         classes[i] = getClassByName(classnames[i]);
  750.       }
  751.       return classes;
  752.     } catch (ClassNotFoundException e) {
  753.       throw new RuntimeException(e);
  754.     }
  755.   }
  756.   /** 
  757.    * Get the value of the <code>name</code> property as a <code>Class</code>.  
  758.    * If no such property is specified, then <code>defaultValue</code> is 
  759.    * returned.
  760.    * 
  761.    * @param name the class name.
  762.    * @param defaultValue default value.
  763.    * @return property value as a <code>Class</code>, 
  764.    *         or <code>defaultValue</code>. 
  765.    */
  766.   public Class<?> getClass(String name, Class<?> defaultValue) {
  767.     String valueString = get(name);
  768.     if (valueString == null)
  769.       return defaultValue;
  770.     try {
  771.       return getClassByName(valueString);
  772.     } catch (ClassNotFoundException e) {
  773.       throw new RuntimeException(e);
  774.     }
  775.   }
  776.   /** 
  777.    * Get the value of the <code>name</code> property as a <code>Class</code>
  778.    * implementing the interface specified by <code>xface</code>.
  779.    *   
  780.    * If no such property is specified, then <code>defaultValue</code> is 
  781.    * returned.
  782.    * 
  783.    * An exception is thrown if the returned class does not implement the named
  784.    * interface. 
  785.    * 
  786.    * @param name the class name.
  787.    * @param defaultValue default value.
  788.    * @param xface the interface implemented by the named class.
  789.    * @return property value as a <code>Class</code>, 
  790.    *         or <code>defaultValue</code>.
  791.    */
  792.   public <U> Class<? extends U> getClass(String name, 
  793.                                          Class<? extends U> defaultValue, 
  794.                                          Class<U> xface) {
  795.     try {
  796.       Class<?> theClass = getClass(name, defaultValue);
  797.       if (theClass != null && !xface.isAssignableFrom(theClass))
  798.         throw new RuntimeException(theClass+" not "+xface.getName());
  799.       else if (theClass != null)
  800.         return theClass.asSubclass(xface);
  801.       else
  802.         return null;
  803.     } catch (Exception e) {
  804.       throw new RuntimeException(e);
  805.     }
  806.   }
  807.   /** 
  808.    * Set the value of the <code>name</code> property to the name of a 
  809.    * <code>theClass</code> implementing the given interface <code>xface</code>.
  810.    * 
  811.    * An exception is thrown if <code>theClass</code> does not implement the 
  812.    * interface <code>xface</code>. 
  813.    * 
  814.    * @param name property name.
  815.    * @param theClass property value.
  816.    * @param xface the interface implemented by the named class.
  817.    */
  818.   public void setClass(String name, Class<?> theClass, Class<?> xface) {
  819.     if (!xface.isAssignableFrom(theClass))
  820.       throw new RuntimeException(theClass+" not "+xface.getName());
  821.     set(name, theClass.getName());
  822.   }
  823.   /** 
  824.    * Get a local file under a directory named by <i>dirsProp</i> with
  825.    * the given <i>path</i>.  If <i>dirsProp</i> contains multiple directories,
  826.    * then one is chosen based on <i>path</i>'s hash code.  If the selected
  827.    * directory does not exist, an attempt is made to create it.
  828.    * 
  829.    * @param dirsProp directory in which to locate the file.
  830.    * @param path file-path.
  831.    * @return local file under the directory with the given path.
  832.    */
  833.   public Path getLocalPath(String dirsProp, String path)
  834.     throws IOException {
  835.     String[] dirs = getStrings(dirsProp);
  836.     int hashCode = path.hashCode();
  837.     FileSystem fs = FileSystem.getLocal(this);
  838.     for (int i = 0; i < dirs.length; i++) {  // try each local dir
  839.       int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
  840.       Path file = new Path(dirs[index], path);
  841.       Path dir = file.getParent();
  842.       if (fs.mkdirs(dir) || fs.exists(dir)) {
  843.         return file;
  844.       }
  845.     }
  846.     LOG.warn("Could not make " + path + 
  847.              " in local directories from " + dirsProp);
  848.     for(int i=0; i < dirs.length; i++) {
  849.       int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
  850.       LOG.warn(dirsProp + "[" + index + "]=" + dirs[index]);
  851.     }
  852.     throw new IOException("No valid local directories in property: "+dirsProp);
  853.   }
  854.   /** 
  855.    * Get a local file name under a directory named in <i>dirsProp</i> with
  856.    * the given <i>path</i>.  If <i>dirsProp</i> contains multiple directories,
  857.    * then one is chosen based on <i>path</i>'s hash code.  If the selected
  858.    * directory does not exist, an attempt is made to create it.
  859.    * 
  860.    * @param dirsProp directory in which to locate the file.
  861.    * @param path file-path.
  862.    * @return local file under the directory with the given path.
  863.    */
  864.   public File getFile(String dirsProp, String path)
  865.     throws IOException {
  866.     String[] dirs = getStrings(dirsProp);
  867.     int hashCode = path.hashCode();
  868.     for (int i = 0; i < dirs.length; i++) {  // try each local dir
  869.       int index = (hashCode+i & Integer.MAX_VALUE) % dirs.length;
  870.       File file = new File(dirs[index], path);
  871.       File dir = file.getParentFile();
  872.       if (dir.exists() || dir.mkdirs()) {
  873.         return file;
  874.       }
  875.     }
  876.     throw new IOException("No valid local directories in property: "+dirsProp);
  877.   }
  878.   /** 
  879.    * Get the {@link URL} for the named resource.
  880.    * 
  881.    * @param name resource name.
  882.    * @return the url for the named resource.
  883.    */
  884.   public URL getResource(String name) {
  885.     return classLoader.getResource(name);
  886.   }
  887.   
  888.   /** 
  889.    * Get an input stream attached to the configuration resource with the
  890.    * given <code>name</code>.
  891.    * 
  892.    * @param name configuration resource name.
  893.    * @return an input stream attached to the resource.
  894.    */
  895.   public InputStream getConfResourceAsInputStream(String name) {
  896.     try {
  897.       URL url= getResource(name);
  898.       if (url == null) {
  899.         LOG.info(name + " not found");
  900.         return null;
  901.       } else {
  902.         LOG.info("found resource " + name + " at " + url);
  903.       }
  904.       return url.openStream();
  905.     } catch (Exception e) {
  906.       return null;
  907.     }
  908.   }
  909.   /** 
  910.    * Get a {@link Reader} attached to the configuration resource with the
  911.    * given <code>name</code>.
  912.    * 
  913.    * @param name configuration resource name.
  914.    * @return a reader attached to the resource.
  915.    */
  916.   public Reader getConfResourceAsReader(String name) {
  917.     try {
  918.       URL url= getResource(name);
  919.       if (url == null) {
  920.         LOG.info(name + " not found");
  921.         return null;
  922.       } else {
  923.         LOG.info("found resource " + name + " at " + url);
  924.       }
  925.       return new InputStreamReader(url.openStream());
  926.     } catch (Exception e) {
  927.       return null;
  928.     }
  929.   }
  930.   private synchronized Properties getProps() {
  931.     if (properties == null) {
  932.       properties = new Properties();
  933.       loadResources(properties, resources, quietmode);
  934.       if (overlay!= null)
  935.         properties.putAll(overlay);
  936.     }
  937.     return properties;
  938.   }
  939.   /**
  940.    * Return the number of keys in the configuration.
  941.    *
  942.    * @return number of keys in the configuration.
  943.    */
  944.   public int size() {
  945.     return getProps().size();
  946.   }
  947.   /**
  948.    * Clears all keys from the configuration.
  949.    */
  950.   public void clear() {
  951.     getProps().clear();
  952.     getOverlay().clear();
  953.   }
  954.   /**
  955.    * Get an {@link Iterator} to go through the list of <code>String</code> 
  956.    * key-value pairs in the configuration.
  957.    * 
  958.    * @return an iterator over the entries.
  959.    */
  960.   public Iterator<Map.Entry<String, String>> iterator() {
  961.     // Get a copy of just the string to string pairs. After the old object
  962.     // methods that allow non-strings to be put into configurations are removed,
  963.     // we could replace properties with a Map<String,String> and get rid of this
  964.     // code.
  965.     Map<String,String> result = new HashMap<String,String>();
  966.     for(Map.Entry<Object,Object> item: getProps().entrySet()) {
  967.       if (item.getKey() instanceof String && 
  968.           item.getValue() instanceof String) {
  969.         result.put((String) item.getKey(), (String) item.getValue());
  970.       }
  971.     }
  972.     return result.entrySet().iterator();
  973.   }
  974.   private void loadResources(Properties properties,
  975.                              ArrayList resources,
  976.                              boolean quiet) {
  977.     if(loadDefaults) {
  978.       for (String resource : defaultResources) {
  979.         loadResource(properties, resource, quiet);
  980.       }
  981.     
  982.       //support the hadoop-site.xml as a deprecated case
  983.       if(getResource("hadoop-site.xml")!=null) {
  984.         loadResource(properties, "hadoop-site.xml", quiet);
  985.       }
  986.     }
  987.     
  988.     for (Object resource : resources) {
  989.       loadResource(properties, resource, quiet);
  990.     }
  991.   }
  992.   private void loadResource(Properties properties, Object name, boolean quiet) {
  993.     try {
  994.       DocumentBuilderFactory docBuilderFactory 
  995.         = DocumentBuilderFactory.newInstance();
  996.       //ignore all comments inside the xml file
  997.       docBuilderFactory.setIgnoringComments(true);
  998.       //allow includes in the xml file
  999.       docBuilderFactory.setNamespaceAware(true);
  1000.       try {
  1001.           docBuilderFactory.setXIncludeAware(true);
  1002.       } catch (UnsupportedOperationException e) {
  1003.         LOG.error("Failed to set setXIncludeAware(true) for parser "
  1004.                 + docBuilderFactory
  1005.                 + ":" + e,
  1006.                 e);
  1007.       }
  1008.       DocumentBuilder builder = docBuilderFactory.newDocumentBuilder();
  1009.       Document doc = null;
  1010.       Element root = null;
  1011.       if (name instanceof URL) {                  // an URL resource
  1012.         URL url = (URL)name;
  1013.         if (url != null) {
  1014.           if (!quiet) {
  1015.             LOG.info("parsing " + url);
  1016.           }
  1017.           doc = builder.parse(url.toString());
  1018.         }
  1019.       } else if (name instanceof String) {        // a CLASSPATH resource
  1020.         URL url = getResource((String)name);
  1021.         if (url != null) {
  1022.           if (!quiet) {
  1023.             LOG.info("parsing " + url);
  1024.           }
  1025.           doc = builder.parse(url.toString());
  1026.         }
  1027.       } else if (name instanceof Path) {          // a file resource
  1028.         // Can't use FileSystem API or we get an infinite loop
  1029.         // since FileSystem uses Configuration API.  Use java.io.File instead.
  1030.         File file = new File(((Path)name).toUri().getPath())
  1031.           .getAbsoluteFile();
  1032.         if (file.exists()) {
  1033.           if (!quiet) {
  1034.             LOG.info("parsing " + file);
  1035.           }
  1036.           InputStream in = new BufferedInputStream(new FileInputStream(file));
  1037.           try {
  1038.             doc = builder.parse(in);
  1039.           } finally {
  1040.             in.close();
  1041.           }
  1042.         }
  1043.       } else if (name instanceof InputStream) {
  1044.         try {
  1045.           doc = builder.parse((InputStream)name);
  1046.         } finally {
  1047.           ((InputStream)name).close();
  1048.         }
  1049.       } else if (name instanceof Element) {
  1050.         root = (Element)name;
  1051.       }
  1052.       if (doc == null && root == null) {
  1053.         if (quiet)
  1054.           return;
  1055.         throw new RuntimeException(name + " not found");
  1056.       }
  1057.       if (root == null) {
  1058.         root = doc.getDocumentElement();
  1059.       }
  1060.       if (!"configuration".equals(root.getTagName()))
  1061.         LOG.fatal("bad conf file: top-level element not <configuration>");
  1062.       NodeList props = root.getChildNodes();
  1063.       for (int i = 0; i < props.getLength(); i++) {
  1064.         Node propNode = props.item(i);
  1065.         if (!(propNode instanceof Element))
  1066.           continue;
  1067.         Element prop = (Element)propNode;
  1068.         if ("configuration".equals(prop.getTagName())) {
  1069.           loadResource(properties, prop, quiet);
  1070.           continue;
  1071.         }
  1072.         if (!"property".equals(prop.getTagName()))
  1073.           LOG.warn("bad conf file: element not <property>");
  1074.         NodeList fields = prop.getChildNodes();
  1075.         String attr = null;
  1076.         String value = null;
  1077.         boolean finalParameter = false;
  1078.         for (int j = 0; j < fields.getLength(); j++) {
  1079.           Node fieldNode = fields.item(j);
  1080.           if (!(fieldNode instanceof Element))
  1081.             continue;
  1082.           Element field = (Element)fieldNode;
  1083.           if ("name".equals(field.getTagName()) && field.hasChildNodes())
  1084.             attr = ((Text)field.getFirstChild()).getData().trim();
  1085.           if ("value".equals(field.getTagName()) && field.hasChildNodes())
  1086.             value = ((Text)field.getFirstChild()).getData();
  1087.           if ("final".equals(field.getTagName()) && field.hasChildNodes())
  1088.             finalParameter = "true".equals(((Text)field.getFirstChild()).getData());
  1089.         }
  1090.         
  1091.         // Ignore this parameter if it has already been marked as 'final'
  1092.         if (attr != null && value != null) {
  1093.           if (!finalParameters.contains(attr)) {
  1094.             properties.setProperty(attr, value);
  1095.             if (finalParameter)
  1096.               finalParameters.add(attr);
  1097.           } else {
  1098.             LOG.warn(name+":a attempt to override final parameter: "+attr
  1099.                      +";  Ignoring.");
  1100.           }
  1101.         }
  1102.       }
  1103.         
  1104.     } catch (IOException e) {
  1105.       LOG.fatal("error parsing conf file: " + e);
  1106.       throw new RuntimeException(e);
  1107.     } catch (DOMException e) {
  1108.       LOG.fatal("error parsing conf file: " + e);
  1109.       throw new RuntimeException(e);
  1110.     } catch (SAXException e) {
  1111.       LOG.fatal("error parsing conf file: " + e);
  1112.       throw new RuntimeException(e);
  1113.     } catch (ParserConfigurationException e) {
  1114.       LOG.fatal("error parsing conf file: " + e);
  1115.       throw new RuntimeException(e);
  1116.     }
  1117.   }
  1118.   /** 
  1119.    * Write out the non-default properties in this configuration to the give
  1120.    * {@link OutputStream}.
  1121.    * 
  1122.    * @param out the output stream to write to.
  1123.    */
  1124.   public void writeXml(OutputStream out) throws IOException {
  1125.     Properties properties = getProps();
  1126.     try {
  1127.       Document doc =
  1128.         DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
  1129.       Element conf = doc.createElement("configuration");
  1130.       doc.appendChild(conf);
  1131.       conf.appendChild(doc.createTextNode("n"));
  1132.       for (Enumeration e = properties.keys(); e.hasMoreElements();) {
  1133.         String name = (String)e.nextElement();
  1134.         Object object = properties.get(name);
  1135.         String value = null;
  1136.         if (object instanceof String) {
  1137.           value = (String) object;
  1138.         }else {
  1139.           continue;
  1140.         }
  1141.         Element propNode = doc.createElement("property");
  1142.         conf.appendChild(propNode);
  1143.       
  1144.         Element nameNode = doc.createElement("name");
  1145.         nameNode.appendChild(doc.createTextNode(name));
  1146.         propNode.appendChild(nameNode);
  1147.       
  1148.         Element valueNode = doc.createElement("value");
  1149.         valueNode.appendChild(doc.createTextNode(value));
  1150.         propNode.appendChild(valueNode);
  1151.         conf.appendChild(doc.createTextNode("n"));
  1152.       }
  1153.     
  1154.       DOMSource source = new DOMSource(doc);
  1155.       StreamResult result = new StreamResult(out);
  1156.       TransformerFactory transFactory = TransformerFactory.newInstance();
  1157.       Transformer transformer = transFactory.newTransformer();
  1158.       transformer.transform(source, result);
  1159.     } catch (Exception e) {
  1160.       throw new RuntimeException(e);
  1161.     }
  1162.   }
  1163.   /**
  1164.    * Get the {@link ClassLoader} for this job.
  1165.    * 
  1166.    * @return the correct class loader.
  1167.    */
  1168.   public ClassLoader getClassLoader() {
  1169.     return classLoader;
  1170.   }
  1171.   
  1172.   /**
  1173.    * Set the class loader that will be used to load the various objects.
  1174.    * 
  1175.    * @param classLoader the new class loader.
  1176.    */
  1177.   public void setClassLoader(ClassLoader classLoader) {
  1178.     this.classLoader = classLoader;
  1179.   }
  1180.   
  1181.   @Override
  1182.   public String toString() {
  1183.     StringBuffer sb = new StringBuffer();
  1184.     sb.append("Configuration: ");
  1185.     if(loadDefaults) {
  1186.       toString(defaultResources, sb);
  1187.       if(resources.size()>0) {
  1188.         sb.append(", ");
  1189.       }
  1190.     }
  1191.     toString(resources, sb);
  1192.     return sb.toString();
  1193.   }
  1194.   private void toString(ArrayList resources, StringBuffer sb) {
  1195.     ListIterator i = resources.listIterator();
  1196.     while (i.hasNext()) {
  1197.       if (i.nextIndex() != 0) {
  1198.         sb.append(", ");
  1199.       }
  1200.       sb.append(i.next());
  1201.     }
  1202.   }
  1203.   /** 
  1204.    * Set the quietness-mode. 
  1205.    * 
  1206.    * In the quiet-mode, error and informational messages might not be logged.
  1207.    * 
  1208.    * @param quietmode <code>true</code> to set quiet-mode on, <code>false</code>
  1209.    *              to turn it off.
  1210.    */
  1211.   public synchronized void setQuietMode(boolean quietmode) {
  1212.     this.quietmode = quietmode;
  1213.   }
  1214.   /** For debugging.  List non-default properties to the terminal and exit. */
  1215.   public static void main(String[] args) throws Exception {
  1216.     new Configuration().writeXml(System.out);
  1217.   }
  1218.   @Override
  1219.   public void readFields(DataInput in) throws IOException {
  1220.     clear();
  1221.     int size = WritableUtils.readVInt(in);
  1222.     for(int i=0; i < size; ++i) {
  1223.       set(org.apache.hadoop.io.Text.readString(in), 
  1224.           org.apache.hadoop.io.Text.readString(in));
  1225.     }
  1226.   }
  1227.   //@Override
  1228.   public void write(DataOutput out) throws IOException {
  1229.     Properties props = getProps();
  1230.     WritableUtils.writeVInt(out, props.size());
  1231.     for(Map.Entry<Object, Object> item: props.entrySet()) {
  1232.       org.apache.hadoop.io.Text.writeString(out, (String) item.getKey());
  1233.       org.apache.hadoop.io.Text.writeString(out, (String) item.getValue());
  1234.     }
  1235.   }
  1236. }