Attachment #223427 for bug #213636

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.




<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
<html>
    <head>
       <meta http-equiv="refresh" content="0; url=faq.php" />
    </head>
    <body>
       <a href="faq.php">This page has moved. Please update your links and bookmarks.</a>
    </body>
<body text="#000000" bgcolor="#FFFFFF">
&nbsp;

<table border=0 cellspacing=5 cellpadding=2 width="100%" >
  <tr>
    <td align=left width="72%"> <font class=indextop> FAQ </font> <br>
      <font class=indexsub> annotation processing in eclipse </font></td>
    <td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
  </tr>
</table>


<table border=0 cellspacing=5 cellpadding=2 width="100%" >
<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0">
<b><font face="Arial,Helvetica"><font color="#FFFFFF">Frequently Asked Questions</font></font></b></td>
</tr>

<tr>
<td COLSPAN="2">

<ol>

<b><li>What are annotations?</b>
<p>
Annotations are a simple metadata facility added to the Java language. Annotations can be
used anywhere a modifier can be used, like <code>public</code>, <code>static</code>, and <code>final</code>.
These annotations can be used at build or run-time in myriad ways. Here's an example annotation:

<pre>
public class Foo {

  <font color="#FF0000">@Override</font>
  public int hashCode() {
    return super.hashCode() ^ 1;
  }
}
</pre>

This indicates that the method <code>hashCode</code> must override a method
with the same signature in its superclass. If the method name were spelled wrong, a
processor could notice this and issue an error.

<p>
Standard uses for annotation processors include EJB and Web Services generators.

<p>
Additional information on annotations can be found in the Java documentation
<a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">here</a>.

<p>
<b><li>When were annotations added to the Java language?</b>
<p>
Java 5 added annotation to the core language.

<p>
<b><li>How does jdt-apt extend basic JDT support?</b>
<p>
We hook into the JDT compiler. If an annotation is detected, we dispatch to any processors that
claim that annotation. We then provide an implementation of the mirror APIs over the
JDT typesystem. If a processor creates a new source file, we then call the necessary
JDT APIs to perform compilation on that new file.

<p>
<b><li>Can I use an existing processor I wrote for the commandline "apt" tool inside of eclipse?</b>
<p>
Yes! This is one of the major goals of the jdt-apt project: you should be able to use an existing
processor directly inside of eclipse and get an interactive experience, provided your processor is
reasonably quick and efficient.

<p>
<b><li>Are the errors from my processor different from other JDT errors?</b>
<p>
No. They're treated just like any other error.

<p>
<b><li>Can I get quick-fixes inside annotation values?</b>
<p>
Yes. When you create your error markers via the Messager API, downcast
to EclipseMessager, and use the printFixable...() APIs. These
error markers can then be processed with a QuickFixProcessor via 
the JDT APIs in Eclipse.<p>

</ol>

</td>
</tr>


</table>

<br>&nbsp;
</body>
</html>




<?php  																														require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php");	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); 	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); 	$App 	= new App();	$Nav	= new Nav();	$Menu 	= new Menu();		include($App->getProjectCommon());    # All on the same line to unclutter the user's desktop'
#
# Begin: page-specific settings.  Change these.
$pageTitle 		= "JDT-APT FAQ";
$pageKeywords	= "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
$pageAuthor		= "JDT/APT team";
# End: page-specific settings
# Paste your HTML content between the markers!
ob_start();
?>

<div id="midcolumn">
	<h1>
		<?= $pageTitle ?>
	</h1>
	<div class="homeitem3col">
		<h3>Frequently Asked Questions</h3>
		<ol>
			<li>
				<strong>What are annotations?</strong>
				<p>
					Annotations are a simple metadata facility added to the Java
					language. Annotations can be used anywhere a modifier can be used,
					like <code>public</code>, <code>static</code>, and <code>final</code>.
					These annotations can be used at build or run-time in myriad ways.
					Here's an example annotation:
				<p>
				<pre>
public class Foo {

  <font color="#FF0000">@Override</font>
  public int hashCode() {
    return super.hashCode() ^ 1;
  }
}
				</pre>
				<p>
					This indicates that the method <code>hashCode</code>
					must override a method with the same signature in its superclass. 
					If the method name were spelled wrong, a processor could notice 
					this and issue an error.
				</p>
				<p>
					Standard uses for annotation processors include EJB and Web Services generators.
				</p>
				<p>
					Additional information on annotations can be found in the Java documentation 
					<a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">here</a>.
				</p>
			</li>
			<li>
				<strong>When were annotations added to the Java language?</strong>
				<p>Java 5 added annotation to the core language.</p>
			</li>
			<li>
				<strong>How does jdt-apt extend basic JDT support?</strong>
				<p>
					We hook into the JDT compiler. If an annotation is detected, we
					dispatch to any processors that claim that annotation. We then
					provide an implementation of the mirror APIs over the JDT
					typesystem. If a processor creates a new source file, we then call
					the necessary JDT APIs to perform compilation on that new file.
				</p>
			</li>
			<li>
				<strong>Can I use an existing processor I wrote for the commandline "apt" tool inside of eclipse?</strong>
				<p>
					Yes! This is one of the major goals of the jdt-apt project: you
					should be able to use an existing processor directly inside of
					eclipse and get an interactive experience, provided your processor
					is reasonably quick and efficient.
				</p>
			</li>
			<li>
				<strong>Are the errors from my processor different from other JDT errors?</strong>
				<p>
					No. They're treated just like any other error.
				</p>
			</li>
			<li>
				<strong>Can I get quick-fixes inside annotation values?</strong>
				<p>
					Yes. When you create your error markers via the Messager API,
					downcast to EclipseMessager, and use the printFixable...() APIs.
					These error markers can then be processed with a QuickFixProcessor
					via the JDT APIs in Eclipse.
				</p>
			</li>
		</ol>
	</div>
</div>
<?php
$html = ob_get_contents();
ob_end_clean();

# Generate the web page
$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>




<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
    <head>
       <meta http-equiv="refresh" content="0; url=index.php" />
    </head>
    <body>
       <a href="index.php">This page has moved. Please update your links and bookmarks.</a>
    </body>
</html>
  <frameset cols="126,*" frameborder=0 framespacing=0 border="0"> 
    <frameset rows="220, *"  frameborder=0 framespacing=0 border="0"> 
      <frame name="home_nav" scrolling="no" noresize target="main" 
                          src="../../home_nav.html"  marginwidth="0" marginheight="0" frameborder="NO">
      <frame name="nav" scrolling="no" noresize target="main" 
                          src="../../eclipse/nav.html"  marginwidth="0" marginheight="0" frameborder="NO">
    </frameset>
    <frame name="main" marginwidth=10 marginheight=10 noresize frameborder="NO" src="main.html">
  </frameset>
  <noframes> 
  <body>
  <p>This page uses frames, but your browser doesn't support them.</p>
  </body>
  </noframes> </frameset>
</html>




<?php  																														require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php");	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); 	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); 	$App 	= new App();	$Nav	= new Nav();	$Menu 	= new Menu();		include($App->getProjectCommon());    # All on the same line to unclutter the user's desktop'
#
# Begin: page-specific settings.  Change these.
$pageTitle 		= "Eclipse JDT-APT Project";
$pageKeywords	= "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
$pageAuthor		= "JDT/APT team";
# End: page-specific settings
# Paste your HTML content between the markers!
ob_start();
?>

