[aspectj-dev] declare annotation syntax

["Wes Isberg" <wes@xxxxxxxxxxxxxx>]

A minor usability question now that we have a preliminary implementation!

I'm concerned that the declare annotation syntax will make it easy to write programs that will be hard to understand or will be incorrect but confusingly
similar to correct ones.  Some examples follow; see if you can read them
out loud on first pass, and see if any are incorrect:

  declare annotation : *.*Test : @Test; 
  declare annotation : * *Test : @Test; 
  declare annotation : (Test+) *Test : @Test; 
  declare annotation : (Test+) *(Test) : @Test; 
  declare annotation : @Test (Test+)* : @Robust;
  declare annotation : @Test * * : @Robust; 
  declare annotation : @Test * @Critical *.*(..): @Robust; 

Imagine using package-prefixes (com.xyz.app.files..*) and real names...  

I'd like to be able to know at a glance whether a declare annotating 
a field, method, or class.  Then I can stop reading or have a hint
about parsing the pattern.  (The pointcuts get(..), execution(..), etc.
give us hints about how to parse the pattern.)

How about this (cheating a bit on the examples):

  declare @field : *..testing..* *: @TestOnly;
  declare @constructor : @Test test*.new(): @TestMethod;
  declare @method : @Test void test*(): @TestMethod;
  declare @class : (*Test && Test+) : @TestClass;

We have the luxury of saying field, method, and class because they're
defined as such in the JLS, and users will already know it.  I suspect
the '@' symbol will soon enough be associated with "annotation."  This
form might also make it easier to support other kinds of annotation 
later, and to make clear which we do support.

If it's worth experimenting, I believe it will be easier for developers
to go from "@field", etc. to "annotation" than vice-versa, so it might 
be better to start there.

Wes

P.S. - I considered collapsing "method" and "constructor" into "code"
for brevity, but preferred being direct.

Background, from the AspectJ 5 developer's notebook:

------------------------------------------------------
The general form of a declare annotation statement is:

  	declare annotation : ElementPattern : Annotation ;
	

Where annotation is a regular annotation expression as defined in the 
Java 5 language. If the annotation has the @Target meta-annotation, 
then the elements matched by ElementPattern must be of the kind 
specified by the @Target annotation.

ElementPattern is defined as follows:

  	        ElementPattern := TypePattern |
  	                          MethodPattern |
  	                          ConstructorPattern |
  	                          FieldPattern
	

The following examples illustrate the use of declare annotation.

  declare annotation : org.xyz.model..* : @BusinessDomain ;

All types defined in a package with the prefix org.xyz.model have 
the @BusinessDomain annotation. 

  declare annotation : public * BankAccount+.*(..) : @Secured(role="supervisor")

 All public methods in BankAccount and its subtypes have the 
annotation @Secured(role="supervisor").

------------------------------------------------------