v2/jam/website/faq.html - xmlbeans - Git at Google

 <html>

 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <title>JAM - FAQ</title>
   <link href="jam.css" rel="stylesheet" type="text/css" />
 </head>

 <body>

 <h1>JAM FAQ</h1>

 <br />

 <h3>What is up with the package name?</h3>

 <p>
 That's the package name it grew up with.  For the moment, JAM is
 still being developed at Apache as part of XBeans (but I'm distributing
 it separately here).  The package will change once JAM finds a permanent
 home.
 </p>


 <br /><br />

 <h3>Why can I get only one JAnnotation of a given type for each
 class/method/field/whatever?</h3>

 <p>
 Sorry, but for better or worse, this is how JSR175 works.  In a given
 scope, you only get to have one annotation declaration of a given
 annotation type.  It only makes sense for JAM to do the same thing.
 </p>


 <br /><br />


 <h3>Why do I have to write all of these JAnnotationProxies?  It seems like
 such a pain.</h3>

 <p>There are two ways this question can be answered; pick the answer you like best:

 <ol>

   <li><u>It really isn't that difficult, especially given the advantages
 they provide, and it will soon be even easier</u>.  Any decent IDE should be able to auto-generate stubs impls for a given 175 interface that you could quickly convert into a AnnotationProxy. And when I have some extra time, I'm going to write a simple compiler that does exactly this from the command line.</li>

   <li><u>You don't actually have to write them</u>.  If you really don't
 want to do write them and are willing to live without
 strongly-typed metadata, you can simply get the values on a 'by-name'
 basis using the <code>MemberValues</code> interface.  Please refer to
 the javadocs for for details.
   </li>

 </ol>
 </p>

 <br /><br />

 <h3>How do I get more control over how JAM maps my JSR175 annotations to my AnnotationProxy?</h3>

 <p>Typically, when implementing a AnnotationProxy, you just extend AnnotationProxy and add your getters and setters.  However, you are free to override
 the base class' implementations of the methods on AnnotationProxy in order
 to customize how data gets set on the proxy.
 </p>

 <br /><br />

 <h3>My program already supports some javadoc tags that don't map very nicely to my AnnotationProxy.  How can I continue to support those tags?</h3>

 <p>You just need to take control of the mapping as described in the answer above.
 </p>


 <br /><br />

 <h3>This AnnotationProxy stuff sounds great and all, but there are some
 cases where I really am going to need to be able to get at the 'real'
 annotation object.</h3>

 <p>
 The <code>JElement</code> interface provides a <code>getArtifact()</code>
 method.  This (usually) will return the object from the underlying
 implementation which is being proxied by the JElement.  In the case
 of a JAnnotation, this (usually) will return an instance of
 <code>java.lang.annotation.Annotation</code> in the case where the
 annotation has been retrieved using 1.5 reflection.  Likewise, if the
 annotation is proxying a javadoc tag, it (usually) will return a
 String containing that tag.
 </p>

 <p>However, use of these methods is generally discouraged,
 since it means your code is making assumptions about how the metadata
 is being represented and parsed - the whole point of using JAM is to
 avoid doing this.  No guarantees made about what
 <code>getArtifact()</code> returns, or whether it will return anything at
 all.
 </p>


 <br /><br />


 <h3>So why doesn't JAM simply recreate the JVM's 'magic' and
 synthesize implementations of 175 annotation types on the fly?</h3>

 <p>That is something that has been considered.  It certainly would not be
 too hard to do, but it would introduce some restrictions that would negate
 many of the advantages that JAM provides.</p>

 <p>First and foremost, it would prevent your annotations from classloading
 under under any pre-1.5 JRE.  175 annotation types all extend
 <code>java.lang.annotation.Annotation</code>, and that class doesn't exist
 in 1.4.  Right off the bat, you would have locked your code into running
 under 1.5.</p>

 <p>Moreover, it's not entirely clear that writing your own implementation
 of a JSR175 annotation interface is a valid thing to do.  The spec doesn't
 say anything about it, but it probably would strike some folks at
 Sun as being at least slightly odd.  I actually have done this with
 1.5 beta 2 and javac makes no complaints, but it's not clear at this point
 that this behavior will always be supported.</p>

 <p>
 Finally, the hot-codegenning the annotation type impls would also remove
 another subtle advantage to the AnnotationProxy approach, which is
 that it allows annotation type authors to introduce behaviors into their
 annotations.  With plain JSR175, it is not possible, for example, to write
 an annotation which performs a simple calculation, or contains any kind of
 logic at all - it's all just dumb data.  With JAnnotationProxies, you control
 the class and you can make it do whatever you want.  While this certainly
 opens the door to people shooting themselves in the foot, I have never been
 an advocate of protecting people from themselves.
 </p>


 <br /><br />


 <h3>Don't you know there already is this or that tool or product 'JAM'?</h3>

 <p>
   Right, I know.  As mentioned above, JAM started out as an internal
   package of another project, so it was not a big concern at first.
   As it found a wider audience, the name just kind of stuck.
 </p>


 </body>
 </html>
	<html>

	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>JAM - FAQ</title>
	<link href="jam.css" rel="stylesheet" type="text/css" />
	</head>

	<body>

	<h1>JAM FAQ</h1>

	<br />

	<h3>What is up with the package name?</h3>

	<p>
	That's the package name it grew up with. For the moment, JAM is
	still being developed at Apache as part of XBeans (but I'm distributing
	it separately here). The package will change once JAM finds a permanent
	home.
	</p>


	<br /><br />

	<h3>Why can I get only one JAnnotation of a given type for each
	class/method/field/whatever?</h3>

	<p>
	Sorry, but for better or worse, this is how JSR175 works. In a given
	scope, you only get to have one annotation declaration of a given
	annotation type. It only makes sense for JAM to do the same thing.
	</p>


	<br /><br />



	<h3>Why do I have to write all of these JAnnotationProxies? It seems like
	such a pain.</h3>

	<p>There are two ways this question can be answered; pick the answer you like best:

	<ol>

	<li><u>It really isn't that difficult, especially given the advantages
	they provide, and it will soon be even easier</u>. Any decent IDE should be able to auto-generate stubs impls for a given 175 interface that you could quickly convert into a AnnotationProxy. And when I have some extra time, I'm going to write a simple compiler that does exactly this from the command line.</li>

	<li><u>You don't actually have to write them</u>. If you really don't
	want to do write them and are willing to live without
	strongly-typed metadata, you can simply get the values on a 'by-name'
	basis using the <code>MemberValues</code> interface. Please refer to
	the javadocs for for details.
	</li>

	</ol>
	</p>

	<br /><br />

	<h3>How do I get more control over how JAM maps my JSR175 annotations to my AnnotationProxy?</h3>

	<p>Typically, when implementing a AnnotationProxy, you just extend AnnotationProxy and add your getters and setters. However, you are free to override
	the base class' implementations of the methods on AnnotationProxy in order
	to customize how data gets set on the proxy.
	</p>

	<br /><br />

	<h3>My program already supports some javadoc tags that don't map very nicely to my AnnotationProxy. How can I continue to support those tags?</h3>

	<p>You just need to take control of the mapping as described in the answer above.
	</p>


	<br /><br />

	<h3>This AnnotationProxy stuff sounds great and all, but there are some
	cases where I really am going to need to be able to get at the 'real'
	annotation object.</h3>

	<p>
	The <code>JElement</code> interface provides a <code>getArtifact()</code>
	method. This (usually) will return the object from the underlying
	implementation which is being proxied by the JElement. In the case
	of a JAnnotation, this (usually) will return an instance of
	<code>java.lang.annotation.Annotation</code> in the case where the
	annotation has been retrieved using 1.5 reflection. Likewise, if the
	annotation is proxying a javadoc tag, it (usually) will return a
	String containing that tag.
	</p>

	<p>However, use of these methods is generally discouraged,
	since it means your code is making assumptions about how the metadata
	is being represented and parsed - the whole point of using JAM is to
	avoid doing this. No guarantees made about what
	<code>getArtifact()</code> returns, or whether it will return anything at
	all.
	</p>


	<br /><br />



	<h3>So why doesn't JAM simply recreate the JVM's 'magic' and
	synthesize implementations of 175 annotation types on the fly?</h3>

	<p>That is something that has been considered. It certainly would not be
	too hard to do, but it would introduce some restrictions that would negate
	many of the advantages that JAM provides.</p>

	<p>First and foremost, it would prevent your annotations from classloading
	under under any pre-1.5 JRE. 175 annotation types all extend
	<code>java.lang.annotation.Annotation</code>, and that class doesn't exist
	in 1.4. Right off the bat, you would have locked your code into running
	under 1.5.</p>

	<p>Moreover, it's not entirely clear that writing your own implementation
	of a JSR175 annotation interface is a valid thing to do. The spec doesn't
	say anything about it, but it probably would strike some folks at
	Sun as being at least slightly odd. I actually have done this with
	1.5 beta 2 and javac makes no complaints, but it's not clear at this point
	that this behavior will always be supported.</p>

	<p>
	Finally, the hot-codegenning the annotation type impls would also remove
	another subtle advantage to the AnnotationProxy approach, which is
	that it allows annotation type authors to introduce behaviors into their
	annotations. With plain JSR175, it is not possible, for example, to write
	an annotation which performs a simple calculation, or contains any kind of
	logic at all - it's all just dumb data. With JAnnotationProxies, you control
	the class and you can make it do whatever you want. While this certainly
	opens the door to people shooting themselves in the foot, I have never been
	an advocate of protecting people from themselves.
	</p>


	<br /><br />




	<h3>Don't you know there already is this or that tool or product 'JAM'?</h3>

	<p>
	Right, I know. As mentioned above, JAM started out as an internal
	package of another project, so it was not a big concern at first.
	As it found a wider audience, the name just kind of stuck.
	</p>



	</body>
	</html>