org.datavec.api.conf

Class Configuration

java.lang.Object

org.datavec.api.conf.Configuration

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>, Writable

public class Configuration
extends java.lang.Object
implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>, Writable, java.io.Serializable

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. 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.client.buffer.dir</name>
    <value>/tmp/hadoop/dfs/client</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. 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>

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.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Configuration.IntegerRanges A class that represents a set of positive integer ranges.

Constructor Summary

Constructors

Constructor and Description
Configuration() A new configuration.
Configuration(boolean loadDefaults) A new configuration where the behavior of reading from the default resources can be turned off.
Configuration(Configuration other) A new configuration with the same settings cloned from another.

Method Summary

Modifier and Type	Method and Description
static void	addDefaultResource(java.lang.String name) Add a default resource.
void	addResource(java.io.InputStream in) Add a configuration resource.
void	addResource(java.lang.String name) Add a configuration resource.
void	addResource(java.net.URL url) Add a configuration resource.
void	clear() Clears all keys from the configuration.
static void	dumpConfiguration(Configuration conf, java.io.Writer out) Writes out all the parameters and their properties (final and resource) to the given Writer The format of the output would be { "properties" : [ {key1,value1,key1.isFinal,key1.resource}, {key2,value2, key2.isFinal,key2.resource}...
java.lang.String	get(java.lang.String name) Get the value of the name property, null if no such property exists.
java.lang.String	get(java.lang.String name, java.lang.String defaultValue) Get the value of the name property.
boolean	getBoolean(java.lang.String name, boolean defaultValue) Get the value of the name property as a boolean.
java.lang.Class<?>	getClass(java.lang.String name, java.lang.Class<?> defaultValue) Get the value of the name property as a Class.
<U> java.lang.Class<? extends U>	getClass(java.lang.String name, java.lang.Class<? extends U> defaultValue, java.lang.Class<U> xface) Get the value of the name property as a Class implementing the interface specified by xface.
java.lang.Class<?>	getClassByName(java.lang.String name) Load a class by name.
java.lang.Class<?>[]	getClasses(java.lang.String name, java.lang.Class<?>... defaultValue) Get the value of the name property as an array of Class.
java.lang.ClassLoader	getClassLoader() Get the ClassLoader for this job.
java.io.InputStream	getConfResourceAsInputStream(java.lang.String name) Get an input stream attached to the configuration resource with the given name.
java.io.Reader	getConfResourceAsReader(java.lang.String name) Get a Reader attached to the configuration resource with the given name.
java.io.File	getFile(java.lang.String dirsProp, java.lang.String path) Get a local file name under a directory named in dirsProp with the given path.
float	getFloat(java.lang.String name, float defaultValue) Get the value of the name property as a float.
<U> java.util.List<U>	getInstances(java.lang.String name, java.lang.Class<U> xface) Get the value of the name property as a List of objects implementing the interface specified by xface.
int	getInt(java.lang.String name, int defaultValue) Get the value of the name property as an int.
long	getLong(java.lang.String name, long defaultValue) Get the value of the name property as a long.
java.util.regex.Pattern	getPattern(java.lang.String name, java.util.regex.Pattern defaultValue) Get the value of the name property as a Pattern.
Configuration.IntegerRanges	getRange(java.lang.String name, java.lang.String defaultValue) Parse the given attribute as a set of integer ranges
java.lang.String	getRaw(java.lang.String name) Get the value of the name property, without doing variable expansion.
java.net.URL	getResource(java.lang.String name) Get the URL for the named resource.
java.util.Collection<java.lang.String>	getStringCollection(java.lang.String name) Get the comma delimited values of the name property as a collection of Strings.
java.lang.String[]	getStrings(java.lang.String name) Get the comma delimited values of the name property as an array of Strings.
java.lang.String[]	getStrings(java.lang.String name, java.lang.String... defaultValue) Get the comma delimited values of the name property as an array of Strings.
java.util.Collection<java.lang.String>	getTrimmedStringCollection(java.lang.String name) Get the comma delimited values of the name property as a collection of Strings, trimmed of the leading and trailing whitespace.
java.lang.String[]	getTrimmedStrings(java.lang.String name) Get the comma delimited values of the name property as an array of Strings, trimmed of the leading and trailing whitespace.
java.lang.String[]	getTrimmedStrings(java.lang.String name, java.lang.String... defaultValue) Get the comma delimited values of the name property as an array of Strings, trimmed of the leading and trailing whitespace.
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>>	iterator() Get an Iterator to go through the list of String key-value pairs in the configuration.
static void	main(java.lang.String[] args) For debugging.
void	readFields(java.io.DataInput in) Deserialize the fields of this object from in.
void	reloadConfiguration() Reload configuration from previously added resources.
void	set(java.lang.String name, java.lang.String value) Set the value of the name property.
void	setBoolean(java.lang.String name, boolean value) Set the value of the name property to a boolean.
void	setBooleanIfUnset(java.lang.String name, boolean value) Set the given property, if it is currently unset.
void	setClass(java.lang.String name, java.lang.Class<?> theClass, java.lang.Class<?> xface) Set the value of the name property to the name of a theClass implementing the given interface xface.
void	setClassLoader(java.lang.ClassLoader classLoader) Set the class loader that will be used to load the various objects.
void	setFloat(java.lang.String name, float value) Set the value of the name property to a float.
void	setIfUnset(java.lang.String name, java.lang.String value) Sets a property if it is currently unset.
void	setInt(java.lang.String name, int value) Set the value of the name property to an int.
void	setLong(java.lang.String name, long value) Set the value of the name property to a long.
void	setPattern(java.lang.String name, java.util.regex.Pattern pattern) Set the given property to Pattern.
void	setQuietMode(boolean quietmode) Set the quietness-mode.
void	setStrings(java.lang.String name, java.lang.String... values) Set the array of string values for the name property as as comma delimited values.
int	size() Return the number of keys in the configuration.
double	toDouble() Convert Writable to double.
float	toFloat() Convert Writable to float.
int	toInt() Convert Writable to int.
long	toLong() Convert Writable to long.
java.lang.String	toString()
void	write(java.io.DataOutput out) Serialize the fields of this object to out.
void	writeXml(java.io.OutputStream out) Write out the non-default properties in this configuration to the give OutputStream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

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 Detail

addDefaultResource

public static void addDefaultResource(java.lang.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.

addResource

public void addResource(java.lang.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(java.net.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(java.io.InputStream in)

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.

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.

get

public java.lang.String get(java.lang.String name)

Get the value of the name property, null if no such property exists. Values are processed for variable expansion before being returned.

Parameters:

name - the property name.

Returns:

the value of the name property, or null if no such property exists.

getRaw

public java.lang.String getRaw(java.lang.String name)

Get the value of the name property, without doing variable expansion.

Parameters:

name - the property name.

Returns:

the value of the name property, or null if no such property exists.

set

public void set(java.lang.String name,
                java.lang.String value)

Set the value of the name property.

Parameters:

name - property name.

value - property value.

setIfUnset

public void setIfUnset(java.lang.String name,
                       java.lang.String value)

Sets a property if it is currently unset.

Parameters:

name - the property name

value - the new value

get

public java.lang.String get(java.lang.String name,
                            java.lang.String defaultValue)

Get the value of the name property. If no such property exists, then defaultValue is returned.

Parameters:

name - property name.

defaultValue - default value.

Returns:

property value, or defaultValue if the property doesn't exist.

getInt

public int getInt(java.lang.String name,
                  int defaultValue)

Get the value of the name property as an int. If no such property exists, or if the specified value is not a valid int, then defaultValue is returned.

Parameters:

name - property name.

defaultValue - default value.

Returns:

property value as an int, or defaultValue.

setInt

public void setInt(java.lang.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(java.lang.String name,
                    long defaultValue)

Get the value of the name property as a long. If no such property is specified, or if the specified value is not a valid long, then defaultValue is returned.

Parameters:

name - property name.

defaultValue - default value.

Returns:

property value as a long, or defaultValue.

setLong

public void setLong(java.lang.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(java.lang.String name,
                      float defaultValue)

Get the value of the name property as a float. If no such property is specified, or if the specified value is not a valid float, then defaultValue is returned.

Parameters:

name - property name.

defaultValue - default value.

Returns:

property value as a float, or defaultValue.

setFloat

public void setFloat(java.lang.String name,
                     float value)

Set the value of the name property to a float.

Parameters:

name - property name.

value - property value.

getBoolean

public boolean getBoolean(java.lang.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(java.lang.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(java.lang.String name,
                              boolean value)

Set the given property, if it is currently unset.

Parameters:

name - property name

value - new value

getPattern

public java.util.regex.Pattern getPattern(java.lang.String name,
                                          java.util.regex.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.

Parameters:

name - property name

defaultValue - default value

Returns:

property value as a compiled Pattern, or defaultValue

setPattern

public void setPattern(java.lang.String name,
                       java.util.regex.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

write

public void write(java.io.DataOutput out)
           throws java.io.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:

java.io.IOException

readFields

public void readFields(java.io.DataInput in)
                throws java.io.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:

java.io.IOException

getRange

public Configuration.IntegerRanges getRange(java.lang.String name,
                                            java.lang.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 java.util.Collection<java.lang.String> getStringCollection(java.lang.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 java.lang.String[] getStrings(java.lang.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 java.lang.String[] getStrings(java.lang.String name,
                                     java.lang.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 java.util.Collection<java.lang.String> getTrimmedStringCollection(java.lang.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 java.lang.String[] getTrimmedStrings(java.lang.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 java.lang.String[] getTrimmedStrings(java.lang.String name,
                                            java.lang.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(java.lang.String name,
                       java.lang.String... values)

Set the array of string values for the name property as as comma delimited values.

Parameters:

name - property name.

values - The values

getClassByName

public java.lang.Class<?> getClassByName(java.lang.String name)
                                  throws java.lang.ClassNotFoundException

Load a class by name.

Parameters:

name - the class name.

Returns:

the class object.

Throws:

java.lang.ClassNotFoundException - if the class is not found.

getClasses

public java.lang.Class<?>[] getClasses(java.lang.String name,
                                       java.lang.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 java.lang.Class<?> getClass(java.lang.String name,
                                   java.lang.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 class name.

defaultValue - default value.

Returns:

property value as a Class, or defaultValue.

getClass

public <U> java.lang.Class<? extends U> getClass(java.lang.String name,
                                                 java.lang.Class<? extends U> defaultValue,
                                                 java.lang.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.

Parameters:

name - the class name.

defaultValue - default value.

xface - the interface implemented by the named class.

Returns:

property value as a Class, or defaultValue.

getInstances

public <U> java.util.List<U> getInstances(java.lang.String name,
                                          java.lang.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.

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(java.lang.String name,
                     java.lang.Class<?> theClass,
                     java.lang.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.

getFile

public java.io.File getFile(java.lang.String dirsProp,
                            java.lang.String path)
                     throws java.io.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:

java.io.IOException

getResource

public java.net.URL getResource(java.lang.String name)

Get the URL for the named resource.

Parameters:

name - resource name.

Returns:

the url for the named resource.

getConfResourceAsInputStream

public java.io.InputStream getConfResourceAsInputStream(java.lang.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 java.io.Reader getConfResourceAsReader(java.lang.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.

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 java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> iterator()

Get an Iterator to go through the list of String key-value pairs in the configuration.

Specified by:

iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>

Returns:

an iterator over the entries.

writeXml

public void writeXml(java.io.OutputStream out)
              throws java.io.IOException

Write out the non-default properties in this configuration to the give OutputStream.

Parameters:

out - the output stream to write to.

Throws:

java.io.IOException

dumpConfiguration

public static void dumpConfiguration(Configuration conf,
                                     java.io.Writer out)
                              throws java.io.IOException

Writes out all the parameters and their properties (final and resource) to the given Writer The format of the output would be { "properties" : [ {key1,value1,key1.isFinal,key1.resource}, {key2,value2, key2.isFinal,key2.resource}... ] } It does not output the parameters of the configuration object which is loaded from an input stream.

Parameters:

out - the Writer to write to

Throws:

java.io.IOException

getClassLoader

public java.lang.ClassLoader getClassLoader()

Get the ClassLoader for this job.

Returns:

the correct class loader.

setClassLoader

public void setClassLoader(java.lang.ClassLoader classLoader)

Set the class loader that will be used to load the various objects.

Parameters:

classLoader - the new class loader.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.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(java.lang.String[] args)
                 throws java.lang.Exception

For debugging. List non-default properties to the terminal and exit.

Throws:

java.lang.Exception

toDouble

public double toDouble()

Description copied from interface: Writable

Convert Writable to double. Whether this is supported depends on the specific writable.

Specified by:

toDouble in interface Writable

toFloat

public float toFloat()

Description copied from interface: Writable

Convert Writable to float. Whether this is supported depends on the specific writable.

Specified by:

toFloat in interface Writable

toInt

public int toInt()

Description copied from interface: Writable

Convert Writable to int. Whether this is supported depends on the specific writable.

Specified by:

toInt in interface Writable

toLong

public long toLong()

Description copied from interface: Writable

Convert Writable to long. Whether this is supported depends on the specific writable.

Specified by:

toLong in interface Writable