Class Options

java.lang.Object
java.util.AbstractMap<String,Object>
java.util.HashMap<String,Object>
org.refcodes.runtime.Options
All Implemented Interfaces:
Serializable, Cloneable, Map<String,Object>, Diagnosable, org.refcodes.schema.Schemable<DiagnosticOptions>
Direct Known Subclasses:
DiagnosticOptions
public class Options extends HashMap<String,Object> implements Diagnosable
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 registerOptions(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<?>> aConfiguration)
      Instantiates a new instance from the given builder and register options provided by the configuration enumeration.
      Parameters:
      aBuilder - The builder from which to populate the this instance.
      aConfiguration - The enumeration describing the options.

  • Method Details

    • get

      public Object get(Enum<?> aKey)
      A convenience method that returns the value associated with the given enumeration's name (as of Enum.name().
      Parameters:
      aKey - The enumeration representing the key by resolving to its name (as of Enum.name().
      Returns:
      The resolved option value, or null if none is available.
      See Also:

    • getOr

      public Object getOr(Enum<?> aKey, Object aValue)
      A convenience method that returns the value associated with the given enumeration's name (as of Enum.name(), or a default value if the key is not present.
      Parameters:
      aKey - The enumeration representing the key by resolving to its name (as of Enum.name().
      aValue - The default value to return if the option is absent.
      Returns:
      The value or aValue if not present.
      See Also:

    • get

      public <T> T get(Enum<?> aKey, Class<T> aType)
      A convenience method that returns the value associated with the given enumeration's name (as of Enum.name() if it matches the requested type.
      Type Parameters:
      T - The expected type.
      Parameters:
      aKey - The enumeration representing the key by resolving to its name (as of Enum.name().
      aType - The expected value's type.
      Returns:
      The typed value, or null if the key is not present or the value is of a different type.
      See Also:

    • getOr

      public <T> T getOr(Enum<?> aKey, Class<T> aType, T aValue)
      A convenience method that returns the value associated with the given enumeration's name (as of Enum.name() if it matches the requested type, or a default value otherwise.
      Type Parameters:
      T - The expected type.
      Parameters:
      aKey - The enumeration representing the key by resolving to its name (as of Enum.name().
      aType - The expected value's type.
      aValue - The default value to return if the option is absent or of a different type.
      Returns:
      The typed value or aValue if not present or incompatible.

    • get

      public <T> T get(String aKey, Class<T> aType)
      Returns the value associated with the given key if it matches the requested type.
      Type Parameters:
      T - The expected type.
      Parameters:
      aKey - The option's key.
      aType - The expected value's type.
      Returns:
      The typed value, or null if the key is not present or the value is of a different type.

    • getOr

      public <T> T getOr(String aKey, Class<T> aType, T aValue)
      Returns the value associated with the given key if it matches the requested type, or a default value otherwise.
      Type Parameters:
      T - The expected type.
      Parameters:
      aKey - The option's key.
      aType - The expected value's type.
      aValue - The default value to return if the option is absent or of a different type.
      Returns:
      The typed value or aValue if not present or incompatible.

    • get

      public Object get(Object aKey)
      Retrieves the value associated with the given option key.

      If no explicit value is present in this Options instance, the lookup transparently falls back to external configuration sources in the following order:

      1. JVM system property (derived from the option by calling SystemProperty.toSystemPropertyName(String))
      2. Environment variable (derived from the option key by calling EnvironmentVariable.toEnvironmentVariableName(String))

      If no value is found, null is returned.

      Specified by:
      get in interface Map<String,Object>
      Overrides:
      get in class HashMap<String,Object>
      Parameters:
      aKey - The option key
      Returns:
      The resolved option value, or null if none is available.

    • put

      public Object put(Enum<?> aKey, Object aValue)
      A convenience method that puts the value associated with the given enumeration's name (as of Enum.name().
      Parameters:
      aKey - The enumeration representing the key by resolving to its name (as of Enum.name().
      aValue - The value to set for the key.
      Returns:
      The previously set value or null if not present.
      See Also:

    • put

      public Object put(String aKey, Object aValue)
      In case options with type information were registered, type conformance is enforced.
      Specified by:
      put in interface Map<String,Object>
      Overrides:
      put in class HashMap<String,Object>

    • toSchema

      public org.refcodes.schema.Schema toSchema()
      Specified by:
      toSchema in interface org.refcodes.schema.Schemable<DiagnosticOptions>

    • toSchema

      public OptionsSchema toSchema(DiagnosticOptions aOptions)
      Specified by:
      toSchema in interface org.refcodes.schema.Schemable<DiagnosticOptions>

    • builder

      public static Options.Builder builder()
      Creates a new Options.Builder for constructing Schema instances.
      Returns:
      A new builder instance

    • registerOptions

      protected void registerOptions(Class<? extends Enum<?>> aConfiguration)
      Register options provided by the configuration enumeration.
      Parameters:
      aConfiguration - The enumeration describing the options.

    • getOption

      protected org.refcodes.runtime.Options.Option getOption(String aKey)
      Returns the Options.Option associated with the given key.
      Parameters:
      aKey - The option's key
      Returns:
      The Options.Option or null if not found.