Class Options

java.lang.Object
java.util.AbstractMap<String,Object>
java.util.HashMap<String,Object>
org.refcodes.ontology.Taxonomy
org.refcodes.runtime.Settings
org.refcodes.runtime.Options
All Implemented Interfaces:
Serializable, Cloneable, Map<String,Object>, Clearable, EmptyAccessor, org.refcodes.ontology.Ontology, Diagnosable, Schemable<DiagnosticOptions>, Containable, ImmutableTable<String,Object>, ImmutableTable.MutableTable<String,Object>, Keys<String,Object>, Keys.MutableKeys<String,Object>, Keys.MutableValues<String,Object>
Direct Known Subclasses:
DiagnosticOptions
public class Options extends Settings
The Options class serves as a generic information container for providing arbitrary, optional parameters and interfaces with the runtime environment: The Options container provides flexible, extensible configuration lookup with support for explicit values, JVM system properties, and environment variables.

It is typically used when additional parameters are required that are not known in advance and must be supplied without extending or breaking the existing API.

Extensions of this class should implement type safe convenience methods for retrieving their specific option values. These methods might also take system properties or environment variables into account, depending on the according implementation and requirements.

Options primarily behave like a Map and allows explicit option values to be set programmatically. In addition, when an option is requested via a getter and no explicit value is present, the lookup transparently falls back to external configuration sources.

Note: As of environment variable lookup and system property mapping, make sure to provide a sound namespace for the option keys: The first part(s) of your option keys should identify your namespace!

Resolution order

Option values are resolved in the following order:

  1. Explicitly set option value (stored in this Options instance)
  2. JVM system property
  3. Environment variable

If none of these sources provides a value, null is returned.

System property key mapping

When falling back to JVM system properties, the option key is transformed according to the following rules:

  • camelCase word boundaries are converted to dot separators
  • underscore characters (_) are replaced by dots (.)
  • the resulting key is converted to lower case

Example: 

option key:    maxBufferSize
system key:    max.buffer.size

Environment variable key mapping

When falling back to environment variables, the option key is transformed according to the following rules:

  • camelCase word boundaries are converted to underscore separators
  • dot characters (.) are replaced by underscores (_)
  • the resulting key is converted to upper case

Example: 

option key:    maxBufferSize
environment:   MAX_BUFFER_SIZE

Design intent

This class is intended as a lightweight configuration bridge between programmatic configuration and externally supplied parameters, especially for implementation-specific or extensible subsystems where not all options can be known in advance.

The fallback to system properties and environment variables is deliberately transparent but deterministic. The lookup rules are fixed and documented so that configuration remains predictable and debuggable.

Note that this class does not perform type conversion beyond the string-based lookup provided by system properties and environment variables. Callers are responsible for interpreting option values according to their expected type.

This class is not intended as a general-purpose configuration framework, but as an infrastructure-level utility for SDKs and toolkits that require flexible, low-friction option passing.

Extensions

Subclasses of Options typically expose a static builder() factory method which returns a specialized Options.Builder implementation. This builder is used to configure and finally create an instance of the extended Options type.

During Options.Builder.build(), the builder invokes the protected constructor Options(Builder) of the extended Options class in order for the configured option values to be transfered into the newly created instance. Both the builder and the extended Options type usually provide type safe convenience methods for setting and retrieving supported options.

Subclasses may additionally define an enumeration implementing the DiagnosticOptions interface. Such an enumeration can be used to declare well known options and to provide additional diagnostic metadata, such as descriptions or option's types, which is exposed via the toSchema() method. Using an enumeration also helps to avoid key and type mismatches when working with known options which provide a type. The constructor of subclassed Options classes then usually invokes the (super) Options(Builder, Class) constructor to provide the Builder alongside the configuration enumeration for construction.

See Also:

  • Constructor Details

    • Options

      public Options()
      Creates an empty Options instance.

      This constructor is intended for quick experimentation or ad-hoc usage. More sophisticated subclasses typically provide type-safe accessors for their supported options and expose a static builder() factory method.

      Such builders usually extend the Options.Builder class and configure option values before creating the final Options instance via the protected Options(Builder) constructor.

      Subclasses may additionally register known options by supplying enumerations to register(Class) or by using the Options(Builder, Class) constructor in order to enrich diagnostic output and enable type-safe configuration.

    • Options

      protected Options(Options.Builder aBuilder)
      Instantiates a new instance from the given builder.
      Parameters:
      aBuilder - The builder from which to populate the this instance.

    • Options

      protected Options(Options.Builder aBuilder, Class<? extends Enum<?>> aOptions)
      Instantiates a new instance from the given builder and register options provided by the configuration enumeration.

      In case the provided enumeration implements the Option interface, the the according metadata is used to enrich diagnostic output (as of toSchema() and enable type-safe configuration of the Options instance (as of the overridden put(String, Object) method).

      Parameters:
      aBuilder - The builder from which to populate the this instance.
      aOptions - The enumeration describing the options.

  • Method Details