XDoclet2 + AS3 + Ant + Cairngorm

I recently wanted to generate Cairngorm VOs (a.k.a. DTOs) from Java VOs. I had a quick search on Google and quickly came across XDoclet2. The current version of XDoclet2 is v1.0.3. I have to confess I struggled to get it running due to the sparse documentation. However, my attempts to get it running were in vain as it wouldn’t generate VOs that I could use in Remote Procedure Calls (RPC). This is because v1.0.3 of the XDoclet2 plugins was released before features such as the metadata used by Flex Data Services (FDS) were known. In particular it doesn’t support the RemoteClass metadata.


The AS3 plugin was contributed by Joe Berkovitz and I noted on the Allurent web site that the latest version of the AS3 plugin code in CVS did indeed have the support. The downside was you had to get the latest source and build the plugin yourself, which is time consuming as you need to check-out the code, install Maven, etc. but I thought a worthy topic of my first blog entry due to the time saved by auto-generating AS3 VOs. However, at the time of writing this entry I note that Joe has released a new version of the plugin on his blog, which supports the new FDS metadata. Hmm, so where does that leave my blog entry?All is not lost. I still think it is a worthwhile exercise to work through a practical example of installing the XDoclet2 plugins with Joe’s new AS3 plugin and to consider Cairngorm along the way.

Requirements

  • Download the XDoclet2 plugins (v1.0.3) from Codehaus.
  • Download the new AS3 plugin from Joe Berkoviz’s blog.
  • Download Log4j – XDoclet2 uses Commons Logging and requires a logging implementation.

Software Installation

  • Extract the XDoclet2 plugins distribution.
  • Extract the Log4j distribution.
  • Copy the Log4j (I used v1.12.13) JAR, <your_log4j_directory>\dist\lib\log4j-1.2.13.jar, to <your_xdoclet_directory>\lib.
  • Delete the shipped AS3 plugin, xdoclet-plugin-actionscript-1.0.3.jar, from <your_xdoclet_directory>\plugins.
  • Copy Joe’s AS3 plugin, xdoclet-plugin-actionscript-1.0.3.20060414.jar, to <your_xdoclet_directory>\plugins.

Example

I created a Java Project in my Eclipse workspace (which you can download here and import into your workspace – extract the file into your workspace and in Eclipse select File > Import and follow the Existing Projects into Workspace wizard).To start with I created a Java VO (PersonVO) which I annotated for the AS3 codegen:

package com.adobe.example;/*** Example Java VO with XDOclet2 annotation for AS3 codegen.** @actionscript.class* 		bindable = true*/public class PersonVO{private String forename;private String surname;public String getForename(){return forename;}public void setForename( final String firstName ){forename = firstName;}public String getSurname(){return surname;}public void setSurname( final String lastName ){surname = lastName;}}

I then created the following Ant build script (build.xml) in the root of my project. You will need to change the value of the xdoclet.plugin.install.dir property to the location of your XDoclet2 installation (remember to use forwarded slashes).

To run the Ant build script in your Eclipse workspace right-click on build.xml and select Run As > Ant Build…. Click the Main tab and then click the Browse Workspace button under the Base Directory field and select your project (XDocletExample). When you have finished click the Run button.The console view will show the output of the Ant build script. When it’s finished you will need to right-click the project and select Refresh to see your generated AS3 class, as shown below:

// Generated file. Do not edit.// Generated by org.xdoclet.plugin.actionscript.ActionScript3Plugin from com.adobe.example.PersonVOpackage com.adobe.example{import org.nevis.cairngorm.vo.ValueObject;/** Example Java VO with XDOclet2 annotation for AS3 codegen. */[Bindable][RemoteClass(alias="com.adobe.example.PersonVO")]public class PersonVO implements ValueObject{public var forename:String;public var surname:String;}}

If you don’t use Eclipse, you will need to download and install Ant. If you add the Ant bin directory to your path you can open a command prompt and change directory to your project. To run the Ant build script just type ant at the command prompt.In a real project you could run the Ant build script automatically by adding it as a builder to your project; this would also refresh your project automatically. Let me know if you want to see the detail.

Cairngorm

When we use VOs in a Cairngorm-based application we implement the org.nevis.cairngorm.vo.ValueObject interface. This is not strictly required as it is only a marker interface. However, my preference is to provide the interface on generated VOs. If this is your preference you can download a modified Velocity template that will add the Cairngorm VO interface to your generated AS3 classes.

  • Extract Joe’s AS3 plugin, you can do this using WinZip but you will need to change the extension to .zip.
  • Overwrite the AS3 template (ActionScript3Plugin.vm) in <your_extracted_plugin_directory>\org\xdoclet\plugin\actionscript with the one you downloaded.
  • Zip the plugin back-up and rename the extension to .jar.
  • Copy your modified plugin JAR to <your_xdoclet_director>\plugins and overwrite the existing JAR.

If you run your Ant build script again you should get a Cairngorm VO, as below:

// Generated file. Do not edit.// Generated by org.xdoclet.plugin.actionscript.ActionScript3Plugin from com.adobe.example.PersonVOpackage com.adobe.example{import org.nevis.cairngorm.vo.ValueObject;/** Example Java VO with XDOclet2 annotation for AS3 codegen. */[Bindable][RemoteClass(alias="com.adobe.example.PersonVO")]public class PersonVO implements ValueObject{public var forename:String;public var surname:String;}}

Please also see my recent follow-up blog on XDoclet2 that covers some of the more practical issues I have encountered and a patch to the AS3 plugin.