Message-ID: <56759A57.9060106@anastigmatix.net>
Date: Sat, 19 Dec 2015 12:56:39 -0500
From: Chapman Flack <chap@anastigmatix.net>
MIME-Version: 1.0
Subject: [Pljava-dev] annotation keyword changes before 1.5.0 (?)
Content-Type: text/plain; charset="us-ascii"

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@lists.pgfoundry.org
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev