Update README and package javadoc to reflect refactored API

tpietzsch · tpietzsch · commit bc1a2ffaee28 · 2020-06-11T23:25:13.000+02:00
Also add org.scijava.optional.examples.Playground that has the full
implementation of the example given in the README and package javadoc.
diff --git a/README.md b/README.md
@@ -10,8 +10,8 @@ For example, `FactoryA` should take `FactoryAOptions` and
 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 an `FactoryAOptions`,
-and `FactoryBOptions::a` should return an `FactoryBOptions` to allow chaining more parameters of
+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 scijava-optional, this can be achieved as follows:
@@ -21,26 +21,26 @@ one exposing methods to set the parameters, one exposing methods to retrieve par
 
 For setting:
 ```java
-interface OptionA<T extends OptionA<T>> extends Options<T> {
+interface OptionA<T> extends Options<T> {
     default T a(int a) {
-        return add("a", a);
+        return setValue("a", a);
     }
 }
 ```
 where the `a()` method records the parameter value (with key `"a"`) via the
-`add()` method of the `Options` super-interface.
+`setValue()` method of the `Options` super-interface.
 
 For getting:
 ```java
 interface ValueA extends Values {
     ...
-    default int a() {}
-        return value( "a", 0 );
+    default int a() {
+        return getValueOrDefault( "a", 0 );
     }
 }
 ```
 where the `a()` method returns the parameter value (with key `"a"` and default value `0`)
-via the `value()` method of the `Values` super-interface.
+via the `getValueOrDefault()` method of the `Values` super-interface.
 
 Finally, the implementation of `FactoryAOptions` derives from `AbstractOptions` and all desired
 subsets of options
@@ -49,17 +49,12 @@ public class FactoryAOptions
          extends AbstractOptions< FactoryAOptions >
          implements OptionA< FactoryAOptions >, ...
 {
-    static class FactoryAValues
+    public class FactoryAValues
             extends AbstractValues
             implements ValueA, ...
-    {
-          ...
-          public FactoryAValues(FactoryAOptions options) {
-              super( options );
-          }
-    }
+    {}
 
-    public final FactoryAValues values = new FactoryAValues(this);;
+    public final FactoryAValues values = new FactoryAValues();
 
     // =======================================================================
  
@@ -76,49 +71,36 @@ public class FactoryAOptions
     protected FactoryAOptions copyOrThis() {
         return new FactoryAOptions(this);
     }
-
-    // =======================================================================
- 
-    // The following is not necessary, but can be overridden like this
-    // to make it show up more nicely in IDE auto-complete
- 
-    @Override
-    public FactoryAOptions a(int a) {
-        return OptionA.super.a(a);
-    }
 }
 ```
 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
+for the values. This is be achieved by overriding the `forEach()` methods in the `Values` interfaces and
+implementation
 ```java
 interface ValueA extends Values {
-    default void buildToString(AbstractValues.ValuesToString sb) {
-        sb.append("a", a());
+    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 value("a", 0);
+        return getValueOrDefault("a", 0);
     }
 }
 ```
 and
 ```java