<div id="midcolumn">
	<h1>
		<?= $pageTitle ?>
	</h1>
	<div class="homeitem3col">
		<h3>What is the JDT-APT project?</h3>
		<p>
			The JDT-APT project provides plugins that add Java 5 annotation
			processing support to Eclipse. A Java annotation processor is a
			compiler plug-in that can gather information about source code as it
			is being compiled, generate additional Java types or other resource
			files, and post warnings and errors. Eclipse 3.2 provided support for
			annotation processors using the <a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
			and Eclipse 3.3 added support for processors using the <a href="http://java.sun.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
				Java 6 annotation processing APIs</a>.
		</p>
		<p>
			You can view the presentation given at JavaOne 2005 during a session
			on APT that describes some of the goals and technical details <a
				href="javaone_apt.ppt">here</a>. At EclipseCon 2006 we made a <a
				href="Eclipsecon2006.ppt">presentation</a> on APT do's and don'ts,
			and at EclipseCon 2007 this was developed into a <a
				href="eclipsecon2007.zip">tutorial</a> on writing annotation
			processors for Eclipse, including some sample code and more
			discussion of techniques to achieve good performance. At EclipseCon
			2008 we gave a <a href="eclipsecon2008.ppt">presentation</a> on
			annotations (which briefly mentions annotation processors but does
			not go into depth) that may be of interest to those looking for
			background material or for alternative strategies to annotation
			processing.
		</p>
		<p>
			Additional frequently asked questions and their answers can be found
			in our <a href="faq.php">FAQ</a>.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>What is APT?</h3>
		<p>
			APT stands for Annotation Processing Tool. Sun shipped an API for APT
			in JDK 1.5, which can be viewed at <a
				href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html">
				http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html</a>.
			Sun also included a commandline implementation of APT in JDK 1.5. You
			can find documentation for it at <a
				href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html"
				target="_blank">http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html</a>.
			In JDK 6, the API was modified considerably and standardized through
			JSR-269, and the Sun implementation was built into the javac compiler
			rather than requiring a standalone tool.
		</p>
		<p>To quote from Sun's documentation:</p>
		<p>
			<code>
				apt is a command-line utility for annotation processing. It includes
				a set of reflective APIs and supporting infrastructure to process
				program annotations (JSR 175). These reflective APIs provide a
				build-time, source-based, read-only view of program structure. They
				are designed to cleanly model the Java<sup><small>TM</small>
				</sup> programming language's type system after the addition of
				generics (JSR 14).
			</code>
		</p>
		<p>
			So, APT provides a means for generating files and compiling new
			java classes based on annotations found in your source code.
		</p>
		<p>
			JDT-APT is not based on Sun's implementation, but rather is a
			separate implementation of the APT APIs that runs entirely within
			Eclipse.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>How do I get started?</h3>
		<p>
			If all you need to do is use an annotation processor, you may not
			need to do anything at all! Many project creation wizards will
			automatically install and enable the necessary processors. To check
			whether this is the case, or to install and enable your own
			processors, use the Java Compiler -&gt; Annotation Processing pane of
			the project properties.</p>
		<p>
			If you need to write your own annotation processor, see <a
				href="introToAPT.php">Intro to APT</a> to get started using APT,
			and also see the EclipseCon 2007 tutorial mentioned above.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>How can I contribute?</h3>
		<p>
			If you're interested in contributing, start by checking the code out of CVS. 
			See the instructions <a href="howtobuildme.txt">here</a>.
		</p>
		<p>
			You can also check out the mailing list, 
			<a href="http://dev.eclipse.org/mailman/listinfo/jdt-apt-dev">jdt-apt-dev@eclipse.org</a>,
			or post questions to the eclipse.tools.jdt 
			<a href="http://www.eclipse.org/newsgroups/">newsgroup</a>. 
			The mailing list is primarily for announcements and discussion by people working
			on the APT tooling in Eclipse; if you have technical questions, it is
			best to use the newsgroup.
		</p>
	</div>
</div>
<?php
$html = ob_get_contents();
ob_end_clean();

# Generate the web page
$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>




<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
<html>
    <head>
       <meta http-equiv="refresh" content="0; url=introToAPT.php" />
    </head>
    <body>
       <a href="introToAPT.php">This page has moved. Please update your links and bookmarks.</a>
    </body>
</html>
&nbsp;

<table border=0 cellspacing=5 cellpadding=2 width="100%" >
  <tr>
    <td align=left width="72%"> <font class=indextop> Introduction to the Annotation Processing Feature </font> <br>
      <font class=indexsub> annotation processing in eclipse </font></td>
    <td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
  </tr>
</table>


<table border=0 cellspacing=5 cellpadding=2 width="100%" >

<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Disclaimer</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2">
This is a BETA release. All APIs contained herein are provisional, and subject to change with subsequent updates.


<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Testing your APT installation</font></font></b></td>
</tr>

<tr>
<td COLSPAN="2">
The APT feature is part of Eclipse 3.2, as of M5a and later. 

If you wish to use Eclipse 3.1, see the <a href="installOn3.1.html">3.1 installation instructions</a>.
<p>

You can verify the installation on either version this way:
<ul>
<li>Create a Java project which contains the file <a href="APTDemo.jar">APTDemo.jar</a> in its filesystem.</li>
<li>Open the project properties dialog, and go to the Java&nbsp;Compiler / Annotation&nbsp;Processing panel.</li>
<li>Check "Enable Project Specific Settings" and "Enable Annotation Processing".</li>
<li>Now open the Java&nbsp;Compiler / Annotation&nbsp;Processing / Factory&nbsp;Path panel.</li>
<li>Click on Add Jars... and add the APTDemo.jar.</li>
<li>Create a new Class, and annotate the class in the source file with @DemoAnnotation(what = "spam").</li>
</ul>

The "spam" value should be squiggled, with the message "I don't like spam".

<ul>
<li>Annotate the same class with @TypeGeneratingAnnotation</li>
<li>Build the project.</li>
</ul>

A new source directory should appear in the project, named .apt_generated, that will contain a generated
Java source file called GeneratedFileTest.java.  <i>The generated source directory will not be visible by
default in the Package Explorer, because it starts with a '.', but it will be visible in the Navigator.</i>



</td>
</tr>

<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Installing and Configuring
Annotation Processors</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2"><font color="#000000">
An annotation processor can run in Eclipse from a .jar file contained in a project, a .jar file external to the workspace, or a plugin.
Jars are added to a workspace or project though the Properties Dialog, Factory Path pane:
<p>

<img src="PropertiesDialog.gif">

<p>
For an example of how to set up a plugin project to develop a processor, download <a href="APTDemo.jar">APTDemo.jar</a> and explode it into a workspace and import it as an existing
project. Eclipse locates plugins along a factory path, which can be configured at the workspace or project level. Workspace configuration
is picked up as the default for projects that have annotation processing enabled (see the Properties dialog shown above). If the factory
path is configured for an individual project, that project will no longer see changes to the workspace configuration; you will have to
update it manually.

<p>
A plugin that contains a factory must extend the annotationProcessorFactory extension point. Here is the example from the plugin
in APTDemo.jar. Each Factory class contained in the plugin must be named in the class=attribute.
<pre>
   &lt;extension
         point="org.eclipse.jdt.apt.core.annotationProcessorFactory">
      &lt;factories enableDefault="true">
	      &lt;factory
	         class="demo.TypeGeneratingAnnotationProcessorFactory">
	      &lt;/factory>
	      &lt;factory
	         class="demo.DemoAnnotationProcessorFactory">
	      &lt;/factory>
      &lt;/factories>
   &lt;/extension>
