[Pljava-dev] annotation keyword changes before 1.5.0 (?)

There has been some code in the tree for Java annotation support
ever since January 2005, but I'm not sure how usable or used it
was before March 2013. That was after the most recent numbered
release, so I think 1.5.0 will be the first numbered release
featuring annotation support in a significant way. So, there will
probably never be a better time to change any of the annotation
keywords, if they are worth changing. No one who has been using
prebuilt distributions from pgFoundry will have used them yet.

- In a @Function annotation, the keyword 'type' is used to specify
the volatility category (volatile, stable, immutable). That dates
all the way back to 2005, but I'd rather have 'type' mean
the SQL type of the function return (right now, you have to say
'complexType' for that, which isn't intuitive). I was stuck for a
a while on a good, short, alternative keyword. I'm not thrilled
with 'volatility' because it's both long and semi-redundant
(volatility=volatile makes you snicker, volatility=immutable
makes you wince). I think my current favorite idea is 'effects'.
I think all of (effects=volatile, effects=stable, effects=immutable)
will be clear at sight when you know the PostgreSQL concepts.

- In @Trigger, 'when' is used for the timing of the trigger call
(before, after, instead of). That's perfectly clear and sensible,
but later PostgreSQL went and added a WHEN clause to CREATE TRIGGER
(which you use to specify a WHERE condition, go figure). We could
keep the 'when' keyword for before/after/instead and add some
other keyword ('where'?) for the WHEN clause, but it is probably
better to change to some other keyword for before/after/instead,
and use 'when' for the new WHEN clause.

The best other keyword I've thought of is simply 'called':
called=BEFORE called=AFTER called=INSTEAD_OF

- In @Function(trust=???), I've had a long struggle with word choice
for the ??? to be as clear as possible. The PostgreSQL usage (trusted,
for code that isn't allowed to do whatever it wants, and untrusted,
for code that is allowed to do whatever it wants) is clear and makes
perfect sense if you think about it the right way. The trouble is, it
is just as easy to think about it the wrong way and get it backwards.
After all, why wouldn't 'trusted' code be allowed to do what it wants,
and 'untrusted' code not be?

My first try to clarify it was with the current trust=RESTRICTED,
trust=UNRESTRICTED, which I now realize suffers from exactly the same
problem! :(

I think the objective I'd like to achieve here is Java code that can
be readable either by a veteran PostgreSQL wizard or just by an
interested Java coder, where the PostgreSQL wiz will think "oh, yes,
I know exactly what PG syntax that maps to" and the generic Java coder
will just think "ok, I believe I get what that means", but neither
one of them will get it exactly backwards, which would be bad.

At the moment, I'm thinking trust=SANDBOXED, trust=UNSANDBOXED, but I am
open to ideas.

Any reactions or suggestions to the above (including "wait! stop! nooo,
don't change any keywords!") welcome.

-Chap
_______________________________________________
Pljava-dev mailing list
Pljava-dev(at)lists(dot)pgfoundry(dot)org
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev