Package org.sosy_lab.common.configuration

Class Configuration

java.lang.Object

org.sosy_lab.common.configuration.Configuration

public final class Configuration
extends Object

Immutable wrapper around a map with properties, providing useful access helper methods.

Method Summary

Modifier and Type	Method	Description
String	asPropertiesString()
static ConfigurationBuilder	builder()	Create a new Builder instance.
static Configuration	copyWithNewPrefix(Configuration oldConfig, String newPrefix)	Creates a copy of a configuration with just the prefix set to a new value.
static Configuration	defaultConfiguration()	Creates a configuration with all values set to default.
void	dumpUsedOptionsTo(PrintStream out)	Let this instance write human-readable information about every option that is used to the given stream.
void	enableLogging(LogManager pLogger)
static void	enableSecureModeGlobally()	Enable a secure mode, i.e., allow only injection of configuration options marked as secure.
static Configuration	fromCmdLineArguments(String[] args)	Construct a configuration object from the array of command line arguments.
static Map<Class<?>,TypeConverter>	getDefaultConverters()	Get the map of registered default TypeConverters.
Set<String>	getDeprecatedProperties()
@Nullable String	getProperty(String key)	Deprecated.
Set<String>	getUnusedProperties()
boolean	hasProperty(String key)	Deprecated.
void	inject(Object obj)	Inject the values of configuration options into an object.
void	inject(Object obj, Class<?> cls)	Use this method if the calling class is likely to be sub-classed, so that the options of the calling class get injected, not the options of the dynamic class type of the object.
<T> void	injectWithDefaults(T obj, Class<T> cls, T defaultsObject)	Same as inject(Object, Class), but if this Configuration instance does not contain a value for a requested configuration option, use the value that is set in the given defaultsInstance instead of the value that is set as default in the to-be-injected object.
void	recursiveInject(Object obj)	Call inject(Object, Class) for this object with its actual class and all super class that have an Options annotation.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static ConfigurationBuilder builder()

Create a new Builder instance.

enableSecureModeGlobally

public static void enableSecureModeGlobally()

Enable a secure mode, i.e., allow only injection of configuration options marked as secure. Once enabled, this can not be disabled.

defaultConfiguration

public static Configuration defaultConfiguration()

Creates a configuration with all values set to default.

copyWithNewPrefix

public static Configuration copyWithNewPrefix(Configuration oldConfig,
                                              String newPrefix)

Creates a copy of a configuration with just the prefix set to a new value.

getDefaultConverters

public static Map<Class<?>,TypeConverter> getDefaultConverters()

Get the map of registered default TypeConverters. These type converters are used whenever a new Configuration instance is created, except when the ConfigurationBuilder.copyFrom(Configuration) method is used.

For all instances in this map the method TypeConverter.getInstanceForNewConfiguration(Configuration) will be called before the type converter is actually added to a Configuration instance.

The returned map is mutable and changes have immediate effect on this class! Callers are free to add and remove mappings as they wish. However, as this is static state, this will affect all other callers as well! Thus, it should be used only with caution, for example to add default type converters in a large project at startup. It is discouraged to change this map, if the same effect can easily be achieved using ConfigurationBuilder.addConverter(Class, TypeConverter).

Returns:

A reference to the map of type converters used by this class.

enableLogging

public void enableLogging(LogManager pLogger)

dumpUsedOptionsTo

public void dumpUsedOptionsTo(PrintStream out)

Let this instance write human-readable information about every option that is used to the given stream.

getProperty

@Deprecated
public @Nullable String getProperty(String key)

Deprecated.

Get the value of an option. USE OF THIS METHOD IS NOT RECOMMENDED!

Use configuration injection with Option and inject(Object) instead. This provides type safety, documentation, logging etc.

hasProperty

@Deprecated
public boolean hasProperty(String key)

Deprecated.

Check whether an option has a specified value. USE OF THIS METHOD IS NOT RECOMMENDED!

Use configuration injection with Option and inject(Object) instead. This provides type safety, documentation, logging, default values, etc.

getUnusedProperties

public Set<String> getUnusedProperties()

getDeprecatedProperties

public Set<String> getDeprecatedProperties()

asPropertiesString

public String asPropertiesString()

inject

public void inject(Object obj)
            throws InvalidConfigurationException

Inject the values of configuration options into an object. The class of the object has to have a Options annotation, and each field to set / method to call has to have a Option annotation.

Supported types for configuration options:

• all primitive types and their wrapper types
• all enum types
• String and arrays of it
• File and Path (the field FileOption.value() is required in this case!)
• Class<Something>
• Charset
• Level
• Pattern
• arbitrary factory interfaces as supported by Classes.createFactory(TypeToken, Class)
• arrays of the above types
• AnnotatedValue with types of the above as value type (users can specify an annotation string after a "::" separator)
• collection types Iterable, Collection, List, Set, SortedSet, Multiset, and EnumSet of the above types

For the collection types an immutable instance will be created and injected. Their type parameter has to be one of the other supported types. For collection types and arrays the values of the configuration option are assumed to be comma separated.

Parameters:

obj - The object in which the configuration options should be injected.

Throws:

InvalidConfigurationException - If the user specified configuration is wrong.

inject

public void inject(Object obj,
                   Class<?> cls)
            throws InvalidConfigurationException

Use this method if the calling class is likely to be sub-classed, so that the options of the calling class get injected, not the options of the dynamic class type of the object.

Parameters:

cls - The static class type of the object to inject.

Throws:

InvalidConfigurationException

See Also:

inject(Object)

injectWithDefaults

public <T> void injectWithDefaults(T obj,
                                   Class<T> cls,
                                   T defaultsObject)
                            throws InvalidConfigurationException

Same as inject(Object, Class), but if this Configuration instance does not contain a value for a requested configuration option, use the value that is set in the given defaultsInstance instead of the value that is set as default in the to-be-injected object. This can be used to create a copy of an object but with some options changed according to this Configuration instance.

Note that this only works for configuration options that are specified as fields, not for those specified as setters.

Parameters:

obj - The to-be-injected instance.

cls - The static class type of the object to inject.

defaultsObject - The instance from which default values should be read.

Throws:

InvalidConfigurationException

recursiveInject

public void recursiveInject(Object obj)
                     throws InvalidConfigurationException

Call inject(Object, Class) for this object with its actual class and all super class that have an Options annotation.

Parameters:

obj - The object in which the configuration options should be injected.

Throws:

InvalidConfigurationException - If the user specified configuration is wrong.

toString

public String toString()

Overrides:

toString in class Object

fromCmdLineArguments

public static Configuration fromCmdLineArguments(String[] args)
                                          throws InvalidConfigurationException

Construct a configuration object from the array of command line arguments.

The input format is as follows:

 
   --option=Value
 
 

Parameters:

args - Command line arguments

Returns:

Constructed Configuration instance

Throws:

InvalidConfigurationException - On incorrect format or when configuration options for Configurations class are invalid