Package org.sosy_lab.common.configuration

Class ConfigurationBuilder

java.lang.Object

org.sosy_lab.common.configuration.ConfigurationBuilder

public final class ConfigurationBuilder
extends Object

Interface for constructing Configuration instances.

Method Summary

Modifier and Type	Method	Description
ConfigurationBuilder	addConverter(Class<?> cls, TypeConverter converter)	Add a type converter for options with a certain type.
Configuration	build()	Create a Configuration instance with the settings specified by method calls on this builder instance.
ConfigurationBuilder	clearOption(String name)	Reset a single option to its default value.
ConfigurationBuilder	copyFrom(Configuration sourceConfig)	Copy everything from an existing Configuration instance.
ConfigurationBuilder	copyOptionFrom(Configuration sourceConfig, String option)	Copy one single option from another Configuration instance, overwriting the value in this builder, if it is already set.
ConfigurationBuilder	copyOptionFromIfPresent(Configuration sourceConfig, String option)	Copy one single option from another Configuration instance, overwriting the value in this builder, if it is already set.
ConfigurationBuilder	loadFromFile(String filename)	Load options from a file with a "key = value" format.
ConfigurationBuilder	loadFromFile(Path file)	Load options from a file with a "key = value" format.
ConfigurationBuilder	loadFromResource(Class<?> contextClass, String resourceName)	Load options from a class-loader resource with a "key = value" format.
ConfigurationBuilder	loadFromSource(CharSource source, String basePath, String sourceName)	Load options from a CharSource with a "key = value" format.
ConfigurationBuilder	setOption(String name, String value)	Set a single option.
ConfigurationBuilder	setOptions(Map<String,String> options)	Add all options from a map.
ConfigurationBuilder	setPrefix(String newPrefix)	Set the optional prefix for new configuration.

Methods inherited from class java.lang.Object

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

Method Detail

setOption

@CanIgnoreReturnValue
public ConfigurationBuilder setOption(String name,
                                      String value)

Set a single option.

clearOption

@CanIgnoreReturnValue
public ConfigurationBuilder clearOption(String name)

Reset a single option to its default value.

setOptions

@CanIgnoreReturnValue
public ConfigurationBuilder setOptions(Map<String,String> options)

Add all options from a map.

setPrefix

@CanIgnoreReturnValue
public ConfigurationBuilder setPrefix(String newPrefix)

Set the optional prefix for new configuration.

copyFrom

@CanIgnoreReturnValue
public ConfigurationBuilder copyFrom(Configuration sourceConfig)

Copy everything from an existing Configuration instance. This also means that the new configuration object created by this builder will share the set of unused properties with the configuration instance passed to this class.

If this method is called, it has to be the first method call on this builder instance.

The converters registered on the given Configuration instance will have TypeConverter.getInstanceForNewConfiguration(Configuration) called on them and the result will be used as converter in the new configuration, except if overridden with addConverter(Class, TypeConverter).

copyOptionFrom

@CanIgnoreReturnValue
public ConfigurationBuilder copyOptionFrom(Configuration sourceConfig,
                                           String option)

Copy one single option from another Configuration instance, overwriting the value in this builder, if it is already set. The given Configuration instance needs to have a value for this option.

It is better to use this method instead of setOption(option, oldConfig.getProperty(option)), because it retains the mapping to the source of this value, which allows better error messages and resolving relative file paths.

Parameters:

sourceConfig - A configuration instance with a value for option.

option - The name of a configuration option.

Throws:

IllegalArgumentException - If the given configuration does not specify a value for the given option.

copyOptionFromIfPresent

@CanIgnoreReturnValue
public ConfigurationBuilder copyOptionFromIfPresent(Configuration sourceConfig,
                                                    String option)

Copy one single option from another Configuration instance, overwriting the value in this builder, if it is already set. If the given Configuration instance does not have a value for this option, nothing is changed.

It is better to use this method instead of setOption(option, oldConfig.getProperty(option)), because it retains the mapping to the source of this value, which allows better error messages and resolving relative file paths.

Parameters:

sourceConfig - A configuration instance.

option - The name of a configuration option.

loadFromSource

@CanIgnoreReturnValue
public ConfigurationBuilder loadFromSource(CharSource source,
                                           String basePath,
                                           String sourceName)
                                    throws IOException,
                                           InvalidConfigurationException

Load options from a CharSource with a "key = value" format.

A stream from this source is opened and closed by this method. This method may additionally access more files from the file system if they are included.

Parameters:

source - The source to read from.

basePath - The directory where relative #include directives should be based on.

sourceName - A string to use as source of the file in error messages or for other uses by the TypeConverter. This needs to be convertible into a Path.

Throws:

IOException - If the stream cannot be read.

InvalidConfigurationException - If the stream contains an invalid format.

loadFromFile

@CanIgnoreReturnValue
public ConfigurationBuilder loadFromFile(String filename)
                                  throws IOException,
                                         InvalidConfigurationException

Load options from a file with a "key = value" format.

Throws:

IOException - If the file cannot be read.

InvalidConfigurationException - If the file contains an invalid format.

loadFromFile

@CanIgnoreReturnValue
public ConfigurationBuilder loadFromFile(Path file)
                                  throws IOException,
                                         InvalidConfigurationException

Load options from a file with a "key = value" format.

Throws:

IOException - If the file cannot be read.

InvalidConfigurationException - If the file contains an invalid format.

loadFromResource

@CanIgnoreReturnValue
public ConfigurationBuilder loadFromResource(Class<?> contextClass,
                                             String resourceName)

Load options from a class-loader resource with a "key = value" format.

There must not be any #include directives in the resource.

Parameters:

contextClass - The class to use for looking up the resource.

resourceName - The name of the resource relative to contextClass.

Throws:

IllegalArgumentException - If the resource cannot be found or read, or contains invalid syntax or #include directives.

addConverter

@CanIgnoreReturnValue
public ConfigurationBuilder addConverter(Class<?> cls,
                                         TypeConverter converter)

Add a type converter for options with a certain type. This will enable the Configuration instance to parse strings into values of the given type and inject them just as the base option types.

As an alternative, the type of an option detail annotation (OptionDetailAnnotation) can be given. In this case, the type converter will be called for options annotated with this type.

Previous type converters for the same type will be overwritten (this also works for types usually handled by the Configuration class, however not for collection and array types).

The same converter may be used for several types.

Parameters:

cls - The type the type converter handles.

converter - A converter instance.

Returns:

this

build

@CheckReturnValue
public Configuration build()
                    throws InvalidConfigurationException

Create a Configuration instance with the settings specified by method calls on this builder instance.

This method resets the builder instance, so that after this method has returned it is exactly in the same state as directly after instantiation.

Throws:

InvalidConfigurationException - if calling TypeConverter.getInstanceForNewConfiguration(Configuration) fails