</pre>
More details about this will follow when we deliver an SDK version of the feature.


<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Debugging Annotation Processors in
Eclipse</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2"><font color="#000000">
To debug an annotation processor it must be run from a plugin. You develop your code in the plugin, and then debug it by
annotating source code in a spawned instance of
Eclipse. The debugging instance needs the annotation declaration, the factory, and the processor. The spawned instance
only needs access to the declaration.


</font></td>
</tr>

<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
Problems and Bugs</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2"><font color="#000000">
Symptom: nothing happens, no errors in log file.
<ul>
<li>Make sure that annotation processing is enabled in the Project Properties.</li>
</ul>
<p>
Symptom: annotations not getting processed, log file contains "Bundle not resolved" warnings, ClassNotFound errors or "No Classloader found" errors.
<ul>
<li>Make sure that you are using a 1.5 JVM to run Eclipse.  Although most of Eclipse can run on a 1.4 JVM, the APT plugins require a 1.5 JVM.</li>
</ul>

<p>
Please post questions to the JDT newsgroup (eclipse.tools.jdt). Post bugs related to this feature in Bugzilla, under Product JDT, Component APT.

<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Feature Enable/Disable in Eclipse 3.1.2</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2"><font color="#000000">
If you installed APT as an update to Eclipse 3.1.2 and you have a problem with the compiler, you can disable the feature through the Product Configuration dialog
(Menu item Help / Software&nbsp;Updates / Manage&nbspConfiguration).
<p>
<img src="ProductConfigDialog.jpg">

<p>
Select the JdtAptFeature from your Eclipse installation and click <b>Disable</b>.
Your Eclipse will now use the unchanged, original version of the compiler. To re-enable the feature you need to click on the Show Disabled
Features on the toolbar of this dialog.


</td>
</tr>
</table>

<br>&nbsp;
</body>
</html>




<?php  																														require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php");	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); 	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); 	$App 	= new App();	$Nav	= new Nav();	$Menu 	= new Menu();		include($App->getProjectCommon());    # All on the same line to unclutter the user's desktop'
#
# Begin: page-specific settings.  Change these.
$pageTitle 		= "Introduction to Annotation Processing in Eclipse";
$pageKeywords	= "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
$pageAuthor		= "JDT/APT team";
# End: page-specific settings
# Paste your HTML content between the markers!
ob_start();
?>

<div id="midcolumn">
	<h1>
		<?= $pageTitle ?>
	</h1>
	<div class="homeitem3col">
		<h3>Disclaimer</h3>
		<p>
			This is a BETA release. All APIs contained herein are provisional, and subject to change with subsequent updates.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>Testing your APT installation</h3>
		<p>
			The APT feature is part of Eclipse 3.2, as of M5a and later. If you wish to use Eclipse 3.1, 
			see the <a href="installOn3.1.html">3.1 installation instructions</a>.
		</p>
		<p>You can verify the installation on either version this way:</p>
		<ul>
			<li>Create a Java project which contains the file <a href="APTDemo.jar">APTDemo.jar</a> in its filesystem.</li>
			<li>Open the project properties dialog, and go to the Java&nbsp;Compiler / Annotation&nbsp;Processing panel.</li>
			<li>Check "Enable Project Specific Settings" and "Enable Annotation Processing".</li>
			<li>Now open the Java&nbsp;Compiler / Annotation&nbsp;Processing / Factory&nbsp;Path panel.</li>
			<li>Click on Add Jars... and add the APTDemo.jar.</li>
			<li>Create a new Class, and annotate the class in the source file with @DemoAnnotation(what = "spam").</li>
		</ul>
		<p>The "spam" value should be squiggled, with the message "I don't like spam".</p>
		<ul>
			<li>Annotate the same class with @TypeGeneratingAnnotation</li>
			<li>Build the project.</li>
		</ul>
		<p>
			A new source directory should appear in the project, named .apt_generated, that will contain a
			generated Java source file called GeneratedFileTest.java. <i>The generated source directory
			will not be visible by default in the Package Explorer, because it starts with a '.', but it
			will be visible in the Navigator.</i>
		</p>
	</div>
	<div class="homeitem3col">
		<h3>Installing and Configuring Annotation Processors</h3>
		<p>
			An annotation processor can run in Eclipse from a .jar file contained in a project, a .jar file 
			external to the workspace, or a plugin. Jars are added to a workspace or project though 
			the Properties Dialog, Factory Path pane:
		</p>
		<img src="PropertiesDialog.gif">
		<p>
			For an example of how to set up a plugin project to develop a processor, download 
			<a href="APTDemo.jar">APTDemo.jar</a> and explode it into a workspace and import it as an
			existing project. Eclipse locates plugins along a factory path, which can be configured at the
			workspace or project level. Workspace configuration is picked up as the default for projects
			that have annotation processing enabled (see the Properties dialog shown above). If the
			factory path is configured for an individual project, that project will no longer see changes
			to the workspace configuration; you will have to update it manually.
		</p>
		<p>
			A plugin that contains a factory must extend the annotationProcessorFactory extension
			point. Here is the example from the plugin in APTDemo.jar. Each Factory class contained in the
			plugin must be named in the class=attribute.
		</p>
			<pre>
   &lt;extension
         point="org.eclipse.jdt.apt.core.annotationProcessorFactory">
      &lt;factories enableDefault="true">
	      &lt;factory
	         class="demo.TypeGeneratingAnnotationProcessorFactory">
	      &lt;/factory>
	      &lt;factory
	         class="demo.DemoAnnotationProcessorFactory">
	      &lt;/factory>
      &lt;/factories>
   &lt;/extension>
			</pre>
		<p>
			More details about this will follow when we deliver an SDK version of the feature.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>Debugging Annotation Processors in Eclipse</h3>
		<p>
			To debug an annotation processor it must be
			run from a plugin. You develop your code in the plugin, and then debug it by annotating
			source code in a spawned instance of Eclipse. The debugging instance needs the annotation
			declaration, the factory, and the processor. The spawned instance only needs access to the
			declaration.
		</p>
	</div>
	<div class="homeitem3col">
		<h3>Problems and Bugs</h3>
		<div>
			<p>Symptom: nothing happens, no errors in log file.</p>
			<ul>
				<li>Make sure that annotation processing is enabled in the Project Properties.</li>
			</ul>
			<p>Symptom: annotations not getting processed, log file contains "Bundle not resolved"
				warnings, ClassNotFound errors or "No Classloader found" errors.</p>
			<ul>
				<li>Make sure that you are using a 1.5 JVM to run Eclipse. Although most of Eclipse
					can run on a 1.4 JVM, the APT plugins require a 1.5 JVM.</li>
			</ul>
			<p>Please post questions to the JDT newsgroup (eclipse.tools.jdt). Post bugs related to
				this feature in Bugzilla, under Product JDT, Component APT.
			</p>
		</div>
	</div>
	<div class="homeitem3col">
		<h3>Feature Enable/Disable in Eclipse 3.1.2</h3>
		<p>
			If you installed APT as an update to
			Eclipse 3.1.2 and you have a problem with the compiler, you can disable the feature
			through the Product Configuration dialog (Menu item Help / Software&nbsp;Updates /
			Manage&nbsp;Configuration).
		</p>
		<img src="ProductConfigDialog.jpg">
		<p>
			Select the JdtAptFeature from your Eclipse installation and click <b>Disable</b>. Your
			Eclipse will now use the unchanged, original version of the compiler. To re-enable the
			feature you need to click on the Show Disabled Features on the toolbar of this dialog.
		</p>
	</div>
