Package org.scijava.optional

Helpers for implementing optional parameters in a builder-like class.

The scenario is that certain methods take optional parameters, subsets of which can overlap. For example, FactoryA should take FactoryAOptions and FactoryB should take FactoryBOptions, where both FactoryAOptions and FactoryBOptions expose an optional parameter "int a" with the same meaning and default values.

To maintain convenience and type-safety, both FactoryAOptions and FactoryBOptions should expose a method a(int) to set the optional parameter. But FactoryAOptions::a should return a FactoryAOptions, and FactoryBOptions::a should return a FactoryBOptions to allow chaining more parameters of FactoryAOptions and FactoryBOptions respectively, while retaining the type of the builder.

Using this package, this can be achieved as follows:

Each subset of optional parameters ("int a" in the above example) is implemented as two interfaces, one exposing methods to set the parameters, the other exposing methods to retrieve parameter values.

For setting:

 interface OptionA<T> extends Options<T> {
     default T a( int a ) {
         return setValue( "a", a );
     }
 }

where the a() method records the parameter value (with key "a") via the setValue() method of the Options super-interface.

For getting:

 interface ValueA extends Values {
     ...
     default int a() {}
         return getValueOrDefault( "a", 0 );
     }
 }

where the a() method returns the parameter value (with key "a" and default value 0) via the getValueOrDefault() method of the Values super-interface.

Finally, the implementation of FactoryAOptions derives from AbstractOptions and all desired subsets of options

 public class FactoryAOptions
          extends AbstractOptions<FactoryAOptions>
          implements OptionA<FactoryAOptions>, ...
 {
     public class FactoryAValues
             extends AbstractValues
             implements ValueA, ...
     {}

     public final FactoryAValues values = new FactoryAValues();

     // =======================================================================

     // If in-place modification of the options builder is desired,
     // the following methods should be left out.

     public FactoryAOptions() {}

     private FactoryAOptions( FactoryAOptions that ) {
         super( that );
     }

     \@Override
     protected FactoryAOptions copyOrThis() {
         return new FactoryAOptions( this );
     }
 }

The parameter values are exposed through inner class FactoryAValues that derives from AbstractValues and all desired subsets of option values.

The only thing that has been omitted from the above example is the parts that provide a nice toString implementation for the values. This is be achieved by overriding the forEach() methods in the Values interfaces and implementation

 interface ValueA extends Values {
     default void forEach( BiConsumer<String, Object> action ) {
         action.accept( "a", a() );
         // and so on, for other parameters defined in this Values interface
     }

     default int a() {
         return getValueOrDefault( "a", 0 );
     }
 }

and

 public class FactoryAValues
         extends AbstractValues
         implements ValueA, ...
 {
     \@Override
     public void forEach( BiConsumer<String, Object> action )
         ValueA.super.forEach( action );
         // and so on, for other implemented Values interfaces
     }
 }