From alex.buckley at oracle.com  Wed Sep 12 17:15:47 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 12 Sep 2012 17:15:47 -0700
Subject: Spec updates for inheritance and reflection
Message-ID: <505125B3.4040507@oracle.com>

I have updated the spec to clarify inheritance of annotations, for both 
singular and repeated annotations. For the first time, there are proper 
definitions of "present" and "directly present" as used throughout 
j.l.r.AnnotatedElement. I work through the implications for core 
reflection of inheritable repeatable annotation types having their 
annotations "overridden" by annotations on a subclass.

I also added a modest section on changes to the language model API, 
consistent with the changes to core reflection.

The spec is at http://cr.openjdk.java.net/~abuckley/8misc.pdf as usual.

Alex

P.S. If you want to play with repeating annotations, check out 
http://jdk8.java.net/type-annotations/ ... thanks to superior code 
wrangling by Joel Franck (repeating annotations) and Werner Dietl (type 
annotations), support for repeating annotations on declarations is 
included in the build. See recent mail on type-annotations-dev for more.


From pbenedict at apache.org  Thu Sep 13 09:04:39 2012
From: pbenedict at apache.org (Paul Benedict)
Date: Thu, 13 Sep 2012 11:04:39 -0500
Subject: Repeating Annotations and backwards compatibility
Message-ID: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>

I just read the archives and find that "looking through" the grouping
annotation is awkward. However, I also agree with Joel that we "shouldn't
make the source-to-reflection gap bigger."

Was there any consideration given to NOT retrofitting annotations? That is,
just allow repeating annotations; those with historical grouping
annotations have to retain them to maintain the same reflection results.
Then no "looking through" magic needs to occur at the reflection level. I
think that's much more straight-forward than what's being proposed.

Paul


From alex.buckley at oracle.com  Thu Sep 13 12:00:16 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 13 Sep 2012 12:00:16 -0700
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
Message-ID: <50522D40.1010008@oracle.com>

On Thursday, September 13, 2012 9:04:39 AM, Paul Benedict wrote:
> Was there any consideration given to NOT retrofitting annotations? That is,
> just allow repeating annotations; those with historical grouping
> annotations have to retain them to maintain the same reflection results.
> Then no "looking through" magic needs to occur at the reflection level. I
> think that's much more straight-forward than what's being proposed.

The goal was to be able to write repeating annotations without writing 
the container annotation manually, and still have legacy consumers work 
without modification when they a) expect a container annotation from 
getAnnotation(Class<T>) and b) do not expect repeating annotations from 
get[Declared]Annotations(). The Java EE group believes the number of 
these legacy consumers to be significant.

New consumers which use the new get[Declared]Annotations(Class<T>) 
methods can choose to ignore container annotations and grab the 
possibly-repeated annotations directly.

Alex


From pbenedict at apache.org  Thu Sep 13 13:52:17 2012
From: pbenedict at apache.org (Paul Benedict)
Date: Thu, 13 Sep 2012 15:52:17 -0500
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <50522D40.1010008@oracle.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50522D40.1010008@oracle.com>
Message-ID: <CABLGb9yAkfds42e=pQcsCE+y2T=Ybtg9qJy-ADqv8Hy7MM7VxQ@mail.gmail.com>

Alex,

Does this mean that future specs will no longer strive to create new
container annotations? Presumably with repeating annotations, container
annotations are no longer a necessary design feature.

Paul

On Thu, Sep 13, 2012 at 2:00 PM, Alex Buckley <alex.buckley at oracle.com>wrote:

> On Thursday, September 13, 2012 9:04:39 AM, Paul Benedict wrote:
>
>> Was there any consideration given to NOT retrofitting annotations? That
>> is,
>> just allow repeating annotations; those with historical grouping
>> annotations have to retain them to maintain the same reflection results.
>> Then no "looking through" magic needs to occur at the reflection level. I
>> think that's much more straight-forward than what's being proposed.
>>
>
> The goal was to be able to write repeating annotations without writing the
> container annotation manually, and still have legacy consumers work without
> modification when they a) expect a container annotation from
> getAnnotation(Class<T>) and b) do not expect repeating annotations from
> get[Declared]Annotations(). The Java EE group believes the number of these
> legacy consumers to be significant.
>
> New consumers which use the new get[Declared]Annotations(**Class<T>)
> methods can choose to ignore container annotations and grab the
> possibly-repeated annotations directly.
>
> Alex
>


