<body>

<p>
JAM's core API.  This package includes JAM's factory mechanism
(the Jam* classes) as well as object model (J* classes) which
are used to model a set of Java types.
</p>

<!--

<p>
The Java API for Metadata (JAM) provides a representation of
Java abstractions (such as classes and methods) and their 
associated metadata.  This model serves to decouple its clients' code 
from any specific introspection mechanism such as javadoc or reflection.
</p>

<p>This approach has several key advantages:</p>
<ul>

  <li><b>A unified introspection API for sources and classes.</b>
  In fact, source- and class-based representations can be freely 
  interwoven, if desired.</li>
<p>
  <li><b>A measure of certainty in an uncertain world.</b>
  Metadata is a hot topic at the moment, and the way we deal with it
  is going to change dramatically over the next year or two.
  By writing to the JAM API, you can be sure that you won't
  have to rewrite your code to accommodate emerging tools and standards
  (JSR175, for example).</li>
<p>
  <li><b>Pluggable metadata stores.</b>
  Metadata can be retrieved from an external source (such as an XML file) 
  or even generated programmatically.  This also allows metadata to 
  be associated with java constructs that may not normally support 
  annotations (such as packages).</li>
<p>
  <li><b>A Node-based view of Java constructs.</b> 
  JAM clients have the option of viewing their java constructs as a tree 
  of generic, DOM-like nodes (packages contain classes, classes contain 
  methods) each of which may have associated annotations.  This is 
  extremely helpful for tools which wish to support annotation
  inheritance.</li>

</ul>


<h3>Comparison of Java Type Inspection Technologies</h3>


<table border='1'>
  <tr>
    <td />
    <td colspan='2' align='center'>JDK 1.4</td>
    <td colspan='2' align='center'>JDK 1.5</td>
  </tr>
  <tr>
    <td />
    <td>Javadoc</td>
    <td>Reflect</td>
    <td>Javadoc</td>
    <td>Reflect</td>
    <td>JavaBeans</td>
    <td>XDoclet</td>
    <td>QDox</td>
    <td>JAM</td>
  </tr>

  <tr>
    <td>JSR-175 from sources</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>JSR-175 from classfiles</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Javadoc-style metadata from source</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td>?</td>
    <td>no</td>
    <td>no</td>
    <td>?</td>
    <td>?</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Line/column number info</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no(1)</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no(1)</td>
    <td>no(1)</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Retrieve comments from source</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Method parameter names</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no(1)</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no(1)</td>
    <td>no(1)</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Overlay external metadata</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Full introspection of 175 annotation types<br>
        (including default values)</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>


  <tr>
    <td>Parse invalid source files</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Extensibility/SPI</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  <tr>
    <td>Supports 'Property' abstraction</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
    <td>no</td>
    <td>no</td>
    <td bgcolor='#22DD22'>yes</td>
  </tr>

  </table>

<h4>notes</h4>
<p>
    (1) This information is embedded in the .class files when the -g debug
        flag specified on javac so that it can be displayed in stack
        traces.  However, there still is no API provided for retrieving 
        this information at runtime.<br />
</p>


-->

</body>