As you probably all know, JSR 175 will enable annotations for Java programs as
part of the JDK.  The current method, using Javadoc, will slowly be phased
out and replaced by this JSR which defines models for

  • The annotations.
  • The class file format.
  • An API to access the annotations.

The current Javadoc approach is very fragile and non-standard, but it does
have a fairly strong point in its favor:  it is totally non-intrusive.

Consider the following Stateless Session Bean defined with EJBGen
annotations:

/**
 * @ejbgen:session
 *    ejb-name = statelessSession
 */
public class TraderEJB implements SessionBean {

 
/**
  
* @ejbgen:remote-method
  
*     transaction = Required
  
*/
 
public void buy(String stockSymbol, int shares) {
   
// buy shares
 
}
}

This Java source file doesn’t have any dependency on EJBGen.  You can
compile it with any Java compiler as long as you have the J2EE libraries in your
classpath.  No need for ejbgen.jar.

Now consider the JSR 175 equivalent:

import com.bea.wls.ejbgen.annotations.*;

@Session(
 
ejb-name = "statelessSession"
)
public class TraderEJB implements SessionBean {

 
@Remote (
     
transaction = Required
 
)
 
public void buy(String stockSymbol, int shares) {
   
// buy shares
 
}
}

This file will not compile unless you have the EJBGen annotations (com.bea.wls.ejbgen.annotations.*)
in your classpath.  You have just tied yourself to a tool.

Now imagine that this source file uses other tools as well, mixing several
kinds of annotations such as Struts, AOP, etc…  Suddenly, your
dependencies shoot up the roof and a simple source file like the one above ends
up pulling a big set of JAR files before you can even run javac on it.

Here is another example:  you send me an MBean source with annotations
from a tool that helps you create MBeans.  I want to be able to build that
MBean even if I’m not using your tool.

How about IDE’s such as Rational that save information as annotations in
their Java files.  With JSR 175, you will no longer be able to compile
these files unless you have the Rational classes in your classpath.

The common point in these examples is that the class can be useful
without the annotations, which are merely hints used by third-party tools to get
a certain job done faster.

What can we do about this?

The first idea that came to my mind was to make annotations optional to javac. 
If the compiler cannot locate an annotation type, it will emit a warning but
keep compiling.  This is similar to the Javadoc behavior, which tries to
make a full transitive closure of all the types in your source files, attempts
to locate the dependent source files but simply issues a warning if it can’t
find them and keeps going.

After all, all this means is that no documentation will be available for these
dependent classes, but it shouldn’t stop the tool from producing documentation for the
supplied classes.

Another way to mitigate the problem would be for tools to be distributed in
two parts:  the annotation jar file (or even better:  the annotation
source files) and
the "real" (runtime) jar file.  Compiling the above source file would still make you
depend on EJBGen, but only the annotation part, not the whole runtime.

What do you think?

  • Should javac have an option -ignoreAnnotations?
     
  • Should this flag be turned on by default?