Peter Martin: April 2006 Archives

Main | May 2006 »

April 28, 2006

XDoclet2 + AS3 + Ant + Cairngorm - Update I

I thought I would follow-up on my last blog entry on XDoclet2. In the last week I have been going head-to-head with XDoclet2 in the hope it will save our team coding Java VOs and AS3 VOs. As the team started using more complex object types in Java it soon became apparent that the generated AS3 VOs weren't going to work. This came as a bit of blow to us so we had to decide whether to drop XDoclet2 and hand-code both sets of VOs, fix XDoclet2 or look for a "home grown" alternative.

The problems we encountered were as follows:

A number of the Java to AS3 types mappings were wrong, namely java.util.Collection mx.collection to ArrayCollection. It appears the AS3 codegen is still using the type mappings from Flex 1.5.
The AS3 class contained Java import statements - so it wouldn't compile.
Java public static final constants were crashing XDoclet2.

We decided to push forward and see if we could fix XDoclet2. I have logged these bugs with XDoclet but you can also download my patched plugin JAR here. It should now implement all the Java to AS3 types mappings as defined in the Developing Flex Applications manual. The latest code in the XDoclet2 repository doesn't appear to have the same issue with imports, although this version will filter out duplicates.

If you want to codegen the Java public static final constants you need to include the Java class files in your XDoclet2 classpath, which is part of the Ant build script, as it uses Java reflection to obtain the value of the constant.

We added our Ant build script as a builder on the project, by default this runs in the same Java VM as Eclipse but it caused memory issues (XDoclet2 appears to be memory intensive) that ultimately crash Eclipse. As a result we ended up configuring our builder to run in a separate JVM and setting the maximum heap size to 64MB.

My updated Ant build script is below, the location of our Java VO classes is now included in the <path> element:

<project name="XDocletExample" default="main">

	
	<property
		name="xdoclet.plugin.install.dir"
		value="C:/apps/java/xdoclet-plugins-1.0.3"/>
	
	
	<property
		name="xdoclet.output.dir"
		value="${basedir}/as"/>

	
	<path id="xdoclet.task.classpath">
 		
  		<fileset dir="${xdoclet.plugin.install.dir}/lib">
    		<include name="**/*.jar" />
  		</fileset>

		
  		<pathelement
			location="${xdoclet.plugin.install.dir}/plugins/xdoclet-plugin-actionscript-1.0.4-SNAPSHOT.jar"/>
 	
		
		<pathelement location="${basedir}/bin"/>
	</path>

 	
 	<taskdef
    	name="xdoclet"
 		classname="org.xdoclet.ant.XDocletTask"
     	classpathref="xdoclet.task.classpath" />

 	<target name="main">
 		
		<delete>
			<fileset dir="${xdoclet.output.dir}">
 				<include name="**/*.*"/>
 			</fileset>
 		</delete>
 		
  		<xdoclet>       
   			
  			<fileset dir="src">
	            <include name="**/*.java"/>
  		  	</fileset>

   			
   			<component
  				classname="org.xdoclet.plugin.actionscript.ActionScript3Plugin"
   				destdir="${xdoclet.output.dir}" />
  		</xdoclet>
	</target>
  			
</project>

Where does this leave us? I don't like patching open-source libraries, but I saw little choice here. Given time I would like to create an AS3 plugin for XDoclet (v1.x), while XDoclet2 may be architecturally better it seems to lack the support given to XDoclet. XDoclet has better documentation and there are a number of books available. For me though the biggest benefit to XDoclet is the Eclipse tooling support.

Resources

Download modified ActionsScript plugin for XDoclet2.
Download modified source files for ActionScript plugin.
XDoclet2 Home
Doclet2 + AS3 + Ant + Cairngorm

Posted by at 4:48 PM | Comments (3)

April 22, 2006

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

<project name="xdoclet2-example" default="main">

	<property
		name="xdoclet.plugin.install.dir"
		value="C:/apps/java/xdoclet-plugins-1.0.3"/>

	<path id="xdoclet.task.classpath">

 		
  		<fileset dir="${xdoclet.plugin.install.dir}/lib">
    		<include name="**/*.jar" />
  		</fileset>

  		
  		<pathelement
  			location="${xdoclet.plugin.install.dir}/plugins/xdoclet-plugin-actionscript-1.0.3.20060414.jar"/>
	 
 	</path>

 	
 	<taskdef
    	name="xdoclet"
 		classname="org.xdoclet.ant.XDocletTask"
     	classpathref="xdoclet.task.classpath" />

 	<target name="main">
  		<xdoclet>       
   			
  			<fileset dir="src">
	            <include name="**/*.java"/>
  		  	</fileset> 	   

   				
   			<component
  				classname="org.xdoclet.plugin.actionscript.ActionScript3Plugin"
   				destdir="." />
  		</xdoclet>
	</target>
  			
</project>

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

package 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.PersonVO

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

Posted by at 9:28 PM | Comments (3)

April 19, 2006

Welcome!

Hi, I'm Peter Martin and I'm a Technical Architect with Adobe Consulting. In the future I hope to blog on how Flex fits within the Enterprise. In particular I am interested in security, clustering, development tooling and agile development.

My first two blogs will cover AS3 codegen using XDoclet2 and FlexUnit integration with Ant and CruiseControl.

In the longer term I hope to introduce you to an Eclipse feature I developed on the Eclipse Web Tools Platform to provide a Flex project facet for dynamic Web projects. My hope is to blend Flex application development with J2EE-application development and leverage the Eclipse tooling in this area.

Posted by at 8:20 PM | Comments (5)