</div>
<?php
$html = ob_get_contents();
ob_end_clean();

# Generate the web page
$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>




<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
<html>
    <head>
       <meta http-equiv="refresh" content="0; url=index.php" />
    </head>
    <body>
       <a href="index.php">This page has moved. Please update your links 
and bookmarks.</a>
    </body>
</html>

<table border=0 cellspacing=5 cellpadding=2 width="100%" >
  <tr>
    <td align=left width="72%"> <font class=indextop> jdt-apt </font> <br>
      <font class=indexsub> annotation processing in eclipse </font></td>
    <td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
  </tr>
</table>


<table border=0 cellspacing=5 cellpadding=2 width="100%" >
<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">What is the JDT-APT project?</font></font></b></td>
</tr>

<tr>
<td COLSPAN="2">The JDT-APT project provides plugins that add Java 5 annotation processing support to Eclipse.

A Java annotation processor is a compiler plug-in that can gather information about source code as 
it is being compiled, generate additional Java types or other resource files, and post warnings 
and errors. Eclipse 3.2 provided support for annotation processors using the 
<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
and Eclipse 3.3 added support for processors using the 
<a href="http://java.sun.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
Java 6 annotation processing APIs</a>.</p>
<p>
You can view the presentation given at JavaOne 2005 during a session on APT that describes some of the goals
and technical details <a href="javaone_apt.ppt">here</a>. At EclipseCon 2006 we made a
<a href="Eclipsecon2006.ppt">presentation</a> on APT do's and don'ts, and at EclipseCon 2007 this was
developed into a <a href="eclipsecon2007.zip">tutorial</a> on writing annotation processors for Eclipse,
including some sample code and more discussion of techniques to achieve good performance. At EclipseCon 2008
we gave a <a href="eclipsecon2008.ppt">presentation</a> on annotations (which briefly mentions annotation
processors but does not go into depth) that may be of interest to those looking for background material
or for alternative strategies to annotation processing.

<p>
Additional frequently asked questions and their answers can be found in our <a href="faq.html">FAQ</a>.

</td>
</tr>

<tr>
<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
What is APT?</font></font></b></td>
</tr>
<tr>
<td COLSPAN="2"><font color="#000000">APT stands for Annotation Processing Tool. 
Sun shipped an API for APT in JDK 1.5, which can be viewed at
<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html">
http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html</a>. Sun also included a commandline 
implementation of APT in JDK 1.5. You can find documentation for it at
<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html" target="_blank">http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html</a>.
In JDK 6, the API was modified considerably and standardized through JSR-269, and the Sun implementation was
built into the javac compiler rather than requiring a standalone tool.
<p>
To quote from Sun's documentation:
<p>
<code>
apt is a command-line utility for annotation processing.
It includes a set of reflective APIs and supporting infrastructure to
process program annotations (JSR 175).
These reflective APIs provide a build-time, source-based,
read-only view of program structure.  They are designed to cleanly model
the Java<sup><small>TM</small></sup>
programming language's type system after the addition of generics (JSR 14).
</code>

<p>
So, APT provides a means for generating files and compiling new java classes based on annotations
found in your source code.

<p>
JDT-APT is not based on Sun's implementation, but rather is a separate implementation of
the APT APIs that runs entirely within Eclipse.

</font></td>
</tr>




<tr><td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
How do I get started?</font></font></b>
</td></tr>

<tr>
<td COLSPAN="2"><font color="#000000">
<p>
If all you need to do is use an annotation processor, you may not need to do anything at all! Many project
creation wizards will automatically install and enable the necessary processors. To check whether this
is the case, or to install and enable your own processors, use the Java Compiler -&gt; Annotation Processing
pane of the project properties.
<p>
If you need to write your own annotation processor, see <a href="introToAPT.html">Intro to APT</a> to get 
started using APT, and also see the EclipseCon 2007 tutorial mentioned above.
</font></td>
</tr>


<tr>
<td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
How can I contribute?</font></font></b></td>
</tr>

<tr>
<td COLSPAN="2">If you're interested in contributing, start by checking the code out of CVS. See the instructions
<a href="howtobuildme.txt">here</a>.

<p>
You can also check out the mailing list,
<a href="http://dev.eclipse.org/mailman/listinfo/jdt-apt-dev">jdt-apt-dev@eclipse.org</a>,
or post questions to the eclipse.tools.jdt <a href="http://www.eclipse.org/newsgroups/">newsgroup</a>.
The mailing list is primarily for announcements and discussion by people working on the APT tooling
in Eclipse; if you have technical questions, it is best to use the newsgroup.


</td>
</tr>
</table>

<br>&nbsp;
</body>
</html>

Return to bug 213636

Lines 1-102 Link Here

(-)a/apt/faq.html (-100 / +7 lines)
1	<!doctype html public "-//w3c//dtd html 4.0 transitional//en">	1	<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
2	<html>	2	<html>
3	<head>	3	<head>
4	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">	4	<meta http-equiv="refresh" content="0; url=faq.php" />
5	<meta name="GENERATOR" content="Mozilla/4.73 [en] (Windows NT 5.0; U) [Netscape]">	5	</head>
6	<title>JDT-APT FAQ</title>	6	<body>
7	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">	7	<a href="faq.php">This page has moved. Please update your links and bookmarks.</a>
8	</head>	8	</body>
9	<body text="#000000" bgcolor="#FFFFFF">
10
11
12	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
13	<tr>
14	<td align=left width="72%"> <font class=indextop> FAQ </font> <br>
15	<font class=indexsub> annotation processing in eclipse </font></td>
16	<td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
17	</tr>
18	</table>
19
20
21	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
22	<tr>
23	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0">
24	<b><font face="Arial,Helvetica"><font color="#FFFFFF">Frequently Asked Questions</font></font></b></td>
25	</tr>
26
27	<tr>
28	<td COLSPAN="2">
29
30	<ol>
31
32	<b><li>What are annotations?</b>
33	<p>
34	Annotations are a simple metadata facility added to the Java language. Annotations can be
35	used anywhere a modifier can be used, like <code>public</code>, <code>static</code>, and <code>final</code>.
36	These annotations can be used at build or run-time in myriad ways. Here's an example annotation:
37
38	<pre>
39	public class Foo {
40
41	<font color="#FF0000">@Override</font>
42	public int hashCode() {
43	return super.hashCode() ^ 1;
44	}
45	}
46	</pre>
47
48	This indicates that the method <code>hashCode</code> must override a method
49	with the same signature in its superclass. If the method name were spelled wrong, a
50	processor could notice this and issue an error.
51
52	<p>
53	Standard uses for annotation processors include EJB and Web Services generators.
54
55	<p>
56	Additional information on annotations can be found in the Java documentation
57	<a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">here</a>.
58
59	<p>
60	<b><li>When were annotations added to the Java language?</b>
61	<p>
62	Java 5 added annotation to the core language.
63
64	<p>
65	<b><li>How does jdt-apt extend basic JDT support?</b>
66	<p>
67	We hook into the JDT compiler. If an annotation is detected, we dispatch to any processors that
68	claim that annotation. We then provide an implementation of the mirror APIs over the
69	JDT typesystem. If a processor creates a new source file, we then call the necessary
70	JDT APIs to perform compilation on that new file.
71
72	<p>
73	<b><li>Can I use an existing processor I wrote for the commandline "apt" tool inside of eclipse?</b>
74	<p>
75	Yes! This is one of the major goals of the jdt-apt project: you should be able to use an existing
76	processor directly inside of eclipse and get an interactive experience, provided your processor is
77	reasonably quick and efficient.
78
79	<p>
80	<b><li>Are the errors from my processor different from other JDT errors?</b>
81	<p>
82	No. They're treated just like any other error.
83
84	<p>
85	<b><li>Can I get quick-fixes inside annotation values?</b>
86	<p>
87	Yes. When you create your error markers via the Messager API, downcast
88	to EclipseMessager, and use the printFixable...() APIs. These
89	error markers can then be processed with a QuickFixProcessor via
90	the JDT APIs in Eclipse.<p>
91
92	</ol>
93
94	</td>
95	</tr>
96
97
98	</table>
99
100	<br>
101	</body>
102	</html>	9	</html>

