[Jsr308-statements] use cases for the annotations on code blocks and statements

[Doug Lea]

Eugene Kuleshov wrote:
> Hi,
> 
>  I would like to start collecting possible use cases for the annotations 
> on code blocks and statements.
> 

Here's a more general characterization that might help:

Annotations are "adjectives" (or sometimes "adverbs").
There are three broad classes of them,
"declarative", "procedural", and "auxiliary":

1. Declarative annotations provide more information than can be
expressed using the base type system. They include
    Cross-checks
       @Overrides
    Pluggable "lightweight" types
       for example @NonNull, @ReadOnly
    Performance specs
       for example WCET annotations
    Behavioral specs
       for example JML; most forms of concurrency annotations


These kinds of annotations mainly support tools that can
check the correctness of the annotations wrt the code and vice
versa. (An interesting and important further question that is
usually swept under the rug is how to arrange that VMs can
trust such annotations to provide better performance, fault
detection, etc. Hard. Probably too hard to deal with in JSR308.)

2. Procedural annotations go beyond purely declarative ones
in that they declare a property/quality that
is compatible with but not actually present in the annotation
target, under the expectation that source, bytecode, load-time,
and/or runtime program transformation tools will cause that
property to hold. They include:
   Most Enterprise Java annotations
      @WebService, object-relational mapping support, etc
   AOP-via-Annotations
      generating code for logging, security checks, etc
   Implicit method generation
      @Property etc
   Parallelization
      loop annotations for map-reduce, etc
   Lightweight Transactions
      support for upcoming STM schemes
   Cluster computing
      as in Terracotta etc

Some people accuse Procedural annotations as being a weird
intermediate ground between syntactic macros and AOP.
But their declarative basis seems to help avoid the worst
aspects of macros and AOP. And they've been pretty successful
especially in enterprise applications where they aren't
so affected by current limitations.

3. Auxiliary annotations conveniently associate various forms of
non-semantic (or, I guess, meta-semantic) data with their
sources. Examples include
   Identification
     Revision, test, histories etc
   Meta-control for development tools
     @deprecated
     Hints/overrides for findBugs etc
     Build script information
     Test instructions

These probably aren't too interesting for JSR308, but are listed
for completeness.



Some more meta-chat:

One of the original ideas behind annotations was to provide
a way for people to create simple ad-hoc "language extensions"
without actually changing the language. EJB3.0 was one of
the drivers for this. In particular, people were sick of using
deployment descriptors to arrange object-relational mappings,
and wanted some way to integrate these with Java source. JSR175
basically only went far enough to support this and related
usages. There was not at the time enough pressure from the
developer community to deal with annotation targets and
usages that hit the various obstacles people have noted about
class file formats, reflection, and syntax.  And it's
likely that if we did attack them, we would have failed to
do anything at all in time for Java 5 release.

But times change, and different pressures emerge.
(Aside: One of the joys of working on platform standards
is that you are completely sure that your judgements
are wrong. You just don't know *when* they will
be proven to be wrong.)

The JSR308 proposal spells out some of the ways that current
limitations form un-workaround-able obstacles for pluggable types
and other desirable applications.

Beyond these, given the goals of annotations, it's
disappointing that there is now more interest than ever in
syntactic extensions that might just as plausibly be covered
by better annotation support. This argues that time would be
well-spent thinking hard about whether and how extensions to
annotation support would help avoid continual syntax proposals.
There are some intrinsic limitations though. Even more uniform
support will probably never result in constructions that are
as aesthetically pleasing as those using full native syntax
integration. But we might be able to do better than what we
have now.

Enhanced annotation support will expand the range of things
you can do with annotations vs other constructs. But of course,
just because we allow them doesn't mean they will always be
the best choice. For an existing example, the Serializable
tagging interface is arguably better than would be a @Serializable
annotation. Although arguably worse too. Luckily, we don't
have to make these judgement calls; just the main one, of
supporting them at all. If we do, people will find usages that
range from the elegant to the embarrassing. Just like they
do now for everything else.

-Doug