Java language support redux

[kelnos]

Based on & supersedes #176

Not ready for merge, but here's what we've got so far. I was planning to break this up into just Java language support and then client/framework support, but I've found that, because of my lack of familiarity with things, the only way I've been able to make sure everything works and also figure out what things need to be refactored and added has been to actually implement full protocol object and client support. So...

• Make several Scala-specific things optional (implicits, package objects, etc.)
• Add support for auxiliary class definitions.
• Define initial JavaLanguage abstraction
• Define JavaInterp
• Jackson protocol interpreters:
  • EnumProtocolTermInterp
  • ModelProtocolTermInterp
  • ArrayProtocolTermInterp
  • ProtocolSupportTermInterp
  • PolyProtocolTermInterp
• Framework interpreters:
  • ClientTermInterp for AsyncHttpClient (nearly done; only missing query/form/body param support)
  • ServerTermInterp for Dropwizard
  • FrameworkInterp for AHC/DW
  • CodegenApplication for DW
• Provide an additional command to run the Java generator against example specifications

After I'm finished I can take a stab out of separating this into 3 PRs if you think it's worth it: 1) structural changes/refactoring, 2) base Java language support, and 3) DW server/AHC client/framework support.

(Note that I plan to force-push to this branch quite a bit, so don't base anything on it just yet.)

[blast-hardcheese]

"read only" means different things from the server side and client side. I haven't come up with a good way to represent this yet. We should want either use case to work correctly, and getting the response from a server and giving it to a client should work without resetting the read-only values to null.

[blast-hardcheese]

x-scala-type: com.example.List would also trigger this as well, right? Is the full classpath known at this point?

[kelnos]

It would, unfortunately. Should try to qualify it I guess?

[blast-hardcheese]

Yeah -- an additional question is that we don't support showables for implementers of an interface, preventing java.util.List from actually being registered as showable, fwict

[kelnos]

There's nothing to prevent anyone from registering any concrete (or non-concrete) class as a Showable, but yeah, List is handled in a special way with behavior a user couldn't add. Unfortunately javaparser has no idea what a List is (or, better, what an Iterable is), so I'm not sure what to do here.

[blast-hardcheese]

This means any parameterized type will not be able to integrate, right? If Showable<A> had both String show(A o) and Boolean canShow(A o), I could

shower.register(classOf[List[_]], new Showable[List[_]] {
    def canShow(l: List[_]): Boolean = l.headOption.fold(true)(o => shower.canShow(o.getClass))
    def show(l: List[_]): String = s"List(${l.map(shower.show(_)).mkString(", ")})"
)

similar to how unapply works

[kelnos]

But that doesn't actually do anything useful here, at least for the specific case of a list of something. If you look at the generated code for AsyncHttpClient, the code that gets emitted in the special case of List is (roughly):

for (final ${containedType} item : list) {
    builder.addFormParam("${paramName}", Shower.show(item));
}

Being able to take a list and generate a string that concats the values with commas in between isn't useful.

Parameterized types that aren't iterable should work, assuming the contained type also has a Showable instance registered. But again, the string that results has to actually be useful as a value. So you could perhaps do somthing like:

shower.register(classOf[Option[_]], new Showable[Option[_]] {
  def show(o: Option[_]): String = o.map(shower.show).orNull
}

That would actually work properly for the specific case of adding a form or query param for the AHC client generator, I think.

Back to list types: what we really need is a way to identify if a (custom) type is iterable or not, and then handle that iterable in whatever way makes sense for that purpose (add each element as a form or query param, or whatever). I'm not really sure how to do that, though, since JavaParser, when given an arbitrary string for a type, can't tell if the type implements Iterable. Perhaps if we know the OpenAPI type is array, then we just assume that if something is passed via x-scala-type for it, it must be Iterable? Not sure...

[blast-hardcheese]

At least if that assumption is wrong, it would be a discoverable type error. I'm thinking of attempts at refinement types, like NonEmptyList registered with Jackson such that more requirements can be expressed in the protocol, leading way to the OpenAPI validation stuff

[blast-hardcheese]

This kind of test harness looks useful; is this what you were talking about with generating test classes as well?

[kelnos]

Nah, the test class generation was to ensure that any custom types had a Showable implementation, but there was a chicken/egg problem there, and I haven't thought about it more to see if there's anything we can do.