Writing a Plugin

This document describes how to write a plugin for XDoclet2. XDoclet2 provides several mini-frameworks for plugins. These are:

  • Velocity
  • Jelly
  • Betwixt / XGG

Deciding what framework to use

What plugin framework to use depends on what kind of file(s) the plugin will generate.

  • Velocity - Your plugin should extend from xdoclet.plugins.VelocityPlugin if you want to generate non XML files. This is typically java files, properties files, but should be used for any file that isn't some sort of XML.
  • Jelly - Your plugin should extend from xdoclet.plugins.JellyPlugin if you want to generate XML files and you __don't__ have a grammar (DTD or XSD) for it.
  • Betwixt / XGG - Your plugin should extend from xdoclet.plugins.BetwixtPlugin if you want to generate XML files and you __do__ have a grammar (DTD or XSD) for it.

Velocity and Jelly

When you write a plugin based on Velocity or Jelly you must write two files: A plugin class and a template file. The template file is a Velocity or Jelly script. These scripts will have access to various context variables.

What context variables are available to the template depends on the generation mode of the associated plugin.

Available if fileName has {0} in it (generate one file per metadata object - typically per java source file). Keep in mind that in this case the template will be rendered once for each object in the metadata collection.

Context variable Java type Description
${object} This varies. This variable contains the current metadata object. If XJavaDoc

is used as MetadataProvider, the type will be xjavadoc.XClass.
${class} xjavadoc.XClass Synonym for ${object}. Only available if XJavaDoc is used as

MetadataProvider.
${destinationFileName} java.lang.String File name of the file to be generated.
${destinationPackageName} java.lang.String Package name of the file to be generated.
${destinationUnqualifiedClassName} java.lang.String The unqualified class name of the file to be generated.
${destinationQualifiedClassName} java.lang.String The qualified class name of the file to be generated.

Available if fileName doesn't have {0} in it (generate one file for all metadata objects):

Context variable Java type Description
${collection} java.util.Collection Collection of metadata. The type of objects in this collection

depends on what xdoclet.MetadataProvider is being used.

When XJavaDoc is used as MetadataProvider, the objects in this

collection will be xjavadoc.XClass.
${classes} Description Synonym for ${collection}. Makes xjavadoc templates more

intuitive.

Always available:

Context variable Java type Description
${XDOCLET_VERSION} java.lang.String The name and version of XDoclet. Include this in the header of

the generated file. Typical value: "XDoclet 2.0-alpha-SNAPSHOT"
${plugin} xdoclet.Plugin The associated plugin object. This is *your* plugin. The

template can access the plugin object to obtain additional

information (information that isn't available in the metadata).

This is typically extra information passed to the plugin,

typically via Ant or the XDoclet GUI's configuration panels.

Betwixt

When you write a plugin based on Betwixt, you typically only write one file: A plugin class that extends from xdoclet.plugins.BetwixtPlugin. (There is no template file!) You should use XDoclet SDK's xgg plugin to generate Java Beans. The XGG plugin accepts one or more DTD and/or XSD files describing the structure of the XML your plugin will generate. The XGG plugin generates one Java Bean per XML element type, and your plugin class should populate these beans with data. Look at the hibernate plugin's source for an example about how this is done.