Autogenerate methods for built-in ops about imagej-ops

[dscho]

It would be slick, and should be doable, too, if we generate the OpService interface and the default implementation, between the compile and test phase.

The only two problems I see:

1. no non-generated classes in ij-ops could depend on OpService
2. it would be harder to stay SemVer-compliant because we do not change the API explicitly anymore

So what I would suggest is something different (similar to how we do things in ij1-patcher's HeadlessGenericDialog): have a "completeness" unit test that compares the OpService signature to the list of all the available built-in ops.

Hmm?

[ctrueden]

There is a chicken-and-egg problem with having those method signatures lives in imagej-ops itself: the autogenerator will need to depend on imagej-ops in order to know the available ops. I still think it would be valuable to have these method signatures somewhere though—perhaps a separate service component elsewhere?

[ctrueden]

I agree with @dscho that instead of autogenerating, let's add a "completeness" test that fails the build if the OpService interface is missing any core op signatures. That will be very doable. I am pulling this into an earlier milestone, because I think having the compile-safety will be extremely helpful in many ways.

[ctrueden]

I started work on this on the built-ins branch, which adds a fancy unit test that verifies all @BuiltIn-annotated methods of OpService cover the set of available Op implementations, and vice versa.

However, I ran into trouble code generating the method signatures including generics. I posted on SO for help.

Fortunately, this functionality is not strictly required for the checking feature, since the actual type matching (especially between generic Type and Type, which is what the unit test is able to use in this scenario) in OPS is pretty robust. In other words: we can manually do the work of adding all 300 method signatures needed, being careful to get the generic parameters right by hand, and the unit test should at least inform us whether we are "close enough" for things to generally work.

That said, it would be ideal if the unit test could spit out the exact missing method signature which needs to be added for each uncovered Op implementation. But doing that would require a deeper understanding of generics than I have right now.

[ctrueden]

I thought of an easier and more flexible way to do this. The type signature comparison logic I wrote (still pending on the built-ins branch) will still be useful, but in general we do not need to be slaves to whether everything matches. Better is for the @BuiltIn annotation to take an op=Class<? extends Op> parameter, which we can use to trivially determine which available ops do not have corresponding built-in method signatures.

The argument type matching on top of that is just gravy: it might be nice to warn if the signature could not possibly match the purported op class, but really that is an increasingly complex problem which does not need to be solved. On the contrary, our actual requirements are:

1. Know that each concrete Op plugin has at least one built-in method signature in the OpService. A parameter on @BuiltIn would accomplish this nicely.
2. Make sure that each built-in method signature has a corresponding unit test. Such unit tests should also be annotated, so that we can have a unit test which ensures this is the case (watch the Watchmen 😉).
3. Have the flexibility to add multiple signatures for the same Op, including signatures that will ultimately resolve to that op even if op reductions (#57) occur.
4. Avoid ever calling OpService#run from other built-in op implementations; rather, we should always call the appropriate built-in type-safe method, adding such built-in methods as they are needed. Then all ugly and confusing casts are encapsulated within the DefaultOpService and its helper classes.

I will keep working on the built-ins branch with the above requirements in mind. When that branch accomplishes these goals and is merged, this issue can be closed.

[ctrueden]

Commit 52be9fd, and PR #145, completed this work. Thanks to @awalter17 for her hard work there.

We do not actually autogenerate the signatures, but we unit test that they are present, and spit out helpful non-generified method bodies for the signatures which are missing.