Annotation Processing Tool
The annotation processing tool (apt) found in JAVA_HOME/bin directory is a command-line utility that ships with JDK 5.0. This tool looks for annotation processors based on the annotation in the set of specified source files being examined. Essentially the annotation processor uses a set of reflective APIs and supporting infrastructure to process the annotations.

When invoked, the apt goes through the following sequence of operations: First, it determines what annotations are present in the source code being operated on. Next, it looks for annotation processor factories. It then asks the factories what annotations they process and, if the factory processes an annotation present in source files being operated on, the apt asks the factory to provide an annotation processor. Next, the annotation processors are run. If the processors have generated new source files, the apt will repeat this process until no new source files are generated. This high-level sequence is indicated in Figure 1.

To write a factory class, a developer has to rely on packages that aren't part of the standard SDK. The packages used are:

• com.sun.mirror.apt: interfaces to interact with the tool.
• com.sun.mirror.declaration: interfaces to model the source code declarations of fields, methods, classes, etc.
• com.sun.mirror.type: interfaces to model types found in the source code.
• com.sun.mirror.util: various utilities for processing types and declarations, including visitors.

Using Annotation for Generating Struts-config.xml
For a concrete understanding of the technology it's imperative that we dive into writing code and see for ourselves how it works. We will look at how to go about generating struts-config.xml by annotating code and using the apt tool. This article assumes that the reader is familiar with the Open Source MVC framework struts. We will look at how to generate the configuration details and the declarative programming semantics provided in the struts-config.xml by annotating the source code.

Before we get to the nitty-gritty of annotating and generating configuration files, we need to understand why this needs to be done.

We need to do this because a developer who has to write code using the struts framework finds himself copying and pasting information from the source code to the deployment descriptor and vice versa. For instance, if we change the name of the Action class and don't change the XML file, the application doesn't work correctly. The way to sidestep this issue is to isolate the changes to one location and let the utility tool generate the deployment descriptor. We will cover how to use the metadata facility to achieve this automatic configuration file generation.

Before we start we have to make sure that we have the right development tools to do what we're trying to do. Currently very few IDEs support Java 5. Among Open Source IDEs, NetBeans 4.0 beta 2 looks promising (in spite of a few runtime exceptions) so most of the code in this article was written and tested with it. The first step in the process is defining the annotation types for the various elements that make up the struts framework. The component parts of the framework are: Action, Form bean (also known as Action Forms), Exceptions, Validator, Plug-ins etc.

The annotation type for Struts Action is as follows:

package com.jdj.article.atypes;
import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface StrutsAction {
    String name();
    String path();
    String scope() default "session";
    String input() default "";
    String roles() default "";
    String validate() default "";
    String parameter() default "";
    StrutsActionForward[] forward();
    StrutsActionException strutsAction
     Exception();
}

As you can see, I have the annotation types as return types. This is necessary because we could have forward and exception elements defined by the action element. The XML snippet from that struts-config.xml that we're trying to generate will clarify the need for embedding other annotation types in the action annotation-type declaration.

<action    path="/SubmitLogon"
           type="example.LogonAction"
           name="LogonForm"
           scope="request"
           input="logon">
     <forward name="failure" path="/
      MainMenu.do"/>
     <forward name="success" path="/
      someValidPage.jsp"/>
     <exception key="expired.password"
                type="example.Expired
                 PasswordException"
                path="/ExpiredPassword.
                 do"/>
</action>

The next step is to annotate the code with the annotation type. In our case we will annotate a struts action class. This is done as follows:

package ....
import ....
@StrutsAction(
    name=" example.LogonAction",
    path="/SubmitLogon", 
    forward = {@StrutsActionForward(
        name = "failure",
        path = "/MainMenu.do" )},
    strutsActionException = 
     @StrutsActionException(
	   key = "expired.password",
	   type = "example.ExpiredPassword
     Exception",
	   path = "/ExpiredPassword.do"
    )
)
public class ExampleAction extends Action {

    /** Creates a new instance of ExampleAction */
    public ExampleAction() {
    }

    public ActionForward execute(ActionMapping 
     mapping,
        ActionForm form,
        HttpServletRequest request,
        HttpServletResponse response)
    throws Exception {
        return null;
    }
}

• Figure 1
• Table 1
• Table 2
• Source Code