Package org.apache.hadoop.conf

Class Configuration

java.lang.Object
org.apache.hadoop.conf.Configuration
All Implemented Interfaces:
Iterable<Map.Entry<String,String>>, Writable
Direct Known Subclasses:
JobConf, YarnConfiguration
@Public @Stable public class Configuration extends Object implements Iterable<Map.Entry<String,String>>, Writable
Provides access to configuration parameters.

Resources

Configurations are specified by resources. A resource contains a set of name/value pairs as XML data. Each resource is named by either a String or by a Path. If named by a String, then the classpath is examined for a file with that name. If named by a Path, then the local filesystem is examined directly, without referring to the classpath.

Unless explicitly turned off, Hadoop by default specifies two resources, loaded in-order from the classpath:

  1. core-default.xml: Read-only defaults for hadoop.
  2. core-site.xml: Site-specific configuration for a given hadoop installation.
Applications may add additional resources, which are loaded subsequent to these resources in the order they are added.

Final Parameters

Configuration parameters may be declared final. Once a resource declares a value final, no subsequently-loaded resource can alter that value. For example, one might define a final parameter with: 


  <property>
    <name>dfs.hosts.include</name>
    <value>/etc/hadoop/conf/hosts.include</value>
    <final>true</final>
  </property>
Administrators typically define parameters as final in core-site.xml for values that user applications may not alter.

Variable Expansion

Value strings are first processed for variable expansion. The available properties are:

  1. Other properties defined in this Configuration; and, if a name is undefined here,
  2. Environment variables in System.getenv() if a name starts with "env.", or
  3. Properties in System.getProperties().

For example, if a configuration resource contains the following property definitions: 


  <property>
    <name>basedir</name>
    <value>/user/${user.name}</value>
  </property>
  
  <property>
    <name>tempdir</name>
    <value>${basedir}/tmp</value>
  </property>

  <property>
    <name>otherdir</name>
    <value>${env.BASE_DIR}/other</value>
  </property>

When conf.get("tempdir") is called, then ${basedir} will be resolved to another property in this Configuration, while ${user.name} would then ordinarily be resolved to the value of the System property with that name.

When conf.get("otherdir") is called, then ${env.BASE_DIR} will be resolved to the value of the ${BASE_DIR} environment variable. It supports ${env.NAME:-default} and ${env.NAME-default} notations. The former is resolved to "default" if ${NAME} environment variable is undefined or its value is empty. The latter behaves the same way only if ${NAME} is undefined.

By default, warnings will be given to any deprecated configuration parameters and these are suppressible by configuring log4j.logger.org.apache.hadoop.conf.Configuration.deprecation in log4j.properties file.

Tags

Optionally we can tag related properties together by using tag attributes. System tags are defined by hadoop.tags.system property. Users can define there own custom tags in hadoop.tags.custom property.

For example, we can tag existing property as: 


  <property>
    <name>dfs.replication</name>
    <value>3</value>
    <tag>HDFS,REQUIRED</tag>
  </property>

  <property>
    <name>dfs.data.transfer.protection</name>
    <value>3</value>
    <tag>HDFS,SECURITY</tag>
  </property>

