Using XDoclet

1. XDoclet Subsystems

The XDoclet core subsytem is the central repository for XDoclet information and provides the following feature :

• Modules list : provides a list of the XDoclet modules available for use by the system. The list is used by the execution subsystem for both creation and execution of project XDoclet configurations.

The XDoclet assistance subsystem supports auto-completion of XDoclet javadoc tags and provides the following features:

• Tag completion : enables the insertion of XDoclet javadoc tags into Java files.
• Tag templates : enables the the definition of tag templates to be used during tag completion.

The XDoclet execution subsystem enables XDoclet tasks to be executed within a Java project and provides the following features

• Configurations definition : enables creation/modification/deletion of generated build configurations.
• Configurations launch : allows launching build configurations within a Java project.

2. XDoclet Core – Updating or Augmenting the XDoclet Modules List

You can add to or upgrade the XDoclet modules used within MyEclipse at any time, without installing a new MyEclipse release. XDoclet modules can be manually updated by performing the following steps:

1. Copy the new XDoclet library into the MyEclipse XDoclet core plugin directory located at: <MyEclipseInstall>/eclipse/plugins/org.jboss.ide.eclipse.xdoclet.core_<version>
2. Click the two “refresh” buttons shown below, in the order shown.
   
   
   
   Refreshing the XDoclet core

3. XDoclet Assist – Completion, Templates, and Variables

As you enter XDoclet annotations in the Java editor, XDoclet code completion features are available. MyEclipse extends the Java editor with the addition of this feature as well as the ability to invoke code completion on EJB APIs.

To activate XDoclet tag completion, simply type an @, followed by the XDoclet namespace, followed by a period ‘.’, and then press CTRL+Space. The completions will be displayed as a drop-down box as shown below.

XDoclet Code Assist

Define tag completion templates on one of the XDoclet preference pages, as shown below.

To define a tag template, use the contextual menu by right-clicking the mouse in the template area. Then choose the tags and build the hierarchy to suite your needs.

Once the templates are saved, they can be used in the completion proposal.

Code Assist templates

XDoclet variables are used to compute default values of the completion proposals.

To modify the the variable name generation, use the preference page shown below.

XDoclet variable name preferences

4. XDoclet Run – Configurations and Generation

The Configurations plugin allows you to define the generation configurations to run against a Java project. A generation configuration is a list of Doclets to run, each Doclet is containing subtasks to apply. The definition of a configuration follows the writing of an XML Ant build file.

To access the generation configurations, right-click a Java Project, and select Properties item.

Generation configuration

The XDoclet project properties is divided into three zones :

• The upper zone contains the generation configurations. A checkbox on the left of each configuration indicates whether or not it is used when launching the generation (see generation launching).
• The lower-left zone contains the detail of the selected generation configuration. It is a tree view of what is inside the configuration.
• The lower-right zone contains the attributes related to the selected element in the lower-left zone.

Configuration and every element, attribute has a checkbox. These checkboxes allow you to choose which configuration to use, which element inside a configuration to use and which attribute for an element will be used.

After configuration, an xdoclet-build.xml file is generated and contains the selected configurations.

4.1 Adding a Configuration

To add a new XDoclet configuration, right-click the upper pane of the dialog, and select Add. To add a standard configuration, select Add Standard.

The configuration will be created and then shown in the list of configurations.

Adding a configuration

4.2 Renaming or Removing a Configuration

To rename or remove a configuration, right-click the configuration, and select Rename or Remove.

Configuration options

4.3 Adding a Doclet

Once the configuration has been created, it must be populated.

The first step is to add a Doclet. Right-click the lower-left zone, select Add, and choose a doclet.

Adding a doclet

The Doclet appears in the configuration detail. You can edit and select attributes to use.

4.4 Adding an Element

Once a doclet has been added, elements can be appended as children.

To add an element, right-click the Doclet in the lower-left pane, select Add, and select an element.

Adding an element to a doclet

The new element appears in the configuration detail. You can edit and select attributes to use.

4.5 Editing Attributes

Once a Doclet or an element has been added, you can edit its attribute

Select the Doclet or the element in the lower-left pane. The attributes appear in the lower-right pane.

Double-click an attribute to edit the value.

Editing an attribute

4.6 Running XDoclet

Once configurations have been defined, they can be run in two ways :

• Using Ant : since the configurations are transformed in Ant Build file, Ant can be run use “xdoclet-build.xml” file
• Using Menu : this is almost the same as Ant run, but it is faster since the launch configuration is pre-computed

Right-click a Java project, and select MyEclipse>Run XDoclet.

A progress window appears, and the Ant output is printed in the Console. At the end of the process, the Java project is automatically refreshed.

Results of running the XDoclet