Posts Tagged ‘ QDox ’

New QDox lead – Robert Scholte

I’d like to announce the new lead for QDox, Robert Scholte.

Anyone who’s been following the project for the past year would have seen that Robert has made a tremendous number of contributions to all areas of QDox, including bug fixes, build, docs/website, releasing, user support and admin. If you follow the project further back, you’ll see that Robert has actually done more on the project in the past year than was done for the combined 6 years before that…. impressive.

I originally wrote QDox back in 2002, as a stop gap until annotations were added to the Java language. It was quickly picked up tools such as XDoclet. I always thought (and hoped) that once annotations made it into the language, it would be redundant. Yet it lived on. Unlike the JDK Annotation Processing Tool (APT), it could process source code rather than byte code in a simpler and faster manner. And it provided access to information that the JDK didn’t make available (e.g. parameter names). And it was useful where annotations still did not exist, like in JavaME. So, even in 2010, it still lives on and is used in tools such as Maven and Eclipse. But I cannot invest the time into it that I once could.

Given Robert’s commitment to the project, I can think of no better person to lead the project. He’s done an astounding job. Robert has kindly accepted this role and I’m delighted to hand it over to him.

I’d also like to use this opportunity to thank Paul Hammant, Mauro Talevi and Dennis Lundberg for their ongoing efforts on the project.

QDox is back – 1.6 released

QDox history

QDox is a fast JavaDoc/Java parser built in 2002. It was originally intended as a stop gap until Java supported annotations by allowing tools to easily get access to JavaDoc attributes. Essentially it provided nothing more than a stripped down version of the JavaDoc Doclet tool, with performance suitable for using in continual build cycles (what would take JavaDoc over ten minutes to process would typically take QDox less than ten seconds). It served its purpose well.

The death of QDox

Then came along Java 5 and I stopped actively working on QDox. The first reason was that with the new annotations support, QDox wasn’t necessary. The other reason was that it would take a lot of effort to update the parser to support Java 5 syntax (not just for annotations, but generics, enums, etc).

And so QDox went quiet. The dev team lost interest and the releases stopped.

QDox is reborn

It turned out, I was wrong. Even with Java supporting annotations, QDox in a Java 5 world has some benefits:

  • Some Java 5 projects still want to use JavaDoc attributes (as well as annotations). Maybe for legacy reasons.
  • QDox acts on source code, rather than byte code. This can be useful in chicken and egg situations where you need to generate source from existing source, but you can’t compile until you’ve generated the code.
  • QDox exposes information that isn’t exposed by reflection, such as names of parameters or JavaDoc comments, which are useful for building tools to help visualize code.

So, by popular demand, I’m resurrecting the project. Yay.

1.6 released

This new release is a stop-gap release. Highlights include:

  • Switched to Apache 2.0 license.
  • Parser can now deal with Java 5 source code (annotations, generics, enums, var args, etc).
  • Numerous bugfixes.

This should be enough for existing projects to carry on using it with Java 5 code.

The next release will focus on making Java 5 specific features available in the API. Stay tuned.

A simple way to access JavaDoc attributes at runtime

It’s easy to gain access to JavaDoc attributes using QDox, however this requires you to have the source available. At runtime this isn’t always possible, unless you’re happy giving your source away.

A workaround to this is to use QDox to parse the source code at development time and serialize the resulting structures to make them available at runtime. This will work, but it’s a bit nasty as big binary files aren’t the most stable of things.

A more open approach is to bundle the source of your classes with the application, making them available at runtime, however *without* the method body implementations.

*Class with method body implementations:*

package stuff;

public class CheeseSlicer {

/** @transaction mode=isolated */
public Slice feedMe() {
// some implementation specific stuff here.. don't waste your time reading it.
if (System.currentTimeMillisMillis() % 2 == 0) {
return new CheddarSlice();
} else {
return new BrieSlice();
}
}

}

*Class WITHOUT method body implementations:*

package stuff;

public class CheeseSlicer {

/** @transaction mode=isolated */
public Slice feedMe();

}

To do this is simple. First, QDox can be used to parse the source of a class into a JavaClass. Calling JavaClass.toString() will print out the class without the body implementations (as above). This is something done at development time and the result should be written to a file that is available at runtime.

At runtime, QDox can read this file just as if it were a full-blown Java source file, making the attributes available.

JDK 1.5, of course, makes this redundant, but in the mean time…

Follow

Get every new post delivered to your Inbox.