Annotation-driven SQL for UDTs.

[jcflack]

The 2013 work on the SQL generator didn't add annotations for setting up PL/Java User Defined Types ... an unhappy omission because hand-coding the SQL for UDTs (base type UDTs, anyway) is fiddly and tedious. So here are two new annotations:

@BaseUDT class foo implements SQLData { ... }

as long as the class implements the interface and also has the necessary parse method and no-arg constructor, will generate all the SQL (shell type, four function declarations, complete type redeclaration) for a new base type.

@MappedUDT(structure={"x float8", "y float8"}) class cplx implements SQLData ...

will emit SQL to declare a new composite/structured type with the specified structure, and call sqlj.add_type_mapping to associate it with the class.

If PostgreSQL says "composite" and the SQL standard says "structured", why did I say "mapped"? Well, because you can use the same annotation to do this (even though it's arguably not a UDT at all then):

@MappedUDT class point implements SQLData ...

If no structure is specified, no type declaration is actually emitted, only the call to sqlj.add_type_mapping to associate the class with some existing PostgreSQL type.

Includes updates to the ComplexScalar, ComplexTuple, and Point examples to make them annotation-driven, and remove the associated SQL from the hand-maintained examples.ddr as it now appears by magic in the generated pljava.ddr.

In the examples, I still use complexType on return values and @SQLType on parameter values to indicate the SQL type corresponding to the class ... one would think the generator could learn that much from seeing the annotation saying the type is the class ... but that will take a bit more rework of the generator's type mapper than appeals to me just now, and complexType/SQLType are not that hard to use, so it can go on the enhancement queue for later.

I had not run these examples (specifically, their logAndReturn methods) before, and trying them out seems to uncover a couple areas for attention. ComplexScalar works great (logs and returns the correct values); ComplexTuple produces equally good results but also a TupleDesc reference leak warning, and Point succeeds and returns the correct values, but emits a log message with different values (that is, after adding a toString method to be able to see the values). As for Point to work it has to intimately know the PostgreSQL internal point layout, maybe these bogus values mean some detail has changed there. I see the same behavior on the master branch.

Turns out the ComplexTuple reference leak warning goes away if the logAndReturn function is declared IMMUTABLE STRICT as it was in the hand-maintained examples.ddr; the generator makes it VOLATILE by default unless annotated otherwise (and that produces the same warning even on the master branch), so I'll adjust the annotation. Maybe it is worth exploring why marking such a simple function VOLATILE would lead to a reference leak, though.