Added Link Here

(-)a/apt/faq.php (+98 lines)
1	<?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop'
2	#
3	# Begin: page-specific settings. Change these.
4	$pageTitle = "JDT-APT FAQ";
5	$pageKeywords = "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
6	$pageAuthor = "JDT/APT team";
7	# End: page-specific settings
8	# Paste your HTML content between the markers!
9	ob_start();
10	?>
11
12	<div id="midcolumn">
13	<h1>
14	<?= $pageTitle ?>
15	</h1>
16	<div class="homeitem3col">
17	<h3>Frequently Asked Questions</h3>
18	<ol>
19	<li>
20	<strong>What are annotations?</strong>
21	<p>
22	Annotations are a simple metadata facility added to the Java
23	language. Annotations can be used anywhere a modifier can be used,
24	like <code>public</code>, <code>static</code>, and <code>final</code>.
25	These annotations can be used at build or run-time in myriad ways.
26	Here's an example annotation:
27	<p>
28	<pre>
29	public class Foo {
30
31	<font color="#FF0000">@Override</font>
32	public int hashCode() {
33	return super.hashCode() ^ 1;
34	}
35	}
36	</pre>
37	<p>
38	This indicates that the method <code>hashCode</code>
39	must override a method with the same signature in its superclass.
40	If the method name were spelled wrong, a processor could notice
41	this and issue an error.
42	</p>
43	<p>
44	Standard uses for annotation processors include EJB and Web Services generators.
45	</p>
46	<p>
47	Additional information on annotations can be found in the Java documentation
48	<a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">here</a>.
49	</p>
50	</li>
51	<li>
52	<strong>When were annotations added to the Java language?</strong>
53	<p>Java 5 added annotation to the core language.</p>
54	</li>
55	<li>
56	<strong>How does jdt-apt extend basic JDT support?</strong>
57	<p>
58	We hook into the JDT compiler. If an annotation is detected, we
59	dispatch to any processors that claim that annotation. We then
60	provide an implementation of the mirror APIs over the JDT
61	typesystem. If a processor creates a new source file, we then call
62	the necessary JDT APIs to perform compilation on that new file.
63	</p>
64	</li>
65	<li>
66	<strong>Can I use an existing processor I wrote for the commandline "apt" tool inside of eclipse?</strong>
67	<p>
68	Yes! This is one of the major goals of the jdt-apt project: you
69	should be able to use an existing processor directly inside of
70	eclipse and get an interactive experience, provided your processor
71	is reasonably quick and efficient.
72	</p>
73	</li>
74	<li>
75	<strong>Are the errors from my processor different from other JDT errors?</strong>
76	<p>
77	No. They're treated just like any other error.
78	</p>
79	</li>
80	<li>
81	<strong>Can I get quick-fixes inside annotation values?</strong>
82	<p>
83	Yes. When you create your error markers via the Messager API,
84	downcast to EclipseMessager, and use the printFixable...() APIs.
85	These error markers can then be processed with a QuickFixProcessor
86	via the JDT APIs in Eclipse.
87	</p>
88	</li>
89	</ol>
90	</div>
91	</div>
92	<?php
93	$html = ob_get_contents();
94	ob_end_clean();
95
96	# Generate the web page
97	$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
98	?>

Lines 1-25 Link Here

(-)a/apt/index.html (-24 / +8 lines)
1		1	<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
2	<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
3	<html>	2	<html>
4	<head>	3	<head>
5	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">	4	<meta http-equiv="refresh" content="0; url=index.php" />
6	<title>Eclipse JDT-APT Project</title>	5	</head>
7	</head>	6	<body>
8	<frameset rows="48,*" frameborder=0 framespacing=0 border="0">	7	<a href="index.php">This page has moved. Please update your links and bookmarks.</a>
9	<frame name="banner" scrolling="no" noresize target="home"	8	</body>
10	src="../../eproject-banner.html" marginwidth="0" marginheight="0" frameborder="NO">	9	</html>
11	<frameset cols="126,*" frameborder=0 framespacing=0 border="0">
12	<frameset rows="220, *" frameborder=0 framespacing=0 border="0">
13	<frame name="home_nav" scrolling="no" noresize target="main"
14	src="../../home_nav.html" marginwidth="0" marginheight="0" frameborder="NO">
15	<frame name="nav" scrolling="no" noresize target="main"
16	src="../../eclipse/nav.html" marginwidth="0" marginheight="0" frameborder="NO">
17	</frameset>
18	<frame name="main" marginwidth=10 marginheight=10 noresize frameborder="NO" src="main.html">
19	</frameset>
20	<noframes>
21	<body>
22	<p>This page uses frames, but your browser doesn't support them.</p>
23	</body>
24	</noframes> </frameset>
25	</html>

Added Link Here

