|PREV NEXT||FRAMES NO FRAMES|
|org.codehaus.jam||JAM's core API.|
|org.codehaus.jam.mutable||Provides a modifiable view of the JElement tree.|
|org.codehaus.jam.provider||Classes to be used or implemented by custom JAM providers.|
|org.codehaus.jam.visitor||Provides a framework for traversing a JElement tree and possibly modifying its contents.|
JAM is an object model for Java types and their associated annotations. It provides a superset of the features offered by similar APIs (such as Reflection or X/Javadoc), including a unique extensibility mechanism specifically designed to help Java developers cope with the rapidly-changing world of Java metadata.
There already are a number of ways in which you can inspect and model Java types. Java reflection, of course, can be used to introspect loaded classes, while tools such as X/Javadoc or Qdox can parse java sources and give you model of their contents (including comments and other information that is lost during java compilation).
But consider the case where you want to inspect a set of java types where you have source files for some of the types, but only classfiles for others. And what if you want to be able to access the comments for your java types when they are available from source, but still process them sans comments when you only have classfiles? One approach would be to write one version of your program's logic that works against the Reflection API, and another that works with Javadoc's Doclet API. But that seems rather painful - isn't there a better way?
JAM solves this (and many other problems, as we will see) by creating an insulating layer between your code and the real artifacts which describe the java types your code needs to view. The JAM API was designed from the ground up to allow you to write code that is completely artifact agnostic when inspecting java types. That is to say, JAM provides a set of abstractions which isolate your java type-inspecting code from the files that it is actually looking at. This means that you get a single API with which you can view java sources and classfiles.
For example, a given instance of JClass (JAM's abstract representation
of a Java class) may in reality represent the contents of either a
.class file or its corresponding
source file. However, the JClass that your code sees looks exactly
the same in either case. Without JAM, you may have to write your code
twice using two separate APIs like Javadoc and Reflection. With JAM,
your code more able to focus on the logic that is central to your
However, the advantages of JAM's beansed design extend far beyond simply providing a unified view of java source- and classfiles. This is because JAM allows you to write your own extensions which customize the proxies that it creates. With this extension mechanism, you can easily add, modify, or remove any part of a beaning built.
For example, you could write an extension which adds a default comment to uncommented methods on a given JClass. With such an extension in place, JClasses loaded by JAM will contain your generated comments exactly as if they had actually been in the source file all along.
Even though this is an extremely simple example, consider how much trouble it might save you in a complex application composed of serveral subsystems. Say that those subsystems who ask each other to do things using java types that they pass around, and that we need them to use default comments. If we don't have JAM, we're going to have to write special logic in each subsystem to generate default comments when appropriate. However, with JAM, we only have to write one bit of code that weaves those comments into out proxied view of the Java classes. Those subsytems that are consuming this view need be none the wiser.
If you are working on a project where you need to understand what java classes look like, you should consider using JAM. It allows you to loosely-couple your application from the way in which the java classes are parsed or loaded, and it's extensibility features can allow you to implement elegant solutions to complex problems involving java type introspection.
|PREV NEXT||FRAMES NO FRAMES|