Properties marked with tags can be retrieved with conf .getAllPropertiesByTag("HDFS") or conf.getAllPropertiesByTags (Arrays.asList("YARN","SECURITY")).

  • Constructor Details

    • Configuration

      public Configuration()
      A new configuration.

    • Configuration

      public Configuration(boolean loadDefaults)
      A new configuration where the behavior of reading from the default resources can be turned off. If the parameter loadDefaults is false, the new instance will not load resources from the default files.
      Parameters:
      loadDefaults - specifies whether to load from the default files

    • Configuration

      public Configuration(Configuration other)
      A new configuration with the same settings cloned from another.
      Parameters:
      other - the configuration from which to clone settings.

  • Method Details

    • addDeprecations

      public static void addDeprecations(org.apache.hadoop.conf.Configuration.DeprecationDelta[] deltas)
      Adds a set of deprecated keys to the global deprecations. This method is lockless. It works by means of creating a new DeprecationContext based on the old one, and then atomically swapping in the new context. If someone else updated the context in between us reading the old context and swapping in the new one, we try again until we win the race.
      Parameters:
      deltas - The deprecations to add.

    • addDeprecation

      @Deprecated public static void addDeprecation(String key, String[] newKeys, String customMessage)
      Deprecated.
      use addDeprecation(String key, String newKey, String customMessage) instead
      Adds the deprecated key to the global deprecation map. It does not override any existing entries in the deprecation map. This is to be used only by the developers in order to add deprecation of keys, and attempts to call this method after loading resources once, would lead to UnsupportedOperationException If a key is deprecated in favor of multiple keys, they are all treated as aliases of each other, and setting any one of them resets all the others to the new value. If you have multiple deprecation entries to add, it is more efficient to use #addDeprecations(DeprecationDelta[] deltas) instead.
      Parameters:
      key - to be deprecated
      newKeys - list of keys that take up the values of deprecated key
      customMessage - depcrication message

    • addDeprecation

      public static void addDeprecation(String key, String newKey, String customMessage)
      Adds the deprecated key to the global deprecation map. It does not override any existing entries in the deprecation map. This is to be used only by the developers in order to add deprecation of keys, and attempts to call this method after loading resources once, would lead to UnsupportedOperationException If you have multiple deprecation entries to add, it is more efficient to use #addDeprecations(DeprecationDelta[] deltas) instead.
      Parameters:
      key - to be deprecated
      newKey - key that take up the values of deprecated key
      customMessage - deprecation message

    • addDeprecation

      @Deprecated public static void addDeprecation(String key, String[] newKeys)
      Deprecated.
      use addDeprecation(String key, String newKey) instead
      Adds the deprecated key to the global deprecation map when no custom message is provided. It does not override any existing entries in the deprecation map. This is to be used only by the developers in order to add deprecation of keys, and attempts to call this method after loading resources once, would lead to UnsupportedOperationException If a key is deprecated in favor of multiple keys, they are all treated as aliases of each other, and setting any one of them resets all the others to the new value. If you have multiple deprecation entries to add, it is more efficient to use #addDeprecations(DeprecationDelta[] deltas) instead.
      Parameters:
      key - Key that is to be deprecated
      newKeys - list of keys that take up the values of deprecated key

    • addDeprecation

      public static void addDeprecation(String key, String newKey)
      Adds the deprecated key to the global deprecation map when no custom message is provided. It does not override any existing entries in the deprecation map. This is to be used only by the developers in order to add deprecation of keys, and attempts to call this method after loading resources once, would lead to UnsupportedOperationException If you have multiple deprecation entries to add, it is more efficient to use #addDeprecations(DeprecationDelta[] deltas) instead.
      Parameters:
      key - Key that is to be deprecated
      newKey - key that takes up the value of deprecated key

    • isDeprecated

      public static boolean isDeprecated(String key)
      checks whether the given key is deprecated.
      Parameters:
      key - the parameter which is to be checked for deprecation
      Returns:
      true if the key is deprecated and false otherwise.

    • setDeprecatedProperties

      public void setDeprecatedProperties()
      Sets all deprecated properties that are not currently set but have a corresponding new property that is set. Useful for iterating the properties when all deprecated properties for currently set properties need to be present.

    • reloadExistingConfigurations

      public static void reloadExistingConfigurations()
      Reload existing configuration instances.

    • addDefaultResource

      public static void addDefaultResource(String name)
      Add a default resource. Resources are loaded in the order of the resources added.
      Parameters:
      name - file name. File should be present in the classpath.

    • setRestrictSystemPropertiesDefault

      public static void setRestrictSystemPropertiesDefault(boolean val)

    • setRestrictSystemProperties

      public void setRestrictSystemProperties(boolean val)

    • addResource

      public void addResource(String name)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final.
      Parameters:
      name - resource to be added, the classpath is examined for a file with that name.

    • addResource

      public void addResource(String name, boolean restrictedParser)

    • addResource

      public void addResource(URL url)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final.
      Parameters:
      url - url of the resource to be added, the local filesystem is examined directly to find the resource, without referring to the classpath.

    • addResource

      public void addResource(URL url, boolean restrictedParser)

    • addResource

      public void addResource(Path file)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final.
      Parameters:
      file - file-path of resource to be added, the local filesystem is examined directly to find the resource, without referring to the classpath.

    • addResource

      public void addResource(Path file, boolean restrictedParser)

    • addResource

      public void addResource(InputStream in)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final. WARNING: The contents of the InputStream will be cached, by this method. So use this sparingly because it does increase the memory consumption.
      Parameters:
      in - InputStream to deserialize the object from. In will be read from when a get or set is called next. After it is read the stream will be closed.

    • addResource

      public void addResource(InputStream in, boolean restrictedParser)

    • addResource

      public void addResource(InputStream in, String name)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final.
      Parameters:
      in - InputStream to deserialize the object from.
      name - the name of the resource because InputStream.toString is not very descriptive some times.

    • addResource

      public void addResource(InputStream in, String name, boolean restrictedParser)

    • addResource

      public void addResource(Configuration conf)
      Add a configuration resource. The properties of this resource will override properties of previously added resources, unless they were marked final.
      Parameters:
      conf - Configuration object from which to load properties

    • reloadConfiguration

      public void reloadConfiguration()
      Reload configuration from previously added resources. This method will clear all the configuration read from the added resources, and final parameters. This will make the resources to be read again before accessing the values. Values that are added via set methods will overlay values read from the resources.

    • substituteCommonVariables

      public String substituteCommonVariables(String expr)
      Provides a public wrapper over substituteVars in order to avoid compatibility issues. See HADOOP-18021 for further details.
      Parameters:
      expr - the literal value of a config key
      Returns:
      null if expr is null, otherwise the value resulting from expanding expr using the algorithm above.
      Throws:
      IllegalArgumentException - when more than MAX_SUBST replacements are required

    • get

      public String get(String name)
      Get the value of the name property, null if no such property exists. If the key is deprecated, it returns the value of the first key which replaces the deprecated key and is not null. Values are processed for variable expansion before being returned. As a side effect get loads the properties from the sources if called for the first time as a lazy init.
      Parameters:
      name - the property name, will be trimmed before get value.
      Returns:
      the value of the name or its replacing property, or null if no such property exists.

    • setAllowNullValueProperties

      @VisibleForTesting public void setAllowNullValueProperties(boolean val)
      Set Configuration to allow keys without values during setup. Intended for use during testing.
      Parameters:
      val - If true, will allow Configuration to store keys without values

    • setRestrictSystemProps

      public void setRestrictSystemProps(boolean val)

    • onlyKeyExists

      @VisibleForTesting public boolean onlyKeyExists(String name)
      Return existence of the name property, but only for names which have no valid value, usually non-existent or commented out in XML.
      Parameters:
      name - the property name
      Returns:
      true if the property name exists without value

    • getTrimmed

      public String getTrimmed(String name)
      Get the value of the name property as a trimmed String, null if no such property exists. If the key is deprecated, it returns the value of the first key which replaces the deprecated key and is not null Values are processed for variable expansion before being returned.
      Parameters:
      name - the property name.
      Returns:
      the value of the name or its replacing property, or null if no such property exists.

    • getTrimmed

      public String getTrimmed(String name, String defaultValue)
      Get the value of the name property as a trimmed String, defaultValue if no such property exists. See @{Configuration#getTrimmed} for more details.
      Parameters:
      name - the property name.
      defaultValue - the property default value.
      Returns:
      the value of the name or defaultValue if it is not set.

    • getRaw

      public String getRaw(String name)
      Get the value of the name property, without doing variable expansion.If the key is deprecated, it returns the value of the first key which replaces the deprecated key and is not null.
      Parameters:
      name - the property name.
      Returns:
      the value of the name property or its replacing property and null if no such property exists.

    • set

      public void set(String name, String value)
      Set the value of the name property. If name is deprecated or there is a deprecated name associated to it, it sets the value to both names. Name will be trimmed before put into configuration.
      Parameters:
      name - property name.
      value - property value.

    • set

      public void set(String name, String value, String source)
      Set the value of the name property. If name is deprecated, it also sets the value to the keys that replace the deprecated key. Name will be trimmed before put into configuration.
      Parameters:
      name - property name.
      value - property value.
      source - the place that this configuration value came from (For debugging).
      Throws:
      IllegalArgumentException - when the value or name is null.

    • unset

      public void unset(String name)
      Unset a previously set property.
      Parameters:
      name - the property name

    • setIfUnset

      public void setIfUnset(String name, String value)
      Sets a property if it is currently unset.
      Parameters:
      name - the property name
      value - the new value

    • get

      public String get(String name, String defaultValue)
      Get the value of the name. If the key is deprecated, it returns the value of the first key which replaces the deprecated key and is not null. If no such property exists, then defaultValue is returned.
      Parameters:
      name - property name, will be trimmed before get value.
      defaultValue - default value.
      Returns:
      property value, or defaultValue if the property doesn't exist.

    • getInt

      public int getInt(String name, int defaultValue)
      Get the value of the name property as an int. If no such property exists, the provided default value is returned, or if the specified value is not a valid int, then an error is thrown.
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as an int, or defaultValue.
      Throws:
      NumberFormatException - when the value is invalid

    • getInts

      public int[] getInts(String name)
      Get the value of the name property as a set of comma-delimited int values. If no such property exists, an empty array is returned.
      Parameters:
      name - property name
      Returns:
      property value interpreted as an array of comma-delimited int values

    • setInt

      public void setInt(String name, int value)
      Set the value of the name property to an int.
      Parameters:
      name - property name.
      value - int value of the property.

    • getLong

      public long getLong(String name, long defaultValue)
      Get the value of the name property as a long. If no such property exists, the provided default value is returned, or if the specified value is not a valid long, then an error is thrown.
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as a long, or defaultValue.
      Throws:
      NumberFormatException - when the value is invalid

    • getLongBytes

      public long getLongBytes(String name, long defaultValue)
      Get the value of the name property as a long or human readable format. If no such property exists, the provided default value is returned, or if the specified value is not a valid long or human readable format, then an error is thrown. You can use the following suffix (case insensitive): k(kilo), m(mega), g(giga), t(tera), p(peta), e(exa)
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as a long, or defaultValue.
      Throws:
      NumberFormatException - when the value is invalid

    • setLong

      public void setLong(String name, long value)
      Set the value of the name property to a long.
      Parameters:
      name - property name.
      value - long value of the property.

    • getFloat

      public float getFloat(String name, float defaultValue)
      Get the value of the name property as a float. If no such property exists, the provided default value is returned, or if the specified value is not a valid float, then an error is thrown.
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as a float, or defaultValue.
      Throws:
      NumberFormatException - when the value is invalid

    • setFloat

      public void setFloat(String name, float value)
      Set the value of the name property to a float.
      Parameters:
      name - property name.
      value - property value.

    • getDouble

      public double getDouble(String name, double defaultValue)
      Get the value of the name property as a double. If no such property exists, the provided default value is returned, or if the specified value is not a valid double, then an error is thrown.
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as a double, or defaultValue.
      Throws:
      NumberFormatException - when the value is invalid

    • setDouble

      public void setDouble(String name, double value)
      Set the value of the name property to a double.
      Parameters:
      name - property name.
      value - property value.

    • getBoolean

      public boolean getBoolean(String name, boolean defaultValue)
      Get the value of the name property as a boolean. If no such property is specified, or if the specified value is not a valid boolean, then defaultValue is returned.
      Parameters:
      name - property name.
      defaultValue - default value.
      Returns:
      property value as a boolean, or defaultValue.

    • setBoolean

      public void setBoolean(String name, boolean value)
      Set the value of the name property to a boolean.
      Parameters:
      name - property name.
      value - boolean value of the property.

    • setBooleanIfUnset

      public void setBooleanIfUnset(String name, boolean value)
      Set the given property, if it is currently unset.
      Parameters:
      name - property name
      value - new value

    • setEnum

      public <T extends Enum<T>> void setEnum(String name, T value)
      Set the value of the name property to the given type. This is equivalent to set(<name>, value.toString()).
      Type Parameters:
      T - enumeration type
      Parameters:
      name - property name
      value - new value

    • getEnum

      public <T extends Enum<T>> T getEnum(String name, T defaultValue)
      Return value matching this enumerated type. Note that the returned value is trimmed by this method.
      Type Parameters:
      T - enumeration type
      Parameters:
      name - Property name
      defaultValue - Value returned if no mapping exists
      Returns:
      enumeration type
      Throws:
      IllegalArgumentException - If mapping is illegal for the type provided

    • getEnumSet

      public <E extends Enum<E>> EnumSet<E> getEnumSet(String key, Class<E> enumClass, boolean ignoreUnknown) throws IllegalArgumentException
      Build an enumset from a comma separated list of values. Case independent. Special handling of "*" meaning: all values.
      Type Parameters:
      E - enumeration type
      Parameters:
      key - key to look for
      enumClass - class of enum
      ignoreUnknown - should unknown values raise an exception?
      Returns:
      a mutable set of the identified enum values declared in the configuration
      Throws:
      IllegalArgumentException - if one of the entries was unknown and ignoreUnknown is false, or there are two entries in the enum which differ only by case.

    • setTimeDuration

      public void setTimeDuration(String name, long value, TimeUnit unit)
      Set the value of name to the given time duration. This is equivalent to set(<name>, value + <time suffix>).
      Parameters:
      name - Property name
      value - Time duration
      unit - Unit of time

    • getTimeDuration

      public long getTimeDuration(String name, long defaultValue, TimeUnit unit)
      Return time duration in the given time unit. Valid units are encoded in properties as suffixes: nanoseconds (ns), microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), and days (d).
      Parameters:
      name - Property name
      defaultValue - Value returned if no mapping exists.
      unit - Unit to convert the stored property, if it exists.
      Returns:
      time duration in given time unit
      Throws:
      NumberFormatException - If the property stripped of its unit is not a number

    • getTimeDuration

      public long getTimeDuration(String name, String defaultValue, TimeUnit unit)

    • getTimeDuration

      public long getTimeDuration(String name, long defaultValue, TimeUnit defaultUnit, TimeUnit returnUnit)
      Return time duration in the given time unit. Valid units are encoded in properties as suffixes: nanoseconds (ns), microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), and days (d). If no unit is provided, the default unit is applied.
      Parameters:
      name - Property name
      defaultValue - Value returned if no mapping exists.
      defaultUnit - Default time unit if no valid suffix is provided.
      returnUnit - The unit used for the returned value.
      Returns:
      time duration in given time unit
      Throws:
      NumberFormatException - If the property stripped of its unit is not a number

    • getTimeDuration

      public long getTimeDuration(String name, String defaultValue, TimeUnit defaultUnit, TimeUnit returnUnit)

    • getTimeDurationHelper

      public long getTimeDurationHelper(String name, String vStr, TimeUnit unit)
      Return time duration in the given time unit. Valid units are encoded in properties as suffixes: nanoseconds (ns), microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), and days (d).
      Parameters:
      name - Property name
      vStr - The string value with time unit suffix to be converted.
      unit - Unit to convert the stored property, if it exists.
      Returns:
      time duration in given time unit.

    • getTimeDurations

      public long[] getTimeDurations(String name, TimeUnit unit)

    • getStorageSize

      public double getStorageSize(String name, String defaultValue, StorageUnit targetUnit)
      Gets the Storage Size from the config, or returns the defaultValue. The unit of return value is specified in target unit.
      Parameters:
      name - - Key Name
      defaultValue - - Default Value -- e.g. 100MB
      targetUnit - - The units that we want result to be in.
      Returns:
      double -- formatted in target Units

    • getStorageSize

      public double getStorageSize(String name, double defaultValue, StorageUnit targetUnit)
      Gets storage size from a config file.
      Parameters:
      name - - Key to read.
      defaultValue - - The default value to return in case the key is not present.
      targetUnit - - The Storage unit that should be used for the return value.
      Returns:
      - double value in the Storage Unit specified.

    • setStorageSize

      public void setStorageSize(String name, double value, StorageUnit unit)
      Sets Storage Size for the specified key.
      Parameters:
      name - - Key to set.
      value - - The numeric value to set.
      unit - - Storage Unit to be used.

    • getPattern

      public Pattern getPattern(String name, Pattern defaultValue)
      Get the value of the name property as a Pattern. If no such property is specified, or if the specified value is not a valid Pattern, then DefaultValue is returned. Note that the returned value is NOT trimmed by this method.
      Parameters:
      name - property name
      defaultValue - default value
      Returns:
      property value as a compiled Pattern, or defaultValue

    • setPattern

      public void setPattern(String name, Pattern pattern)
      Set the given property to Pattern. If the pattern is passed as null, sets the empty pattern which results in further calls to getPattern(...) returning the default value.
      Parameters:
      name - property name
      pattern - new value

    • getPropertySources

      @Unstable public String[] getPropertySources(String name)
      Gets information about why a property was set. Typically this is the path to the resource objects (file, URL, etc.) the property came from, but it can also indicate that it was set programmatically, or because of the command line.
      Parameters:
      name - - The property name to get the source of.
      Returns:
      null - If the property or its source wasn't found. Otherwise, returns a list of the sources of the resource. The older sources are the first ones in the list. So for example if a configuration is set from the command line, and then written out to a file that is read back in the first entry would indicate that it was set from the command line, while the second one would indicate the file that the new configuration was read in from.

    • getRange

      public org.apache.hadoop.conf.Configuration.IntegerRanges getRange(String name, String defaultValue)
      Parse the given attribute as a set of integer ranges.
      Parameters:
      name - the attribute name
      defaultValue - the default value if it is not set
      Returns:
      a new set of ranges from the configured value

    • getStringCollection

      public Collection<String> getStringCollection(String name)
      Get the comma delimited values of the name property as a collection of Strings. If no such property is specified then empty collection is returned.

      This is an optimized version of getStrings(String)

      Parameters:
      name - property name.
      Returns:
      property value as a collection of Strings.

    • getStrings

      public String[] getStrings(String name)
      Get the comma delimited values of the name property as an array of Strings. If no such property is specified then null is returned.
      Parameters:
      name - property name.
      Returns:
      property value as an array of Strings, or null.

    • getStrings

      public String[] getStrings(String name, String... defaultValue)
      Get the comma delimited values of the name property as an array of Strings. If no such property is specified then default value is returned.
      Parameters:
      name - property name.
      defaultValue - The default value
      Returns:
      property value as an array of Strings, or default value.

    • getTrimmedStringCollection

      public Collection<String> getTrimmedStringCollection(String name)
      Get the comma delimited values of the name property as a collection of Strings, trimmed of the leading and trailing whitespace. If no such property is specified then empty Collection is returned.
      Parameters:
      name - property name.
      Returns:
      property value as a collection of Strings, or empty Collection

    • getTrimmedStrings

      public String[] getTrimmedStrings(String name)
      Get the comma delimited values of the name property as an array of Strings, trimmed of the leading and trailing whitespace. If no such property is specified then an empty array is returned.
      Parameters:
      name - property name.
      Returns:
      property value as an array of trimmed Strings, or empty array.

    • getTrimmedStrings

      public String[] getTrimmedStrings(String name, String... defaultValue)
      Get the comma delimited values of the name property as an array of Strings, trimmed of the leading and trailing whitespace. If no such property is specified then default value is returned.
      Parameters:
      name - property name.
      defaultValue - The default value
      Returns:
      property value as an array of trimmed Strings, or default value.

    • setStrings

      public void setStrings(String name, String... values)
      Set the array of string values for the name property as as comma delimited values.
      Parameters:
      name - property name.
      values - The values

    • getPassword

      public char[] getPassword(String name) throws IOException
      Get the value for a known password configuration element. In order to enable the elimination of clear text passwords in config, this method attempts to resolve the property name as an alias through the CredentialProvider API and conditionally fallsback to config.
      Parameters:
      name - property name
      Returns:
      password
      Throws:
      IOException - when error in fetching password

    • getPasswordFromCredentialProviders

      public char[] getPasswordFromCredentialProviders(String name) throws IOException
      Try and resolve the provided element name as a credential provider alias.
      Parameters:
      name - alias of the provisioned credential
      Returns:
      password or null if not found
      Throws:
      IOException - when error in fetching password

    • getPasswordFromConfig

      protected char[] getPasswordFromConfig(String name)
      Fallback to clear text passwords in configuration.
      Parameters:
      name - the property name.
      Returns:
      clear text password or null

    • getSocketAddr

      public InetSocketAddress getSocketAddr(String hostProperty, String addressProperty, String defaultAddressValue, int defaultPort)
      Get the socket address for hostProperty as a InetSocketAddress. If hostProperty is null, addressProperty will be used. This is useful for cases where we want to differentiate between host bind address and address clients should use to establish connection.
      Parameters:
      hostProperty - bind host property name.
      addressProperty - address property name.
      defaultAddressValue - the default value
      defaultPort - the default port
      Returns:
      InetSocketAddress

    • getSocketAddr

      public InetSocketAddress getSocketAddr(String name, String defaultAddress, int defaultPort)
      Get the socket address for name property as a InetSocketAddress.
      Parameters:
      name - property name.
      defaultAddress - the default value
      defaultPort - the default port
      Returns:
      InetSocketAddress

    • setSocketAddr

      public void setSocketAddr(String name, InetSocketAddress addr)
      Set the socket address for the name property as a host:port.
      Parameters:
      name - property name.
      addr - inetSocketAddress addr.

    • updateConnectAddr

      public InetSocketAddress updateConnectAddr(String hostProperty, String addressProperty, String defaultAddressValue, InetSocketAddress addr)
      Set the socket address a client can use to connect for the name property as a host:port. The wildcard address is replaced with the local host's address. If the host and address properties are configured the host component of the address will be combined with the port component of the addr to generate the address. This is to allow optional control over which host name is used in multi-home bind-host cases where a host can have multiple names
      Parameters:
      hostProperty - the bind-host configuration name
      addressProperty - the service address configuration name
      defaultAddressValue - the service default address configuration value
      addr - InetSocketAddress of the service listener
      Returns:
      InetSocketAddress for clients to connect

    • updateConnectAddr

      public InetSocketAddress updateConnectAddr(String name, InetSocketAddress addr)
      Set the socket address a client can use to connect for the name property as a host:port. The wildcard address is replaced with the local host's address.
      Parameters:
      name - property name.
      addr - InetSocketAddress of a listener to store in the given property
      Returns:
      InetSocketAddress for clients to connect

    • getClassByName

      public Class<?> getClassByName(String name) throws ClassNotFoundException
      Load a class by name.
      Parameters:
      name - the class name.
      Returns:
      the class object.
      Throws:
      ClassNotFoundException - if the class is not found.

    • getClassByNameOrNull

      public Class<?> getClassByNameOrNull(String name)
      Load a class by name, returning null rather than throwing an exception if it couldn't be loaded. This is to avoid the overhead of creating an exception.
      Parameters:
      name - the class name
      Returns:
      the class object, or null if it could not be found.

    • getClasses

      public Class<?>[] getClasses(String name, Class<?>... defaultValue)
      Get the value of the name property as an array of Class. The value of the property specifies a list of comma separated class names. If no such property is specified, then defaultValue is returned.
      Parameters:
      name - the property name.
      defaultValue - default value.
      Returns:
      property value as a Class[], or defaultValue.

    • getClass

      public Class<?> getClass(String name, Class<?> defaultValue)
      Get the value of the name property as a Class. If no such property is specified, then defaultValue is returned.
      Parameters:
      name - the conf key name.
      defaultValue - default value.
      Returns:
      property value as a Class, or defaultValue.

    • getClass

      public <U> Class<? extends U> getClass(String name, Class<? extends U> defaultValue, Class<U> xface)
      Get the value of the name property as a Class implementing the interface specified by xface. If no such property is specified, then defaultValue is returned. An exception is thrown if the returned class does not implement the named interface.
      Type Parameters:
      U - Interface class type.
      Parameters:
      name - the conf key name.
      defaultValue - default value.
      xface - the interface implemented by the named class.
      Returns:
      property value as a Class, or defaultValue.

    • getInstances

      public <U> List<U> getInstances(String name, Class<U> xface)
      Get the value of the name property as a List of objects implementing the interface specified by xface. An exception is thrown if any of the classes does not exist, or if it does not implement the named interface.
      Type Parameters:
      U - Interface class type.
      Parameters:
      name - the property name.
      xface - the interface implemented by the classes named by name.
      Returns:
      a List of objects implementing xface.

    • setClass

      public void setClass(String name, Class<?> theClass, Class<?> xface)
      Set the value of the name property to the name of a theClass implementing the given interface xface. An exception is thrown if theClass does not implement the interface xface.
      Parameters:
      name - property name.
      theClass - property value.
      xface - the interface implemented by the named class.

    • getLocalPath

      public Path getLocalPath(String dirsProp, String path) throws IOException
      Get a local file under a directory named by dirsProp with the given path. If dirsProp contains multiple directories, then one is chosen based on path's hash code. If the selected directory does not exist, an attempt is made to create it.
      Parameters:
      dirsProp - directory in which to locate the file.
      path - file-path.
      Returns:
      local file under the directory with the given path.
      Throws:
      IOException - raised on errors performing I/O.

    • getFile

      public File getFile(String dirsProp, String path) throws IOException
      Get a local file name under a directory named in dirsProp with the given path. If dirsProp contains multiple directories, then one is chosen based on path's hash code. If the selected directory does not exist, an attempt is made to create it.
      Parameters:
      dirsProp - directory in which to locate the file.
      path - file-path.
      Returns:
      local file under the directory with the given path.
      Throws:
      IOException - raised on errors performing I/O.

    • getResource

      public URL getResource(String name)
      Get the URL for the named resource.
      Parameters:
      name - resource name.
      Returns:
      the url for the named resource.

    • getConfResourceAsInputStream

      public InputStream getConfResourceAsInputStream(String name)
      Get an input stream attached to the configuration resource with the given name.
      Parameters:
      name - configuration resource name.
      Returns:
      an input stream attached to the resource.

    • getConfResourceAsReader

      public Reader getConfResourceAsReader(String name)
      Get a Reader attached to the configuration resource with the given name.
      Parameters:
      name - configuration resource name.
      Returns:
      a reader attached to the resource.

    • getFinalParameters

      public Set<String> getFinalParameters()
      Get the set of parameters marked final.
      Returns:
      final parameter set.

    • getProps

      protected Properties getProps()

    • size

      public int size()
      Return the number of keys in the configuration.
      Returns:
      number of keys in the configuration.

    • clear

      public void clear()
      Clears all keys from the configuration.

    • iterator

      public Iterator<Map.Entry<String,String>> iterator()
      Get an Iterator to go through the list of String key-value pairs in the configuration.
      Specified by:
      iterator in interface Iterable<Map.Entry<String,String>>
      Returns:
      an iterator over the entries.

    • getPropsWithPrefix

      public Map<String,String> getPropsWithPrefix(String confPrefix)
      Constructs a mapping of configuration and includes all properties that start with the specified configuration prefix. Property names in the mapping are trimmed to remove the configuration prefix.
      Parameters:
      confPrefix - configuration prefix
      Returns:
      mapping of configuration properties with prefix stripped

    • addTags

      public void addTags(Properties prop)
      Add tags defined in HADOOP_TAGS_SYSTEM, HADOOP_TAGS_CUSTOM.
      Parameters:
      prop - properties.

    • writeXml

      public void writeXml(OutputStream out) throws IOException
      Write out the non-default properties in this configuration to the given OutputStream using UTF-8 encoding.
      Parameters:
      out - the output stream to write to.
      Throws:
      IOException - raised on errors performing I/O.

    • writeXml

      public void writeXml(Writer out) throws IOException
      Throws:
      IOException

    • writeXml

      public void writeXml(@Nullable String propertyName, Writer out, Configuration config) throws IOException, IllegalArgumentException
      Write out the non-default properties in this configuration to the given Writer.
      • When property name is not empty and the property exists in the configuration, this method writes the property and its attributes to the Writer.
      • When property name is null or empty, this method writes all the configuration properties and their attributes to the Writer.
      • When property name is not empty but the property doesn't exist in the configuration, this method throws an IllegalArgumentException.
      Parameters:
      propertyName - xml property name.
      out - the writer to write to.
      config - configuration.
      Throws:
      IOException - raised on errors performing I/O.
      IllegalArgumentException

    • writeXml

      public void writeXml(@Nullable String propertyName, Writer out) throws IOException, IllegalArgumentException
      Throws:
      IOException
      IllegalArgumentException

    • dumpConfiguration

      public static void dumpConfiguration(Configuration config, String propertyName, Writer out) throws IOException
      Writes properties and their attributes (final and resource) to the given Writer.
      • When propertyName is not empty, and the property exists in the configuration, the format of the output would be, 
          {
    "property": {
      "key" : "key1",
      "value" : "value1",
      "isFinal" : "key1.isFinal",
      "resource" : "key1.resource"
    }
  }
      • When propertyName is null or empty, it behaves same as dumpConfiguration(Configuration, Writer), the output would be, 
          { "properties" :
      [ { key : "key1",
          value : "value1",
          isFinal : "key1.isFinal",
          resource : "key1.resource" },
        { key : "key2",
          value : "value2",
          isFinal : "ke2.isFinal",
          resource : "key2.resource" }
       ]
   }
      • When propertyName is not empty, and the property is not found in the configuration, this method will throw an IllegalArgumentException.

      Parameters:
      config - the configuration
      propertyName - property name
      out - the Writer to write to
      Throws:
      IOException - raised on errors performing I/O.
      IllegalArgumentException - when property name is not empty and the property is not found in configuration

    • dumpConfiguration

      public static void dumpConfiguration(Configuration config, Writer out) throws IOException
      Writes out all properties and their attributes (final and resource) to the given Writer, the format of the output would be, 
        { "properties" :
      [ { key : "key1",
          value : "value1",
          isFinal : "key1.isFinal",
          resource : "key1.resource" },
        { key : "key2",
          value : "value2",
          isFinal : "ke2.isFinal",
          resource : "key2.resource" }
       ]
   }
      It does not output the properties of the configuration object which is loaded from an input stream.

      Parameters:
      config - the configuration
      out - the Writer to write to
      Throws:
      IOException - raised on errors performing I/O.

    • getClassLoader

      public ClassLoader getClassLoader()
      Get the ClassLoader for this job.
      Returns:
      the correct class loader.

    • setClassLoader

      public void setClassLoader(ClassLoader classLoader)
      Set the class loader that will be used to load the various objects.
      Parameters:
      classLoader - the new class loader.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • setQuietMode

      public void setQuietMode(boolean quietmode)
      Set the quietness-mode. In the quiet-mode, error and informational messages might not be logged.
      Parameters:
      quietmode - true to set quiet-mode on, false to turn it off.

    • main

      public static void main(String[] args) throws Exception
      For debugging. List non-default properties to the terminal and exit.
      Parameters:
      args - the argument to be parsed.
      Throws:
      Exception - exception.

    • readFields

      public void readFields(DataInput in) throws IOException
      Description copied from interface: Writable
      Deserialize the fields of this object from in.

      For efficiency, implementations should attempt to re-use storage in the existing object where possible.

      Specified by:
      readFields in interface Writable
      Parameters:
      in - DataInput to deseriablize this object from.
      Throws:
      IOException - any other problem for readFields.

    • write

      public void write(DataOutput out) throws IOException
      Description copied from interface: Writable
      Serialize the fields of this object to out.
      Specified by:
      write in interface Writable
      Parameters:
      out - DataOuput to serialize this object into.
      Throws:
      IOException - any other problem for write.

    • getValByRegex

      public Map<String,String> getValByRegex(String regex)
      get keys matching the the regex.
      Parameters:
      regex - the regex to match against.
      Returns:
      Map<String,String> with matching keys

    • dumpDeprecatedKeys

      public static void dumpDeprecatedKeys()

    • hasWarnedDeprecation

      public static boolean hasWarnedDeprecation(String name)
      Returns whether or not a deprecated name has been warned. If the name is not deprecated then always return false
      Parameters:
      name - proprties.
      Returns:
      true if name is a warned deprecation.

    • getAllPropertiesByTag

      public Properties getAllPropertiesByTag(String tag)
      Get all properties belonging to tag.
      Parameters:
      tag - tag
      Returns:
      Properties with matching tag

    • getAllPropertiesByTags

      public Properties getAllPropertiesByTags(List<String> tagList)
      Get all properties belonging to list of input tags. Calls getAllPropertiesByTag internally.
      Parameters:
      tagList - list of input tags
      Returns:
      Properties with matching tags

    • isPropertyTag

      public boolean isPropertyTag(String tagStr)
      Get Property tag Enum corresponding to given source.
      Parameters:
      tagStr - String representation of Enum
      Returns:
      true if tagStr is a valid tag