(-)a/apt/index.php (+123 lines)
1	<?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop'
2	#
3	# Begin: page-specific settings. Change these.
4	$pageTitle = "Eclipse JDT-APT Project";
5	$pageKeywords = "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
6	$pageAuthor = "JDT/APT team";
7	# End: page-specific settings
8	# Paste your HTML content between the markers!
9	ob_start();
10	?>
11
12	<div id="midcolumn">
13	<h1>
14	<?= $pageTitle ?>
15	</h1>
16	<div class="homeitem3col">
17	<h3>What is the JDT-APT project?</h3>
18	<p>
19	The JDT-APT project provides plugins that add Java 5 annotation
20	processing support to Eclipse. A Java annotation processor is a
21	compiler plug-in that can gather information about source code as it
22	is being compiled, generate additional Java types or other resource
23	files, and post warnings and errors. Eclipse 3.2 provided support for
24	annotation processors using the <a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
25	and Eclipse 3.3 added support for processors using the <a href="http://java.sun.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
26	Java 6 annotation processing APIs</a>.
27	</p>
28	<p>
29	You can view the presentation given at JavaOne 2005 during a session
30	on APT that describes some of the goals and technical details <a
31	href="javaone_apt.ppt">here</a>. At EclipseCon 2006 we made a <a
32	href="Eclipsecon2006.ppt">presentation</a> on APT do's and don'ts,
33	and at EclipseCon 2007 this was developed into a <a
34	href="eclipsecon2007.zip">tutorial</a> on writing annotation
35	processors for Eclipse, including some sample code and more
36	discussion of techniques to achieve good performance. At EclipseCon
37	2008 we gave a <a href="eclipsecon2008.ppt">presentation</a> on
38	annotations (which briefly mentions annotation processors but does
39	not go into depth) that may be of interest to those looking for
40	background material or for alternative strategies to annotation
41	processing.
42	</p>
43	<p>
44	Additional frequently asked questions and their answers can be found
45	in our <a href="faq.php">FAQ</a>.
46	</p>
47	</div>
48	<div class="homeitem3col">
49	<h3>What is APT?</h3>
50	<p>
51	APT stands for Annotation Processing Tool. Sun shipped an API for APT
52	in JDK 1.5, which can be viewed at <a
53	href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html">
54	http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html</a>.
55	Sun also included a commandline implementation of APT in JDK 1.5. You
56	can find documentation for it at <a
57	href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html"
58	target="_blank">http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html</a>.
59	In JDK 6, the API was modified considerably and standardized through
60	JSR-269, and the Sun implementation was built into the javac compiler
61	rather than requiring a standalone tool.
62	</p>
63	<p>To quote from Sun's documentation:</p>
64	<p>
65	<code>
66	apt is a command-line utility for annotation processing. It includes
67	a set of reflective APIs and supporting infrastructure to process
68	program annotations (JSR 175). These reflective APIs provide a
69	build-time, source-based, read-only view of program structure. They
70	are designed to cleanly model the Java<sup><small>TM</small>
71	</sup> programming language's type system after the addition of
72	generics (JSR 14).
73	</code>
74	</p>
75	<p>
76	So, APT provides a means for generating files and compiling new
77	java classes based on annotations found in your source code.
78	</p>
79	<p>
80	JDT-APT is not based on Sun's implementation, but rather is a
81	separate implementation of the APT APIs that runs entirely within
82	Eclipse.
83	</p>
84	</div>
85	<div class="homeitem3col">
86	<h3>How do I get started?</h3>
87	<p>
88	If all you need to do is use an annotation processor, you may not
89	need to do anything at all! Many project creation wizards will
90	automatically install and enable the necessary processors. To check
91	whether this is the case, or to install and enable your own
92	processors, use the Java Compiler -> Annotation Processing pane of
93	the project properties.</p>
94	<p>
95	If you need to write your own annotation processor, see <a
96	href="introToAPT.php">Intro to APT</a> to get started using APT,
97	and also see the EclipseCon 2007 tutorial mentioned above.
98	</p>
99	</div>
100	<div class="homeitem3col">
101	<h3>How can I contribute?</h3>
102	<p>
103	If you're interested in contributing, start by checking the code out of CVS.
104	See the instructions <a href="howtobuildme.txt">here</a>.
105	</p>
106	<p>
107	You can also check out the mailing list,
108	<a href="http://dev.eclipse.org/mailman/listinfo/jdt-apt-dev">jdt-apt-dev@eclipse.org</a>,
109	or post questions to the eclipse.tools.jdt
110	<a href="http://www.eclipse.org/newsgroups/">newsgroup</a>.
111	The mailing list is primarily for announcements and discussion by people working
112	on the APT tooling in Eclipse; if you have technical questions, it is
113	best to use the newsgroup.
114	</p>
115	</div>
116	</div>
117	<?php
118	$html = ob_get_contents();
119	ob_end_clean();
120
121	# Generate the web page
122	$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
123	?>

Lines 1-162 Link Here

(-)a/apt/introToAPT.html (-161 / +8 lines)
1	<!doctype html public "-//w3c//dtd html 4.0 transitional//en">	1	<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
2	<html>	2	<html>
3	<head>	3	<head>
4	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">	4	<meta http-equiv="refresh" content="0; url=introToAPT.php" />
5	<meta name="GENERATOR" content="Mozilla/4.73 [en] (Windows NT 5.0; U) [Netscape]">	5	</head>
6	<title>Introduction to Annotation Processing in Eclipse</title>	6	<body>
7	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">	7	<a href="introToAPT.php">This page has moved. Please update your links and bookmarks.</a>
8	</head>	8	</body>
9	<body text="#000000" bgcolor="#FFFFFF">	9	</html>
10
11
12	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
13	<tr>
14	<td align=left width="72%"> <font class=indextop> Introduction to the Annotation Processing Feature </font> <br>
15	<font class=indexsub> annotation processing in eclipse </font></td>
16	<td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
17	</tr>
18	</table>
19
20
21	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
22
23	<tr>
24	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Disclaimer</font></font></b></td>
25	</tr>
26	<tr>
27	<td COLSPAN="2">
28	This is a BETA release. All APIs contained herein are provisional, and subject to change with subsequent updates.
29
30
31	<tr>
32	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Testing your APT installation</font></font></b></td>
33	</tr>
34
35	<tr>
36	<td COLSPAN="2">
37	The APT feature is part of Eclipse 3.2, as of M5a and later.
38
39	If you wish to use Eclipse 3.1, see the <a href="installOn3.1.html">3.1 installation instructions</a>.
40	<p>
41
42	You can verify the installation on either version this way:
43	<ul>
44	<li>Create a Java project which contains the file <a href="APTDemo.jar">APTDemo.jar</a> in its filesystem.</li>
45	<li>Open the project properties dialog, and go to the Java Compiler / Annotation Processing panel.</li>
46	<li>Check "Enable Project Specific Settings" and "Enable Annotation Processing".</li>
47	<li>Now open the Java Compiler / Annotation Processing / Factory Path panel.</li>
48	<li>Click on Add Jars... and add the APTDemo.jar.</li>
49	<li>Create a new Class, and annotate the class in the source file with @DemoAnnotation(what = "spam").</li>
50	</ul>
51
52	The "spam" value should be squiggled, with the message "I don't like spam".
53
54	<ul>
55	<li>Annotate the same class with @TypeGeneratingAnnotation</li>
56	<li>Build the project.</li>
57	</ul>
58
59	A new source directory should appear in the project, named .apt_generated, that will contain a generated
60	Java source file called GeneratedFileTest.java. <i>The generated source directory will not be visible by
61	default in the Package Explorer, because it starts with a '.', but it will be visible in the Navigator.</i>
62
63
64
65	</td>
66	</tr>
67
68	<tr>
69	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Installing and Configuring
70	Annotation Processors</font></font></b></td>
71	</tr>
72	<tr>
73	<td COLSPAN="2"><font color="#000000">
74	An annotation processor can run in Eclipse from a .jar file contained in a project, a .jar file external to the workspace, or a plugin.
75	Jars are added to a workspace or project though the Properties Dialog, Factory Path pane:
76	<p>
77
78	<img src="PropertiesDialog.gif">
79
80	<p>
81	For an example of how to set up a plugin project to develop a processor, download <a href="APTDemo.jar">APTDemo.jar</a> and explode it into a workspace and import it as an existing
82	project. Eclipse locates plugins along a factory path, which can be configured at the workspace or project level. Workspace configuration
83	is picked up as the default for projects that have annotation processing enabled (see the Properties dialog shown above). If the factory
84	path is configured for an individual project, that project will no longer see changes to the workspace configuration; you will have to
85	update it manually.
86
87	<p>
88	A plugin that contains a factory must extend the annotationProcessorFactory extension point. Here is the example from the plugin
89	in APTDemo.jar. Each Factory class contained in the plugin must be named in the class=attribute.
90	<pre>
91	<extension
92	point="org.eclipse.jdt.apt.core.annotationProcessorFactory">
93	<factories enableDefault="true">
94	<factory
95	class="demo.TypeGeneratingAnnotationProcessorFactory">
96	</factory>
97	<factory
98	class="demo.DemoAnnotationProcessorFactory">
99	</factory>
100	</factories>
101	</extension>
102	</pre>
103	More details about this will follow when we deliver an SDK version of the feature.
104
105
106	<tr>
107	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Debugging Annotation Processors in
108	Eclipse</font></font></b></td>
109	</tr>
110	<tr>
111	<td COLSPAN="2"><font color="#000000">
112	To debug an annotation processor it must be run from a plugin. You develop your code in the plugin, and then debug it by
113	annotating source code in a spawned instance of
114	Eclipse. The debugging instance needs the annotation declaration, the factory, and the processor. The spawned instance
115	only needs access to the declaration.
116
117
118	</font></td>
119	</tr>
120
121	<tr>
122	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
123	Problems and Bugs</font></font></b></td>
124	</tr>
125	<tr>
126	<td COLSPAN="2"><font color="#000000">
127	Symptom: nothing happens, no errors in log file.
128	<ul>
129	<li>Make sure that annotation processing is enabled in the Project Properties.</li>
130	</ul>
131	<p>
132	Symptom: annotations not getting processed, log file contains "Bundle not resolved" warnings, ClassNotFound errors or "No Classloader found" errors.
133	<ul>
134	<li>Make sure that you are using a 1.5 JVM to run Eclipse. Although most of Eclipse can run on a 1.4 JVM, the APT plugins require a 1.5 JVM.</li>
135	</ul>
136
137	<p>
138	Please post questions to the JDT newsgroup (eclipse.tools.jdt). Post bugs related to this feature in Bugzilla, under Product JDT, Component APT.
139
140	<tr>
141	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">Feature Enable/Disable in Eclipse 3.1.2</font></font></b></td>
142	</tr>
143	<tr>
144	<td COLSPAN="2"><font color="#000000">
145	If you installed APT as an update to Eclipse 3.1.2 and you have a problem with the compiler, you can disable the feature through the Product Configuration dialog
146	(Menu item Help / Software Updates / Manage&nbspConfiguration).
147	<p>
148	<img src="ProductConfigDialog.jpg">
149
150	<p>
151	Select the JdtAptFeature from your Eclipse installation and click <b>Disable</b>.
152	Your Eclipse will now use the unchanged, original version of the compiler. To re-enable the feature you need to click on the Show Disabled
153	Features on the toolbar of this dialog.
154
155
156	</td>
157	</tr>
158	</table>
159
160	<br>
161	</body>
162	</html>