From alex.buckley at oracle.com  Thu Sep 13 13:54:26 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 13 Sep 2012 13:54:26 -0700
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <CABLGb9yAkfds42e=pQcsCE+y2T=Ybtg9qJy-ADqv8Hy7MM7VxQ@mail.gmail.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50522D40.1010008@oracle.com>
	<CABLGb9yAkfds42e=pQcsCE+y2T=Ybtg9qJy-ADqv8Hy7MM7VxQ@mail.gmail.com>
Message-ID: <50524802.4090902@oracle.com>

I thought I made it clear that container annotations are required in 
the ClassFile for legacy users of reflection. We generate container 
annotations on an occurrence of repeating annotations precisely for 
their benefit. New users of reflection can use new methods which "look 
through" container annotations, but the container annotations are still 
physically present.

Alex

On Thursday, September 13, 2012 1:52:17 PM, Paul Benedict wrote:
> Alex,
>
> Does this mean that future specs will no longer strive to create new
> container annotations? Presumably with repeating annotations,
> container annotations are no longer a necessary design feature.
>
> Paul
>
> On Thu, Sep 13, 2012 at 2:00 PM, Alex Buckley <alex.buckley at oracle.com
> <mailto:alex.buckley at oracle.com>> wrote:
>
>     On Thursday, September 13, 2012 9:04:39 AM, Paul Benedict wrote:
>
>         Was there any consideration given to NOT retrofitting
>         annotations? That is,
>         just allow repeating annotations; those with historical grouping
>         annotations have to retain them to maintain the same
>         reflection results.
>         Then no "looking through" magic needs to occur at the
>         reflection level. I
>         think that's much more straight-forward than what's being
>         proposed.
>
>
>     The goal was to be able to write repeating annotations without
>     writing the container annotation manually, and still have legacy
>     consumers work without modification when they a) expect a
>     container annotation from getAnnotation(Class<T>) and b) do not
>     expect repeating annotations from get[Declared]Annotations(). The
>     Java EE group believes the number of these legacy consumers to be
>     significant.
>
>     New consumers which use the new
>     get[Declared]Annotations(__Class<T>) methods can choose to ignore
>     container annotations and grab the possibly-repeated annotations
>     directly.
>
>     Alex
>
>


From pbenedict at apache.org  Thu Sep 13 14:06:02 2012
From: pbenedict at apache.org (Paul Benedict)
Date: Thu, 13 Sep 2012 16:06:02 -0500
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <50524802.4090902@oracle.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50522D40.1010008@oracle.com>
	<CABLGb9yAkfds42e=pQcsCE+y2T=Ybtg9qJy-ADqv8Hy7MM7VxQ@mail.gmail.com>
	<50524802.4090902@oracle.com>
Message-ID: <CABLGb9z1hE-BbDAnKt7VAcsV5sFqqOj5ZJs2BNkWSgO-2xLaRg@mail.gmail.com>

On Thu, Sep 13, 2012 at 3:54 PM, Alex Buckley <alex.buckley at oracle.com>wrote:

> I thought I made it clear that container annotations are required in the
> ClassFile for legacy users of reflection.


Well, maybe.


> We generate container annotations on an occurrence of repeating
> annotations precisely for their benefit. New users of reflection can use
> new methods which "look through" container annotations, but the container
> annotations are still physically present.
>
>
I thought you were saying that *legacy* container annotations are ONLY for
*legacy* annotations. If a futuristic JPA 3, for example, introduced a new
repeating annotation, it should be unnecessary to also spec out a new
container annotation too. Are you really saying container annotations are
necessary forever?

Paul


From forax at univ-mlv.fr  Thu Sep 13 14:22:28 2012
From: forax at univ-mlv.fr (Remi Forax)
Date: Thu, 13 Sep 2012 23:22:28 +0200
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
Message-ID: <50524E94.9050901@univ-mlv.fr>

