Re: [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

Just my £0.0002 worth

On Sat, Dec 19, 2015 at 5:56 PM, Chapman Flack <chap(at)anastigmatix(dot)net>
wrote:

> 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.
>

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.

> 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
>

--
Peter Henderson

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

On 12/20/15 20:11, Peter Henderson wrote:
> volatility=Volatile
> volatility=Stable
> volatility=Immutable
>
> 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
_______________________________________________
Pljava-dev mailing list
Pljava-dev(at)lists(dot)pgfoundry(dot)org
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev

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

- thomas

On 2015-12-19 18:56, Chapman Flack wrote:
> 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

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