Enable Optional Parameters Using Reduction

[gselzer]

This PR introduces the ability to declare optional parameters in an Op's functional method using the @Optional annotation. The motivation behind this implementation was to maintain from ImageJ Ops the ability to declare optional parameters without the complexity of field injection.

Once one parameter (or more) has been declared optional for some Op, scijava ops will create a set of ReducedOpInfos for that Op; if an Op has n optional parameters, we will then have n+1 OpInfos that delegate to that Op (n of which being ReducedOpInfos). These ReducedOpInfos can then be matched, just as any other OpInfo. We maintain ImageJ Ops' behavior of matching subsets of optional parameters in a left-to-right manner; this means that if there is an OpMethod

public Double foo(Double a, @Optional Double b, @Optional Double c) {}

we can match this Op using:

• a
• a and b
• a, b, and c.

We do not allow the matching of a and c, as when b and c are the same type, passing a Double would provide no indication whether that Double should be assigned to b or c. To be deterministic we assume that optional parameters are always left off right to left.

Using this paradigm, users can write a class Op with optional parameters as

@Plugin(type = Op.class, name = "foo")
public  class OptionalArgClass implements BiFunction<Double, Double, Double> {
  public Double apply( Double in1, @Optional in2) {
    if (in2 == null) in2 = <reasonable default>;
    ...
  }
}

When this Op is called without the optional parameter, the ReducedOpInfo will use Javassist to create a wrapper for OptionalArgClass, passing null for each optional parameter that is omitted in the matched ReducedOpInfo. note that the Op author is then responsible for null-checking any optional arguments.

Using the OpBuilder syntax, this Op can then be called using either

Double d1 = 1.0;
Double d2 = 2.0;
Double o = ops.op("foo").input(d1, d2).outType(Double.class).apply();

or

Double d1 = 1.0;
Double o = ops.op("foo").input(d1).outType(Double.class).apply();

Ops written as methods can similarly be written with optional parameters:

@OpMethod(names = "bar", type = BiFunction.class)
public Double barMethod(Double in1, @Optional Double in2) {
  if (in2 == null) in2 = <reasonable default>;
  ...
}

When writing an Op as a Field, there are two options. One can write the Op as either an anonymous Class:

@OpField(names = "foobar")
public final BiFunction<Double, Double, Double> foobar = new BiFunction<> {
  public Double apply( Double in1, @Optional in2) {
    if (in2 == null) in2 = <reasonable default>;
    ...
  }
}

or, with the help of a specialized interface, using a lambda:

public interface BiFunctionWithOptional<I1, I2, I3, O> extends Functions.Arity3<I1, I2, I3, O> {
  @Override  
  public O apply(I1 in1, I2 in2, @Optional I3 in3);
}

@OpField(names = "baz")
public final BiFunctionWithOptional<Double, Double, Double, Double> baz = (in1, in2, in3) -> {
  if (in3 == null) in3 = <reasonable default>;
  ...
};

To promote extensibility, each OpInfo is reduced using a InfoReducer plugin. InfoReducers are designed to be able to reduce OpInfos backed by one of a set of functional types (for example, a FunctionReducer should reduce all Functions). For each functional type an InfoReducer can reduce, it should be able to produce an OpInfo for any number of optional parameters. So if, for example, an InfoReducer is able to reduce a Functions.Arity3, it should be able to reduce that Arity3 into a BiFunction, a Function, and a Producer. OpInfo reduction is performed at plugin discovery time, and the Javassist wrapper is created when the Op is matched.

Closes scijava/scijava#14

[elect86]

What about default parameters in Kotlin?

[gselzer]

What about default parameters in Kotlin?

How does that help us, unless we convert our entire codebase to Kotlin?

Tangentially, I suppose that, if one wrote an Op in Kotlin, we could have a KotlinOpInfo, and then a ReducedKotlinOpInfo or something that knows how to create an Op from a chunk of Kotlin. I think that could coexist with our current Java code? Of course, you'd probably want to house that in some SciJava Ops Kotlin module or something...

[ctrueden]

Closing in favor of #58.