XDoclet: Attribute-Oriented Programming - Maven XDoclet Plug-in
Author: Ara Abrahamian

##### XDoclet

- Overview
- News and Status
- Download/Installation
- Using XDoclet
- Best Practices
- FAQ
- License

##### Ant Task Reference

- <doclet .. />
- <ejbdoclet .. />
- <hibernatedoclet .. />
- <jdodoclet .. />
- <jmxdoclet .. />
- <mockdoclet .. />
- <portletdoclet .. />
- <springdoclet .. />
- <tapestrydoclet .. />
- <webdoclet .. />
- <wseedoclet .. />

##### Tag Reference

- apache (@soap @struts @axis @tapestry)
- bea (@weblogic)
- borland (@bes)
- caucho (@resin)
- ejb (@ejb @dao)
- exolab (@castor)
- hp (@hpas)
- hibernate (@hibernate)
- ibm (@websphere)
- java (@javabean)
- jboss (@jboss)
- jdo (@jdo)
- jmx (@jmx)
- jsf (@jsf)
- macromedia (@jrun)
- mockobjects (@mock)
- mvcsoft (@mvcsoft)
- mx4j (@mx4j)
- objectweb (@jonas)
- oracle (@oc4j)
- orion (@orion)
- portlet (@portlet)
- pramati (@pramati)
- spring (@spring)
- sun (@sunone)
- sybase (@easerver)
- tjdo (@tjdo)
- web (@web @jsp)
- webwork (@webwork)
- wsee (@wsee)
- xdoclet (@xdoclet @doc @msg)

##### Feature Documentation

- Using Value Objects
- EJB Environment Handling

##### Advanced

- Maven Plug-in
- Merge Points
- IDE Integration
- Migration from EJBDoclet
- Ant 1.5 Troubleshooting

##### Community

- Feedback
- Resources
- Tools

##### Development

- Developer Guide
- Javadoc (API)
- Template Language (*.xdt)
- XJavaDoc Site

##### Search XDoclet

##### Project Documentation

- About XDoclet
- Project Info
- Project Reports
- Development Process

## Maven XDoclet Plug-in

Maven is an increasingly popular build tool, and XDoclet maintains its own Maven plug-in. This plug-in is located in the same folder as the other xdoclet jar files, and is named maven-xdoclet-plugin-&lt;version&gt;.jar. Just drop it in your $MAVEN_HOME/plugins directory and you're ready to go. You might have to delete your $MAVEN_HOME/cache/*.* files and previous un-zipped XDoclet plug-ins in $MAVEN_HOME/plugins to be able to get it to work properly.

The Maven XDoclet plug-in supports all standard tasks and subtasks of XDoclet.

### How-to

1. XDoclet has a lot of modules. Some of the most common modules have already been added to the plugin's classpath for you. However, other, less used ones, have not. So in order to keep the load time optimized to individual installations, you have to declare any missing XDoclet-module jar files in your project.xml. For example, the xdoclet-ejb-module is included. However, for use with jboss, you would need to include the xdoclet-jboss-module. So if you want to use ejbdoclet with jboss, you should do:

    <dependencies>
        <dependency>
            <groupId>xdoclet</groupId>
            <artifactId>xdoclet-jboss-module</artifactId>
            <version>1.2</version>
        </dependency>

        <dependency>
            <groupId>jboss</groupId>
            <artifactId>jboss-j2ee</artifactId>
            <version>3.2.1</version>
        </dependency>
    </dependencies>

2. If you want XDoclet to run automatically before the compile step you should define a maven.xml file like this:

    <project>

        <preGoal name="java:compile">
            <attainGoal name="xdoclet:ejbdoclet"/>
        </preGoal>

    </project>

3. Now how does XDoclet know you want to run remoteinterface subtask or what is the remote interface class pattern? Well, you need to define some properties, but some properties have defaults. These defaults are important to understand, please go to the plugin.properties file and review them now. For example, by default ejbdoclet has these defaults defined in its plugin.properties file:

    #ejbdoclet default properties
    maven.xdoclet.ejbdoclet.destDir=${maven.build.dir}/xdoclet/ejbdoclet

    maven.xdoclet.ejbdoclet.fileset.0=true
    maven.xdoclet.ejbdoclet.fileset.0.include=**/*Bean.java

    maven.xdoclet.ejbdoclet.deploymentdescriptor.0=true
    maven.xdoclet.ejbdoclet.deploymentdescriptor.0.destDir=${maven.build.dir}/xdoclet/ejb/META-INF

    maven.xdoclet.ejbdoclet.entitybmp.0=true
    maven.xdoclet.ejbdoclet.entitycmp.0=true
    maven.xdoclet.ejbdoclet.entitypk.0=true
    maven.xdoclet.ejbdoclet.homeinterface.0=true
    maven.xdoclet.ejbdoclet.localhomeinterface.0=true
    maven.xdoclet.ejbdoclet.localinterface.0=true
    maven.xdoclet.ejbdoclet.remoteinterface.0=true
    maven.xdoclet.ejbdoclet.session.0=true
    maven.xdoclet.ejbdoclet.utilobject.0=true

So by default the destDir is target/xdoclet/ejbdoclet and all classes ending with "Bean" are processed. The entitybmp, entitycmp, etc subtasks are run, for instance because the 'maven.xdoclet.ejbdoclet.entitybmp.0' is set to 'true'. Basically for any task or subtask parameter you find in XDoclet documentation there's a counterpart in the maven plug-in too. But sometimes the capitalization is different than you might expect. (Don't spend too much time trying to experiment with capitalization though, instead open up the plugin.jelly file and review it there.) The destDir parameter of ejbdoclet is named maven.xdoclet.ejbdoclet.destDir for example. Any nested element with many cardinality (you can nest many of them inside ejbdoclet for example) and all subtasks are indexed. So you reference entitypk subtask of ejbdoclet with maven.xdoclet.ejbdoclet.entitypk.0 and if you want to specify the pattern attribute of it you define it like this: maven.xdoclet.ejbdoclet.entitypk.0.pattern={0}PK. As you review the plugin.jelly file, you will see why there is an index, the jelly file is actually a script, and it is using the indexes for iterating over the number of items that you have for your specific build.

4. If you use Eclipse and the Maven Eclipse plugin, you'll notice that you have to manually add any generated source files to the classpath of your Project. Alternatively, you can specify a 'maven.gen.src' directory to be the root of your generated source files. Any folders under that will be imported into Eclipse as source folders on the classpath. Just add this to your project.properties:

    maven.gen.src=${maven.build.dir}/xdoclet