Package org.sosy_lab.common.configuration

@CheckReturnValue @ParametersAreNonnullByDefault @ReturnValuesAreNonnullByDefault @FieldsAreNonnullByDefault package org.sosy_lab.common.configuration

Java-Config is a library for injecting configuration options in a decentralized way.

Configuration objects can be generated either from .properties configuration files, or from command line options. The usability is geared towards configuration files, but command line generation is also supported.

The library is conceptually similar to GFlags and allows arbitrary option injection throughout used classes.

Annotating classes with options

The example below demonstrates defining options for a class:

 
 @Options(prefix="grep")
 public class Grep {
   @Option(description="Ignore case of the query", secure=true)
   private boolean ignoreCase = false;

   @Option(description="File to search", secure=true)
   @FileOption(Type.REQUIRED_INPUT_FILE)
   private PathCounterTemplate haystack = null;

   public Grep(Configuration c) {
     c.inject(this);
   }

   public boolean search(String needle) {
      // ... search for a needle in a haystack.
   }
 
 

Note the following features:

• @Option annotations are used to define various options associated with a class. Options are decentralized, the only requirement is that the Configuration object is injected (preferably in the constructor).
• The fields defining options can be private. The injector contains reflection calls to set them to the arbitrary file.
• Normally, the type of the option is defined by the type of the field. For complex cases (e.g. files) additional decorators are used.
• Option name is either derived from the field name (prefixed with a base prefix), or set explicitly in the Option annotation.

Configuration options instance can be constructed in three different ways:

• Most common if you have a lot of options and a large project: load them from the configuration file. See ConfigurationBuilder.loadFromFile(java.lang.String) for details.
• Useful for smaller programs: construct an instance from command line options. See Configuration.fromCmdLineArguments(java.lang.String[]).
• Most rare, useful for small scripts: construct an instance by hand, using ConfigurationBuilder.

Related Packages

Package	Description
org.sosy_lab.common	This package contains general utilities that do not fit anywhere else.
org.sosy_lab.common.configuration.converters	This package provides the possibility to convert String values into appropriate objects of certain types.

Class	Description
AnnotatedValue<T>	Immutable container that stores a value and an optional string.
ClassOption	This is an optional annotation for all configuration options (i.e., elements that are annotated with Option) whose type is Class.
Configuration	Immutable wrapper around a map with properties, providing useful access helper methods.
ConfigurationBuilder	Interface for constructing Configuration instances.
FileOption	This is an annotation providing more features for options of types File and Path.
FileOption.Type
IntegerOption	This is an optional annotation for all configuration options (i.e., elements that are annotated with Option) whose type is an integer number (i.e., int, long, Integer and Long):
InvalidConfigurationException	Exception class to signal that something is wrong in the user-specified configuration.
Option	An annotation to mark fields or methods which should get configuration values injected.
OptionAnnotationProcessor	Annotation processor for checking constraints on Option and Options annotations.
OptionCollector	This class collects all Options of a program.
OptionDetailAnnotation	This is a meta annotation that marks other annotation which may be used in conjunction with Option to provide more information for a specific option type.
Options	Annotation for a class which has fields or methods with an Option annotation.
TimeSpanOption	This is an annotation for all integer options that specify some sort of time duration (e.g., a timeout).