An apt replacement

Good riddance! Too bad apt was not deprecated in Java SE 6 so we could totally kill it now.

Suggestion: unbundle this turd from the JDK now, keeping it available as a separate download -- with "unsupported" status and deprecation tags -- for people who need it. There is no reason that stuff that's (a) deprecated, (b) planned for total elimination in next release, should be conveniently bundled in the JDK.

JSR-269 has been available for 2.5 years since Java SE 6 so you must assume that only the most lazy or conservative users are still depending on apt; some people follow too hard the "if it ain't broken, don't fix it" rule. These are exactly the users who will typically ignore deprecation warnings, and they will be still using apt when JDK 8 ships completely without apt.

You do a favor to these laggards to make a bit harder to use apt with JDK 7; with unbundling, they will see their builds breaking and be forced to download and install apt separately. This should be enough "writing on the wall" to make people migrate faster.

Remember that the Java platform has a long tradition of never removing any legacy feature, we have all garbage deprecated in JDK1.1 and up still in the latest version. So many developers get used to simply ignore deprecation in core libs.

I'm currently using apt for its SourcePosition information, which isn't available in JSR 269. Too bad for me!

In spite of that, I think this is the right move.

Jesse,

The Tree API of JDK6 provides a much richer API for getting source positions. The API focuses on character offsets in files, rather than lines and columns which simply doesn't provide a good canonical representation.

However, it is a little expensive for the compiler to account for all the source positions, so we didn't make them first class citizens in the API. Here is a collection of all the relevant API:

http://java.sun.com/javase/6/docs/technotes/guides/javac/index.html

The first thing you need to do is get an instance of Trees using this method: http://java.sun.com/javase/6/docs/jdk/api/javac/tree/com/sun/source/util/Trees.html#instance(javax.annotation.processing.ProcessingEnvironment)

Now that you have this instance, grab an instance of the sources positions utility using getSourcePositions().

Use the Trees instance to get the path of an element using getPath().

From the path you can get the compilation unit and leaf node. Use them to get a start or end position from the SourcePositions instance. These positions are character offsets from the beginning of a file, you can convert them to lines and columns using the line map of the compilation unit.

I know this is a complex API compared to com.sun.mirror, but we felt it was important to be able to expose the underlying representation inside javac directly without building heavy wrapper objects thus sacrificing speed and memory footprint. We hope the exposed API is flexible enough to not constrain future optimizations of javac. I think you will find that annotation processing inside javac is much faster than apt. All the element, type, and tree objects that you get are the objects used directly inside javac, not costly wrapper objects with slightly out-of-sync semantics.

Cheers,

Peter

@Jesse and @Peter,

Within the apt API, source positions are only consumed by the Messager. Because of that, in JSR 269 we just pass elements in question to the Messager to allow the source position to be implicitly reconstructed.

If you need the source positions for some other purpose, Peter's suggestion of using the tree API is the right approach.

Joe,

I thought the replacements you listed are already available in Java 6? At least I can't find javax.annotation.processing.ProcessingEnvironment for example. I have to migrate an apt based model driven development approach and would appreciate any hints to good documentation, tutorials, migration guides ...

Cheers,

Roger

@Roger,

Yes, all the replacements are available as of JDK 6; the type in question is documented at

http://java.sun.com/javase/6/docs/api/javax/annotation/processing/ProcessingEnvironment.html

See slides 56 and 57 of the 2006 JavaOne talk

"Annotation Processing With JSR 269,"

by Joseph D. Darcy, Scott Seligman, Jess Garms, Bruce Chapman

to get an overview of some of the fundamental changes between apt the the JSR 269-based annotation processing in javac.

@Joe,

sorry! It was right before my eyes!

Cheers,

Roger