Added Link Here

(-)a/apt/introToAPT.php (+138 lines)
1	<?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop'
2	#
3	# Begin: page-specific settings. Change these.
4	$pageTitle = "Introduction to Annotation Processing in Eclipse";
5	$pageKeywords = "JDT, Java, UI, Debug, APT, java, development, tools, java ide, Eclipse";
6	$pageAuthor = "JDT/APT team";
7	# End: page-specific settings
8	# Paste your HTML content between the markers!
9	ob_start();
10	?>
11
12	<div id="midcolumn">
13	<h1>
14	<?= $pageTitle ?>
15	</h1>
16	<div class="homeitem3col">
17	<h3>Disclaimer</h3>
18	<p>
19	This is a BETA release. All APIs contained herein are provisional, and subject to change with subsequent updates.
20	</p>
21	</div>
22	<div class="homeitem3col">
23	<h3>Testing your APT installation</h3>
24	<p>
25	The APT feature is part of Eclipse 3.2, as of M5a and later. If you wish to use Eclipse 3.1,
26	see the <a href="installOn3.1.html">3.1 installation instructions</a>.
27	</p>
28	<p>You can verify the installation on either version this way:</p>
29	<ul>
30	<li>Create a Java project which contains the file <a href="APTDemo.jar">APTDemo.jar</a> in its filesystem.</li>
31	<li>Open the project properties dialog, and go to the Java Compiler / Annotation Processing panel.</li>
32	<li>Check "Enable Project Specific Settings" and "Enable Annotation Processing".</li>
33	<li>Now open the Java Compiler / Annotation Processing / Factory Path panel.</li>
34	<li>Click on Add Jars... and add the APTDemo.jar.</li>
35	<li>Create a new Class, and annotate the class in the source file with @DemoAnnotation(what = "spam").</li>
36	</ul>
37	<p>The "spam" value should be squiggled, with the message "I don't like spam".</p>
38	<ul>
39	<li>Annotate the same class with @TypeGeneratingAnnotation</li>
40	<li>Build the project.</li>
41	</ul>
42	<p>
43	A new source directory should appear in the project, named .apt_generated, that will contain a
44	generated Java source file called GeneratedFileTest.java. <i>The generated source directory
45	will not be visible by default in the Package Explorer, because it starts with a '.', but it
46	will be visible in the Navigator.</i>
47	</p>
48	</div>
49	<div class="homeitem3col">
50	<h3>Installing and Configuring Annotation Processors</h3>
51	<p>
52	An annotation processor can run in Eclipse from a .jar file contained in a project, a .jar file
53	external to the workspace, or a plugin. Jars are added to a workspace or project though
54	the Properties Dialog, Factory Path pane:
55	</p>
56	<img src="PropertiesDialog.gif">
57	<p>
58	For an example of how to set up a plugin project to develop a processor, download
59	<a href="APTDemo.jar">APTDemo.jar</a> and explode it into a workspace and import it as an
60	existing project. Eclipse locates plugins along a factory path, which can be configured at the
61	workspace or project level. Workspace configuration is picked up as the default for projects
62	that have annotation processing enabled (see the Properties dialog shown above). If the
63	factory path is configured for an individual project, that project will no longer see changes
64	to the workspace configuration; you will have to update it manually.
65	</p>
66	<p>
67	A plugin that contains a factory must extend the annotationProcessorFactory extension
68	point. Here is the example from the plugin in APTDemo.jar. Each Factory class contained in the
69	plugin must be named in the class=attribute.
70	</p>
71	<pre>
72	<extension
73	point="org.eclipse.jdt.apt.core.annotationProcessorFactory">
74	<factories enableDefault="true">
75	<factory
76	class="demo.TypeGeneratingAnnotationProcessorFactory">
77	</factory>
78	<factory
79	class="demo.DemoAnnotationProcessorFactory">
80	</factory>
81	</factories>
82	</extension>
83	</pre>
84	<p>
85	More details about this will follow when we deliver an SDK version of the feature.
86	</p>
87	</div>
88	<div class="homeitem3col">
89	<h3>Debugging Annotation Processors in Eclipse</h3>
90	<p>
91	To debug an annotation processor it must be
92	run from a plugin. You develop your code in the plugin, and then debug it by annotating
93	source code in a spawned instance of Eclipse. The debugging instance needs the annotation
94	declaration, the factory, and the processor. The spawned instance only needs access to the
95	declaration.
96	</p>
97	</div>
98	<div class="homeitem3col">
99	<h3>Problems and Bugs</h3>
100	<div>
101	<p>Symptom: nothing happens, no errors in log file.</p>
102	<ul>
103	<li>Make sure that annotation processing is enabled in the Project Properties.</li>
104	</ul>
105	<p>Symptom: annotations not getting processed, log file contains "Bundle not resolved"
106	warnings, ClassNotFound errors or "No Classloader found" errors.</p>
107	<ul>
108	<li>Make sure that you are using a 1.5 JVM to run Eclipse. Although most of Eclipse
109	can run on a 1.4 JVM, the APT plugins require a 1.5 JVM.</li>
110	</ul>
111	<p>Please post questions to the JDT newsgroup (eclipse.tools.jdt). Post bugs related to
112	this feature in Bugzilla, under Product JDT, Component APT.
113	</p>
114	</div>
115	</div>
116	<div class="homeitem3col">
117	<h3>Feature Enable/Disable in Eclipse 3.1.2</h3>
118	<p>
119	If you installed APT as an update to
120	Eclipse 3.1.2 and you have a problem with the compiler, you can disable the feature
121	through the Product Configuration dialog (Menu item Help / Software Updates /
122	Manage Configuration).
123	</p>
124	<img src="ProductConfigDialog.jpg">
125	<p>
126	Select the JdtAptFeature from your Eclipse installation and click <b>Disable</b>. Your
127	Eclipse will now use the unchanged, original version of the compiler. To re-enable the
128	feature you need to click on the Show Disabled Features on the toolbar of this dialog.
129	</p>
130	</div>
131	</div>
132	<?php
133	$html = ob_get_contents();
134	ob_end_clean();
135
136	# Generate the web page
137	$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
138	?>