On 09/13/2012 06:04 PM, Paul Benedict wrote:
> I just read the archives and find that "looking through" the grouping
> annotation is awkward. However, I also agree with Joel that we "shouldn't
> make the source-to-reflection gap bigger."

While I may agree with this if it's free, the main issue is that the 
current design come with a price,
you can retrofit repeated annotations and their container only if they 
are declared in the same library
(at least under the control of the same group of people).

I've seen code to add a container annotation to javax.jws.WebService so 
I suppose that
several projects have come along the same path for annotations that 
already exist in Java SE/EE world.

R?mi



From bill.shannon at oracle.com  Thu Sep 13 14:53:17 2012
From: bill.shannon at oracle.com (Bill Shannon)
Date: Thu, 13 Sep 2012 14:53:17 -0700
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <50524E94.9050901@univ-mlv.fr>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50524E94.9050901@univ-mlv.fr>
Message-ID: <505255CD.3030907@oracle.com>

Remi Forax wrote on 09/13/2012 02:22 PM:
> On 09/13/2012 06:04 PM, Paul Benedict wrote:
>> I just read the archives and find that "looking through" the grouping
>> annotation is awkward. However, I also agree with Joel that we "shouldn't
>> make the source-to-reflection gap bigger."
> 
> While I may agree with this if it's free, the main issue is that the current
> design come with a price,
> you can retrofit repeated annotations and their container only if they are
> declared in the same library
> (at least under the control of the same group of people).
> 
> I've seen code to add a container annotation to javax.jws.WebService so I
> suppose that
> several projects have come along the same path for annotations that already
> exist in Java SE/EE world.

If there's existing Java EE annotations that need new container annotations,
now would be a good time to bring that up with the corresponding spec lead!

I wouldn't have expected @WebService to be one of those.  Does someone want
to expose a single class as multiple web services?  Isn't a workaround to
just create some trivial subclasses with new annotations?



From alex.buckley at oracle.com  Thu Sep 13 15:06:58 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 13 Sep 2012 15:06:58 -0700
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <CABLGb9z1hE-BbDAnKt7VAcsV5sFqqOj5ZJs2BNkWSgO-2xLaRg@mail.gmail.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50522D40.1010008@oracle.com>
	<CABLGb9yAkfds42e=pQcsCE+y2T=Ybtg9qJy-ADqv8Hy7MM7VxQ@mail.gmail.com>
	<50524802.4090902@oracle.com>
	<CABLGb9z1hE-BbDAnKt7VAcsV5sFqqOj5ZJs2BNkWSgO-2xLaRg@mail.gmail.com>
Message-ID: <50525902.6060809@oracle.com>

On 9/13/2012 2:06 PM, Paul Benedict wrote:
> I thought you were saying that *legacy* container annotations are ONLY
> for *legacy* annotations. If a futuristic JPA 3, for example, introduced
> a new repeating annotation, it should be unnecessary to also spec out a
> new container annotation too. Are you really saying container
> annotations are necessary forever?

The price of behavioral compatibility for legacy consumers of legacy 
ClassFiles (which must continue to work for ever mre) is the 
containerization of repeating annotations for ever. Useful new 
reflection methods make this a non-issue for new consumers of repeatable 
annotation types; such consumers may write and reflect repeating 
annotations with very little interest in the container behind the curtain.

Alex


From forax at univ-mlv.fr  Thu Sep 13 15:54:54 2012
From: forax at univ-mlv.fr (Remi Forax)
Date: Fri, 14 Sep 2012 00:54:54 +0200
Subject: Repeating Annotations and backwards compatibility
In-Reply-To: <505255CD.3030907@oracle.com>
References: <CABLGb9yaP5xApXui194n18d=7DNfZ+bFDP7udT=Leo6xYUhaiw@mail.gmail.com>
	<50524E94.9050901@univ-mlv.fr> <505255CD.3030907@oracle.com>
Message-ID: <5052643E.5020004@univ-mlv.fr>

