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

From: Chapman Flack <[email-masked]>
Date: Sat, 19 Dec 2015 12:56:39 -0500

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
[email-masked]
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev

---

From: Peter Henderson <[email-masked]>
Date: Mon, 21 Dec 2015 01:11:31 +0000

Just my £0.0002 worth

>   will be clear at sight when you know the PostgreSQL concepts.

Personally I'd prefer names similar to those used in the main documentation
http://www.postgresql.org/docs/9.4/static/xfunc-volatility.html

volatility=Volatile
volatility=Stable
volatility=Immutable

Make sense to me. Plus relate to the same terms used by a PL/pgSQL function.

-- 
Peter Henderson

Director
Starjar Ltd.
www.starjar.com
0330 088 1662

---

From: Chapman Flack <[email-masked]>
Date: Sun, 20 Dec 2015 21:49:50 -0500

> Make sense to me. Plus relate to the same terms used by a PL/pgSQL function.

Hi Peter,

I may have overlooked something; is there any context in PL/pgSQL where
you in fact say volatility=Volatile (or volatility=Stable, etc.)?

Or are you just referring to the standard CREATE FUNCTION syntax, where
you simply say VOLATILE, or STABLE, or IMMUTABLE?

I'm absolutely not proposing to change the names volatile, stable, and
immutable ... everybody knows those.

It just seems to me that the Java annotation syntax is adding a somewhat
unusual need to put somekeyword= in front of those three well-known names.
You don't ever have to do that in the SQL syntax, it's just a new slight
awkwardness imposed in the Java syntax, and my proposal is only about
what the somekeyword should be. It's effectively a non-optional noise
word, and to keep it unobtrusive I'd like it to be a short one. (I'm
sure that's the reason Thomas chose 'type' originally; it's nice and
short, and only unfortunate because it would be natural to use that
word to talk about the function's data type.)

Because nobody's changing the value names, even if the keyword were
Fahrvergnügen, you would still see Fahrvergnügen=IMMUTABLE or
Fahrvergnügen=VOLATILE and you'd immediately recognize what it was.

But 'effects' is even shorter than 'Fahrvergnügen', and almost as short
as 'type', without giving you the feeling of repeating yourself, as
volatility=VOLATILE would.

I flat-out refuse to make it Fahrvergnügen even if that gets the most votes.

-Chap

---

From: Thomas Hallgren <[email-masked]>
Date: Sun, 27 Dec 2015 15:55:14 +0100

My reaction is - Go ahead and change the keywords. Your suggestions 
sounds great!

- thomas