Lines 1-133 Link Here

(-)a/apt/main.html (-132 / +9 lines)
1	<!doctype html public "-//w3c//dtd html 4.0 transitional//en">	1	<!DOCTYPE html public "-//w3c//dtd html 4.0 transitional//en">
2	<html>	2	<html>
3	<head>	3	<head>
4	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">	4	<meta http-equiv="refresh" content="0; url=index.php" />
5	<meta name="GENERATOR" content="Mozilla/4.73 [en] (Windows NT 5.0; U) [Netscape]">	5	</head>
6	<title>JDT-APT Project</title>	6	<body>
7	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">	7	<a href="index.php">This page has moved. Please update your links
8	</head>	8	and bookmarks.</a>
9	<body text="#000000" bgcolor="#FFFFFF">	9	</body>
10		10	</html>
11
12	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
13	<tr>
14	<td align=left width="72%"> <font class=indextop> jdt-apt </font> <br>
15	<font class=indexsub> annotation processing in eclipse </font></td>
16	<td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" height=86 width=120></td>
17	</tr>
18	</table>
19
20
21	<table border=0 cellspacing=5 cellpadding=2 width="100%" >
22	<tr>
23	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">What is the JDT-APT project?</font></font></b></td>
24	</tr>
25
26	<tr>
27	<td COLSPAN="2">The JDT-APT project provides plugins that add Java 5 annotation processing support to Eclipse.
28
29	A Java annotation processor is a compiler plug-in that can gather information about source code as
30	it is being compiled, generate additional Java types or other resource files, and post warnings
31	and errors. Eclipse 3.2 provided support for annotation processors using the
32	<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/overview-summary.html">Java 5 Mirror APIs</a>,
33	and Eclipse 3.3 added support for processors using the
34	<a href="http://java.sun.com/javase/6/docs/api/javax/annotation/processing/package-summary.html">
35	Java 6 annotation processing APIs</a>.</p>
36	<p>
37	You can view the presentation given at JavaOne 2005 during a session on APT that describes some of the goals
38	and technical details <a href="javaone_apt.ppt">here</a>. At EclipseCon 2006 we made a
39	<a href="Eclipsecon2006.ppt">presentation</a> on APT do's and don'ts, and at EclipseCon 2007 this was
40	developed into a <a href="eclipsecon2007.zip">tutorial</a> on writing annotation processors for Eclipse,
41	including some sample code and more discussion of techniques to achieve good performance. At EclipseCon 2008
42	we gave a <a href="eclipsecon2008.ppt">presentation</a> on annotations (which briefly mentions annotation
43	processors but does not go into depth) that may be of interest to those looking for background material
44	or for alternative strategies to annotation processing.
45
46	<p>
47	Additional frequently asked questions and their answers can be found in our <a href="faq.html">FAQ</a>.
48
49	</td>
50	</tr>
51
52	<tr>
53	<td COLSPAN="2" ALIGN=LEFT VALIGN=TOP BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
54	What is APT?</font></font></b></td>
55	</tr>
56	<tr>
57	<td COLSPAN="2"><font color="#000000">APT stands for Annotation Processing Tool.
58	Sun shipped an API for APT in JDK 1.5, which can be viewed at
59	<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html">
60	http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/index.html</a>. Sun also included a commandline
61	implementation of APT in JDK 1.5. You can find documentation for it at
62	<a href="http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html" target="_blank">http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html</a>.
63	In JDK 6, the API was modified considerably and standardized through JSR-269, and the Sun implementation was
64	built into the javac compiler rather than requiring a standalone tool.
65	<p>
66	To quote from Sun's documentation:
67	<p>
68	<code>
69	apt is a command-line utility for annotation processing.
70	It includes a set of reflective APIs and supporting infrastructure to
71	process program annotations (JSR 175).
72	These reflective APIs provide a build-time, source-based,
73	read-only view of program structure. They are designed to cleanly model
74	the Java<sup><small>TM</small></sup>
75	programming language's type system after the addition of generics (JSR 14).
76	</code>
77
78	<p>
79	So, APT provides a means for generating files and compiling new java classes based on annotations
80	found in your source code.
81
82	<p>
83	JDT-APT is not based on Sun's implementation, but rather is a separate implementation of
84	the APT APIs that runs entirely within Eclipse.
85
86	</font></td>
87	</tr>
88
89
90
91
92	<tr><td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
93	How do I get started?</font></font></b>
94	</td></tr>
95
96	<tr>
97	<td COLSPAN="2"><font color="#000000">
98	<p>
99	If all you need to do is use an annotation processor, you may not need to do anything at all! Many project
100	creation wizards will automatically install and enable the necessary processors. To check whether this
101	is the case, or to install and enable your own processors, use the Java Compiler -> Annotation Processing
102	pane of the project properties.
103	<p>
104	If you need to write your own annotation processor, see <a href="introToAPT.html">Intro to APT</a> to get
105	started using APT, and also see the EclipseCon 2007 tutorial mentioned above.
106	</font></td>
107	</tr>
108
109
110	<tr>
111	<td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
112	How can I contribute?</font></font></b></td>
113	</tr>
114
115	<tr>
116	<td COLSPAN="2">If you're interested in contributing, start by checking the code out of CVS. See the instructions
117	<a href="howtobuildme.txt">here</a>.
118
119	<p>
120	You can also check out the mailing list,
121	<a href="http://dev.eclipse.org/mailman/listinfo/jdt-apt-dev">jdt-apt-dev@eclipse.org</a>,
122	or post questions to the eclipse.tools.jdt <a href="http://www.eclipse.org/newsgroups/">newsgroup</a>.
123	The mailing list is primarily for announcements and discussion by people working on the APT tooling
124	in Eclipse; if you have technical questions, it is best to use the newsgroup.
125
126
127	</td>
128	</tr>
129	</table>
130
131	<br>
132	</body>
133	</html>