Using XDoclet in MyEclipse

1. XDoclet Subsystems

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

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

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

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.

XDoclet Preferences

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.

Project Properties
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.

Configuration List Popup
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 List Popup
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.

Configuration Popup

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 attributes.

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.

Attribute Edit
Editing an attribute

4.6 Running XDoclet

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

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

Generation Popup

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.

Generation Dialog

Generation Ouput
Results of running the XDoclet