-static class FactoryAValues
+public class FactoryAValues
         extends AbstractValues
         implements ValueA, ...
 {
     @Override
-    public String toString() {
-        final ValuesToString sb = new ValuesToString();
-        ValueA.super.buildToString(sb);
-        return sb.toString();
-    }
-
-    public FactoryAValues(FactoryAOptions options) {
-        super(options);
+    default void forEach(BiConsumer<String, Object> action) {
+        ValueA.super.forEach( action );
+        // and so on, for other implemented Values interfaces
     }
 }
 ```
diff --git a/src/main/java/org/scijava/optional/package-info.java b/src/main/java/org/scijava/optional/package-info.java
@@ -7,51 +7,46 @@
  * expose an optional parameter "{@code int a}" with the same meaning and default values.
  * <p>
  * To maintain convenience and type-safety, both {@code FactoryAOptions} and {@code FactoryBOptions} should expose
- * a method {@code a(int)} to set the optional parameter. But {@code FactoryAOptions::a} should return an {@code FactoryAOptions},
- * and {@code FactoryBOptions::a} should return an {@code FactoryBOptions} to allow chaining more parameters of
+ * a method {@code a(int)} to set the optional parameter. But {@code FactoryAOptions::a} should return a {@code FactoryAOptions},
+ * and {@code FactoryBOptions::a} should return a {@code FactoryBOptions} to allow chaining more parameters of
  * {@code FactoryAOptions} and {@code FactoryBOptions} respectively, while retaining the type of the builder.
  * <p>
  * Using this package, this can be achieved as follows:
  * <p>
  * Each subset of optional parameters ("{@code int a}" in the above example) is implemented as two interfaces,
- * one exposing methods to set the parameters, one exposing methods to retrieve parameter values.
+ * one exposing methods to set the parameters, the other exposing methods to retrieve parameter values.
  * <p>
  * For setting:
  * <pre>{@code
- * interface OptionA< T extends OptionA< T > > extends Options< T > {
+ * interface OptionA<T> extends Options<T> {
  *     default T a( int a ) {
- *         return add( "a", a );
+ *         return setValue( "a", a );
  *     }
  * }}</pre> where the {@code a()} method records the parameter value (with key {@code "a"}) via the
- * {@code add()} method of the {@code Options} super-interface.
+ * {@code setValue()} method of the {@code Options} super-interface.
  * <p>
  * For getting:
  * <pre>{@code
  * interface ValueA extends Values {
  *     ...
  *     default int a() {}
- *         return value( "a", 0 );
+ *         return getValueOrDefault( "a", 0 );
  *     }
  * }}</pre> where the {@code a()} method returns the parameter value (with key {@code "a"} and default value {@code 0})
- * via the {@code value()} method of the {@code Values} super-interface.
+ * via the {@code getValueOrDefault()} method of the {@code Values} super-interface.
  * <p>
  * Finally, the implementation of {@code FactoryAOptions} derives from {@code AbstractOptions} and all desired
  * subsets of options
  * <pre>{@code public class FactoryAOptions
- *          extends AbstractOptions< FactoryAOptions >
- *          implements OptionA< FactoryAOptions >, ...
+ *          extends AbstractOptions<FactoryAOptions>
+ *          implements OptionA<FactoryAOptions>, ...
  * {
- *     static class FactoryAValues
+ *     public class FactoryAValues
  *             extends AbstractValues
  *             implements ValueA, ...
- *     {
- *           ...
- *           public FactoryAValues( final FactoryAOptions options ) {
- *               super( options );
- *           }
- *     }
+ *     {}
  *
- *     public final FactoryAValues values = new FactoryAValues( this );
+ *     public final FactoryAValues values = new FactoryAValues();
  *
  *     // =======================================================================
  *
@@ -60,52 +55,39 @@
  *
  *     public FactoryAOptions() {}
  *
- *     private FactoryAOptions(FactoryAOptions that) {
- *         super(that);
+ *     private FactoryAOptions( FactoryAOptions that ) {
+ *         super( that );
  *     }
  *
  *     \@Override
  *     protected FactoryAOptions copyOrThis() {
- *         return new FactoryAOptions(this);
- *     }
- *
- *     // =======================================================================
- *
- *     // The following is not necessary, but can be overridden like this
- *     // to make it show up more nicely in IDE auto-complete
- *
- *     \@Override
- *     public FactoryAOptions a(int a) {
- *         return OptionA.super.a(a);
+ *         return new FactoryAOptions( this );
  *     }
  * }}</pre> The parameter values are exposed through inner class {@code FactoryAValues} that derives from {@code AbstractValues}
  * and all desired subsets of option values.
  * <p>
  * The only thing that has been omitted from the above example is the parts that provide a nice {@code toString} implementation
- * for the values. This is be achieved by
+ * for the values. This is be achieved by overriding the {@code forEach()} methods in the {@code Values} interfaces and
+ * implementation
  * <pre>{@code
  * interface ValueA extends Values {
- *     default void buildToString( AbstractValues.ValuesToString sb ) {
- *         sb.append( "a", a() );
+ *     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 value( "a", 0 );
+ *         return getValueOrDefault( "a", 0 );
  *     }
  * }}</pre> and <pre>{@code
- * static class FactoryAValues
+ * public class FactoryAValues
  *         extends AbstractValues
  *         implements ValueA, ...
  * {
  *     \@Override
- *     public String toString() {
- *         final ValuesToString sb = new ValuesToString();
- *         ValueA.super.buildToString( sb );
- *         return sb.toString();
- *     }
- *
- *     public FactoryAValues( final FactoryAOptions options ) {
- *         super( options );
+ *     public void forEach( BiConsumer<String, Object> action )
+ *         ValueA.super.forEach( action );
+ *         // and so on, for other implemented Values interfaces
  *     }
  * }}</pre>
  */
diff --git a/src/test/java/org/scijava/optional/examples/Playground.java b/src/test/java/org/scijava/optional/examples/Playground.java
@@ -0,0 +1,107 @@
+package org.scijava.optional.examples;
+
+import java.util.function.BiConsumer;
+import org.scijava.optional.AbstractOptions;
+import org.scijava.optional.Options;
+import org.scijava.optional.Values;
+
+public class Playground
+{
+	interface OptionA< T > extends Options< T >
+	{
+		default T a( final int a )
+		{
+			return setValue( "a", a );
+		}
+
+		interface ValueA extends Values
+		{
+			default void forEach( BiConsumer< String, Object > action )
+			{
+				action.accept( "a", a() );
+			}
+
+			default int a()
+			{
+				return getValueOrDefault( "a", 0 );
+			}
+		}
+	}
+
+	// ====================================================================================== //
+
+	interface OptionB< T > extends Options< T >
+	{
+		default T b( final int b )
+		{
+			return setValue( "b", b );
+		}
+
+		interface ValueB extends Values
+		{
+			default void forEach( BiConsumer< String, Object > action )
+			{
+				action.accept( "b", b() );
+			}
+
+			default int b()
+			{
+				return getValueOrDefault( "b", 0 );
+			}
+		}
+	}
+
+	// ====================================================================================== //
+
+	static class FactoryAOptions extends AbstractOptions< FactoryAOptions > implements OptionA< FactoryAOptions >, OptionB< FactoryAOptions >
+	{
+		class FactoryAValues extends AbstractValues implements ValueA, ValueB
+		{
+			@Override
+			public void forEach( BiConsumer< String, Object > action )
+			{
+				ValueA.super.forEach( action );
+				ValueB.super.forEach( action );
+			}
+		}
+
+		public final FactoryAValues values = new FactoryAValues();
+
+		/*
+		 * The following methods result in immutable FactoryAOptions instances,
+		 * where options.a(3) results in a new FactoryAOptions instance with the
+		 * same parameters as options, except a=3.
+		 *
+		 * If in-place modification of the options builder is desired,
+		 * the following methods should be left out. Then, options.a(3) modifies
+		 * the options instance, setting a=3
+		 */
+
+		public FactoryAOptions()
+		{}
+
+		private FactoryAOptions( FactoryAOptions that )
+		{
+			super( that );
+		}
+
+		@Override
+		protected FactoryAOptions copyOrThis()
+		{
+			return new FactoryAOptions( this );
+		}
+	}
+
+	static < O extends OptionA< O > & OptionB< O > > void factory( final O options )
+	{
+		System.out.println( "(factory) options = " + options );
+	}
+
+	public static void main( final String[] args )
+	{
+		final FactoryAOptions options = new FactoryAOptions().a( 3 ).b( 2 );
+		System.out.println( "options = " + options );
+		factory( options );
+		System.out.println( "options.values = " + options.values );
+	}
+}
