Annotation Composition

[Gerard Davison]

A long while ago I wrote up a proposal for adding support for composite 
annotations, this came from my experience of using SOAP and REST web 
services. I never got around to posting it on this list, but I wondered 
if it might be worth considering for a later cycle and this seemed to be 
the right place to post it.

(A prettier version is on my blog at 
http://kingsfleet.blogspot.com/2010/04/composite-annotations.html)

PROJECT COIN SMALL LANGUAGE CHANGE PROPOSAL FORM v1.0

AUTHOR(S): Gerard Davison

OVERVIEW

Provide a two sentence or shorter description of these five aspects of 
the feature:

FEATURE SUMMARY: Should be suitable as a summary in a language tutorial.

Add the ability to compose existing annotations as meta annotations to 
be able to easily create stereotypes for common combinations.

MAJOR ADVANTAGE: What makes the proposal a favorable change?

Libraries can provide common "stereotype" made up of sensible default 
combinations of annotations.

MAJOR BENEFIT: Why is the platform better if the proposal is adopted?

Potentially shallower learning curve for annotation based frameworks.

MAJOR DISADVANTAGE: There is always a cost.

It is possible that by hiding configuration behind stereotypes that the 
code becomes harder to diagnose. This can be ameliorated to some extent 
with tool support and suitable naming conventions.

ALTERNATIVES: Can the benefits and advantages be had some way without a 
language change?

Yes, it is possible for each and every framework to introduce there own 
Composite marker annotation and processor. For example spring has 
something quite similar in there meta annotations:

http://blog.springsource.com/2009/05/06/spring-framework-30-m3-released/

Each implementation would be different then as not as easily accessible 
as a language feature would be.

EXAMPLES Show us the code!

SIMPLE EXAMPLE: Show the simplest possible program utilizing the new 
feature.

<http://kingsfleet.blogspot.com/2010/04/composite-annotations.html#><http://kingsfleet.blogspot.com/2010/04/composite-annotations.html#>

   1. package java.lang.annotation;
   2.
   3. @Retention(SOURCE)
   4. @Target(ANNOTATION_TYPE)
   5. public at interface Composite
   6. {
   7. }
   8.
   9.
  10. package x;
  11.
  12. @Composite
  13. @SuppressWarnings({"unchecked"})
  14. @Target(METHOD)
  15. public at interface SuppressUnchecked
  16. {
  17. }
  18.
  19. package y;
  20.
  21. publicclass ExampleService
  22. {
  23. @SupressUnchecked
  24. publicvoid methodWithOddCast()
  25.     {
  26.         ...
  27.     }
  28. }

ADVANCED EXAMPLE: Show advanced usage(s) of the feature.

<http://kingsfleet.blogspot.com/2010/04/composite-annotations.html#><http://kingsfleet.blogspot.com/2010/04/composite-annotations.html#>

   1. @Composite
   2. @WebService
   3. @Binding(SOAPBinding.SOAP_12_BINDING)
   4. @Addressing
   5. @Target(CLASS)
   6. public at interface SOAP12AddressingWebService
   7. {
   8. }
   9.
  10. @SOAP12AddressingWebService
  11. publicclass ExampleService
  12. {
  13.     ...
  14. }

DETAILS SPECIFICATION: Describe how the proposal affects the grammar, 
type system, and meaning of expressions and statements in the Java 
Programming Language as well as any other known impacts.

The lexical grammar is unchanged. The type system is unchanged. The 
annotation type section is modified (JLS ?.?) so that an annotation can 
be applied to composite annotation if that annotation is tagged with 
@Composite and the target and retention matches that of the composite 
annotation. This prevents all annotations having to be modified with the 
ANNOTATION_TYPE modifier.

COMPILATION: How would the feature be compiled to class files?

This feature modifies the process which is used to gather the annotation 
properties. In general the rule is that values directly applied to class 
will override values provided by composite annotations. So the process 
for building the values for a particular class should be:

   1. For each annotation attached to the class that isn't marked as
      @Composite store the values for this class. Once defined the value
      will not change.
   2. For each annotation attached to the class in source order that is
      marked as @Composite apply any values that have not been
      previously defined. Recursively apply the values for any attached
      composite annotations.

The compilation should fail if there is a loop of @Composite 
annotations. (QUERY should we allow multi-level or is one turtle enough.)

For a client reading the class using the reflective API it should appear 
as if the annotations provided by the composite annotations were applied 
to the class directly. (QUERY should the composite annotations be erased 
at runtime?)

TESTING: How can the feature be tested?

It should be a matter of generating various simple cases with differing 
levels of composite annotations. Corner cases should be provided with 
inconsistent target or retention policies.

LIBRARY SUPPORT: Are any supporting libraries needed for the feature?

REFLECTIVE APIS: Do any of the various and sundry reflection APIs need 
to be updated? This list of reflective APIs includes but is not limited 
to core reflection (java.lang.Class and java.lang.reflect.*), 
javax.lang.model.*, the doclet API, and JPDA.

As the annotations are unwound at compile time this won't affect any 
reflective API that works from a class file. It is going to pose a 
question of what is the correct thing to do when looking at a source 
file. (QUERY not sure what the best thing is to do)

OTHER CHANGES: Do any other parts of the platform need be updated too? 
Possibilities include but are not limited to JNI, serialization, and 
output of the javadoc tool.

Yes, the javadoc tool should show both the composite and the applied 
annotations in some way.

MIGRATION: Sketch how a code base could be converted, manually or 
automatically, to use the new feature.

Roll up some application to use stereotypes as applicable.

COMPATIBILITY BREAKING CHANGES: Are any previously valid programs now 
invalid? If so, list one.

All existing programs remain valid.

EXISTING PROGRAMS: How do source and class files of earlier platform 
versions interact with the feature? Can any new overloadings occur? Can 
any new overriding occur?

The semantics of existing class files and legal source files and are 
unchanged by this feature.

REFERENCES EXISTING BUGS: Please include a list of any existing Sun bug 
ids related to this proposal.

None

URL FOR PROTOTYPE (optional):

No prototype at this time.