On 09/13/2012 11:53 PM, Bill Shannon wrote:
> Remi Forax wrote on 09/13/2012 02:22 PM:
>> On 09/13/2012 06:04 PM, Paul Benedict wrote:
>>> I just read the archives and find that "looking through" the grouping
>>> annotation is awkward. However, I also agree with Joel that we "shouldn't
>>> make the source-to-reflection gap bigger."
>> While I may agree with this if it's free, the main issue is that the current
>> design come with a price,
>> you can retrofit repeated annotations and their container only if they are
>> declared in the same library
>> (at least under the control of the same group of people).
>>
>> I've seen code to add a container annotation to javax.jws.WebService so I
>> suppose that
>> several projects have come along the same path for annotations that already
>> exist in Java SE/EE world.
> If there's existing Java EE annotations that need new container annotations,
> now would be a good time to bring that up with the corresponding spec lead!
>
> I wouldn't have expected @WebService to be one of those.  Does someone want
> to expose a single class as multiple web services?  Isn't a workaround to
> just create some trivial subclasses with new annotations?
>

I've seen that last year visiting a student working for a big french 
telco company,
I don't remember clearly the details but they were transitioning from an 
in house
framework that was allowing this kind of stupid stuff and the dev team have
to emulate the same behaviour (bit to bit :( ) using JAX-WS reference 
implementation + patches.

R?mi



From alex.buckley at oracle.com  Thu Sep 20 13:58:12 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 20 Sep 2012 13:58:12 -0700
Subject: Spec update for repeatable/containing relationship
Message-ID: <505B8364.7000905@oracle.com>

I just updated the spec to slightly tighten the two-way relationship 
between a repeatable and a containing annotation type when compiling a 
prospective containing annotation type. Previously, its @ContainerFor 
merely needed to agree with the containee's @ContainedBy, but that 
allowed deformities in the structure of the prospective containing 
annotation type (e.g. the return type of its value() element). In 
contrast, we always required that compiling a prospective repeatable 
annotation type needed to see an @ContainedBy that named a well-formed 
containing annotation type.

The change is a single paragraph on page 4 of 
http://cr.openjdk.java.net/~abuckley/8misc.pdf, and the corresponding 
reflection rule on page 10. I extended the example on page 4 too.

Separately, I would be grateful if any EE engineers on this list could 
be sure they agree with the detailed reflection examples in section 1.2.

Alex


From pbenedict at apache.org  Fri Sep 21 06:47:35 2012
From: pbenedict at apache.org (Paul Benedict)
Date: Fri, 21 Sep 2012 08:47:35 -0500
Subject: Spec update for repeatable/containing relationship
In-Reply-To: <505B8364.7000905@oracle.com>
References: <505B8364.7000905@oracle.com>
Message-ID: <CABLGb9yE-k6sEvfNL275exSoH0vv8-yUCAZf7Ckbo2XSPuV8NQ@mail.gmail.com>

Alex,

Two questions on page 2...

(1) "An annotation type TC is the containing annotation type of T if all of
the following are true ... Any methods declared by TC other than value()
have a default value."

Shouldn't a compile error be emitted if this case fails? If I code a
container annotation but forget defaults on other methods, I think an error
should occur. I didn't see a line in the spec that explicitly stated this
behavior, but it would be helpful to developers.

(2) In regards to this paragraph: "@ContainerFor supports the Java SE
platform reflection API in differentiating automatically-generated
container annotations from legacy annotations which served as idiomatic
containers prior to Java SE 8."

I think this paragraph is incorrect regarding (a) automatically-generated
container annotations and (b) legacy annotations. For repeatability to
exist at all, a pairing of @ContainerFor and @ContainedBy annotation types
must exist at compile time. So this isn't about "legacy" code, and the
pairing doesn't seem to provide any room for the container to be
"automatically-generated".

Paul

On Thu, Sep 20, 2012 at 3:58 PM, Alex Buckley <alex.buckley at oracle.com>wrote:

> I just updated the spec to slightly tighten the two-way relationship
> between a repeatable and a containing annotation type when compiling a
> prospective containing annotation type. Previously, its @ContainerFor
> merely needed to agree with the containee's @ContainedBy, but that allowed
> deformities in the structure of the prospective containing annotation type
> (e.g. the return type of its value() element). In contrast, we always
> required that compiling a prospective repeatable annotation type needed to
> see an @ContainedBy that named a well-formed containing annotation type.
>
> The change is a single paragraph on page 4 of http://cr.openjdk.java.net/~
> **abuckley/8misc.pdf <http://cr.openjdk.java.net/~abuckley/8misc.pdf>,
> and the corresponding reflection rule on page 10. I extended the example on
> page 4 too.
>
> Separately, I would be grateful if any EE engineers on this list could be
> sure they agree with the detailed reflection examples in section 1.2.
>
> Alex
>


From alex.buckley at oracle.com  Fri Sep 21 11:48:03 2012
From: alex.buckley at oracle.com (Alex Buckley)
Date: Fri, 21 Sep 2012 11:48:03 -0700
Subject: Spec update for repeatable/containing relationship
In-Reply-To: <CABLGb9yE-k6sEvfNL275exSoH0vv8-yUCAZf7Ckbo2XSPuV8NQ@mail.gmail.com>
References: <505B8364.7000905@oracle.com>
	<CABLGb9yE-k6sEvfNL275exSoH0vv8-yUCAZf7Ckbo2XSPuV8NQ@mail.gmail.com>
Message-ID: <505CB663.9050605@oracle.com>

On 9/21/2012 6:47 AM, Paul Benedict wrote:
> (1) "An annotation type TC is the containing annotation type of T if all
> of the following are true ... Any methods declared by TC other than
> value() have a default value."
>
> Shouldn't a compile error be emitted if this case fails? If I code a
> container annotation but forget defaults on other methods, I think an
> error should occur. I didn't see a line in the spec that explicitly
> stated this behavior, but it would be helpful to developers.

Yes, a compile-time error should and will be emitted. There are strict 
rules about what a well-formed containing annotation type looks like. If 
a prospective repeatable annotation type T has a meta-annotation 
@ContainedBy(TC.class), but TC doesn't look like a well-formed 
containing annotation type (e.g. TC has a blah() method without a 
default), then TC is not in fact the containing annotation type of T. TC 
is a pretender. Then from page 4:

"It is a compile-time error if an annotation type T is (meta-)annotated 
with an @ContainedBy annotation whose value element indicates a type 
other than the containing annotation type of T."

So write T.java and TC.java, and try to compile T.java; it will give an 
error. Try to compile TC.java; it will give an error too, because of:

"It is a compile-time error if an annotation type TC is (meta-)annotated 
with an @ContainerFor annotation whose value element indicates the type 
T, but TC is not the containing annotation type of T."

> (2) In regards to this paragraph: "@ContainerFor supports the Java SE
> platform reflection API in differentiating automatically-generated
> container annotations from legacy annotations which served as idiomatic
> containers prior to Java SE 8."
>
> I think this paragraph is incorrect regarding (a)
> automatically-generated container annotations and (b) legacy
> annotations. For repeatability to exist at all, a pairing of
> @ContainerFor and @ContainedBy annotation types must exist at compile
> time. So this isn't about "legacy" code, and the pairing doesn't seem to
> provide any room for the container to be "automatically-generated".

In 2007, say, someone declared type Foo and an idiomatic container type 
FooContainer and wrote @FooContainer(value={@Foo(1), at Foo(2)}) on a 
class. The resulting ClassFile will continue to work and be reflectable 
in Java SE 8. But with no "opt-in" via @ContainedBy on Foo and 
@ContainerFor on FooContainer, there is no change in behavior of 
AnnotatedElement methods. For example, get[Declared]Annotations() will 
still return {@FooContainer(..)}. This is the legacy code story.

If in 2013 the annotation type author "opts in", then app authors can 
rewrite @FooContainer(value={@Foo(1), at Foo(2)}) to @Foo(1) @Foo(2) and 
get @FooContainer generated automatically. 2013-era consumers get find 
@Foo annotations directly via get[Declared]Annotations(Foo.class). 
2007-era consumers can still do 
get[Declared]Annotation(FooContainer.class) and inspect the value element.

The introductory text in Chapter 1 will end up as a note in the JLS, so 
if you find it unclear, please suggest an alternative.

Alex