Peter Martin: Tooling Archives

July 31, 2008

New FlexAntTask - fails build if test suite doesn't execute

The FlexAntTask will now fail the build if there is an error executing the test suite e.g. a socket timeout. In the past the error was swallowed as the server socket runs in a separate thread - any errors are now passed back to the task and re-thrown.

Binary distribution

Source Distribution

Example Project

FlexUnitExample.zip

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by pmartin at 7:07 PM | Comments (14)

September 27, 2007

FlexUnit for Ant now supports Mac OS X

A big thank you to Tom Sugden who has added support for Mac OS X.

For more details on how to use FlexUnit for Ant please see my earlier blog. There is also documentation on the flexunit Ant task parameters at the end of this blog. You can download FlexUnit from Adobe Labs.

Binary distribution

Source Distribution

Example Project

FlexUnitExample.zip

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by pmartin at 10:45 PM | Comments (5)

February 16, 2007

FDS Plugin V2

I am please to say V2 of my FDS Plugin is now available for download on the Flex Exchange. Thanks to all those who took the time to downloaded the BETA and for reporting the bugs you found. In particular the following bugs have been fixed:

The plugin will now run with Java 1.4.
The paths in the project are correct on Mac OS X.
The 'user_classes' folder is now included in the project classpath.
If you compile locally the Web Tools Plaform WAR export will now include the Flex generated files (e.g. *.swf) and the Flex source files if selected.

What's new?

The dependancy on Flex Data Services (FDS) has now been externalized. This means you need to have FDS installed on your machine. You will find a new preferences page in Eclipse (Window > Preferences > Flex Data Services > FDS Installations) where you can configure the installation location of FDS.

FDS Preferences

The new project wizard now has a configuration page, which you can use to configure your FDS project.

Project Config

In particular it adds an option to compile your application locally in Flex Builder, which should help improve your development velocity. In the past it only supported compile on server, which it continues to support. However, I would strongly urge against using this option as I have found it to be troublesome when you are debugging as Flex Builder won't always find the source.

Posted by at 9:48 AM | Comments (12)

January 17, 2007

Continuous Integration with CruiseControl + FlexUnit + XDoclet2

Last year I blogged about XDoclet2 and FlexUnit and Ant . In this entry I am going to look at setting up CruiseControl for continuous integration. I have setup my CruiseControl server on Linux so I will do my best to make sure these instruction also apply to Windows. I also used Perforce as my source control repository so I have included the extra steps that are required to get CruiseControl working with Perforce. CruiseControl supports many other repositories such as Subversion and CVS. Please refer the the CuriseControl configuration reference for more details.

What software do I need?

You will need to download the following software:

Download the CruiseControl binary distribution - I downloaded CruiseControl 2.6.
Download a Java SE Development Kit (JDK) - I downloaded JDK 5.0 Update 10.
Download FlexAntTasks.
Download Flash Player 9 for Windows, Macintosh or Linux.
Download Flex SDK.

If you are using Perforce you will also need the following:

Download the Apache Ant binary distribution Don’t use the embedded copy of Ant that comes with CruiseControl as it doesn’t contain the Perforce tasks - I downloaded Apache Ant 1.7.0.
Download the Jakarta ORO binary distribution. Jakarta ORO is required by the Perforce Ant tasks - I downloaded Jakarta ORO 2.0.8.
Download the Perforce client (p4).

Do I need anything else?

Yes - if you are running this on Linux you will need an X Server installed and you will probably want a virtual frame buffer. These are required by the Flash Player - there is no headless version of the player. If you try and run the Flash Player without these you will probably get the following error:

Can't connect to X11 window server using ':0.0' as the value of the DISPLAY

The virtual frame buffer will allow the Flash Player to run in a virtual window without the need for a display plugged in to your server. I used XFree86, which provides an X Server and a virtual frame buffer (Xvfb).

How do I install the software?

Extract CruiseControl to a suitable location on your local machine.
Install your JDK.
Create a JAVA_HOME environment variable with the path to your JDK installation.
Add $JAVA_HOME/bin (or %JAVA_HOME%\bin on Windows) to your path.
Copy FlexAntTasks.jar to <ANT_HOME>\lib, where <ANT_HOME> is the path to your Ant installation. If you are using the version of Ant that comes with CruiseControl you will find it under your CruiseControl instalaltion. The example config at the end of this blog shows how to configure an alternative Ant installation.
Install Flash Player 9.
Install Flex SDK.

Note: if you are using Linux the FlexUnit Ant task will use the standalone player, please make sure the Flash Player executable (gflashplayer) is on your PATH.

To verify CruiseControl is working start is using cruisecontrol.sh or cruisecontrol.bat (start CruiseControl from its home directory) and connect to the console through your browser using http://<your_server>:8080. You should see a test project called connectfour. Stop CruiseControl after you have connected sucessfully.

If you are using Perforce:

Extract Apache Ant to a suitable location on your local machine.
Extract Jakarta ORO and copy the JAR (e.g. jakarta-oro-2.0.8.jar) to <ANT_HOME>\lib, where <ANT_HOME> is the path to your Ant installation.
Make sure the Perforce client executable (p4) is on your PATH.

You will also need to create a client workspace for Perforce, which is used by CruiseControl. You can do this using the P4V tool or on the command line using p4, for example you can do the following on Linux to create a client workspace:

mkdir ~/cruisecontrol
cd ~/cruisecontrol
p4 -p <port> -c <client_workspace> -u <user> -P <password> client

The final command puts you in the editor, which you can just quit.

How do I run CruiseControl?

If you are running on Linux and using Xvfb execute the following commands:

export DISPLAY=:1.0
/usr/X11R6/bin/Xvfb :1 -screen 0 1280x1024x8 &
cd <CC_HOME>, where <CC_HOME> is the parth to your CruiseControl installation.
cruisecontrol.sh &

If you are on Windows:

Open a command prompt.
cd <CC_HOME>, where <CC_HOME> is the parth to your CruiseControl installation.
cruisecontrol.bat

You can then connect to the console using your browser: http://<your_server>:8080

How do I configure a project?

You must configure your projects in <CC_HOME>\config.xml, where <CC_HOME> is the parth to your CruiseControl installation.

I have provided an example of config.xml , which externalises its configuration parameters to config.properties. This example uses my FlexUnitExample project.

Note: use the latest version of FlexUnit for Ant as it no longer requires you to create a FlashPlayerTrust configuration file.

Posted by at 7:34 PM | Comments (3)

FlexUnit for Ant Update#4

You can download a new release of FlexUnit for Ant. This version fixes a bug with the toDir property and also removes the need to create a configuration file under the FlashPlayerTrust folder to allow the SWF to run in the local trusted sandbox. The Ant task will now send a policy file to the Flash Player to allow the data to be sent over the socket - should make life a little easier.

Binary distribution

Source Distribution

Example Project

FlexUnitExample.zip

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by at 5:11 PM | Comments (3)

January 9, 2007

FDS Plugin 2 (Beta)

A number of people of have been asking me when a new version of my FDS plugin will be released to support Flex 2.0.1, Eclipse 3.2 and the Mac. Now that Flex 2.0.1 is released I am happy to say I have made a beta version of the plugin available. So please install it and let me know what you think. More importantly if you find a bug send me an email, pmartin@adobe.com.

This is a complete re-write and I have done my best to address the issues that I saw in the previous versions. In particular I have removed the dependency on Java 5 and externalized Flex Data Services (you now need to have FDS installed on your your local machine).

Prerequisites

To install the plugin you need the following already installed:

Eclipse 3.2.x
Eclipse Web Tools Platform 1.5.x
Flex Builder 2.0.1

With regards to Eclipse + Eclipse Web Tools Platform I would recommend installing the all-in-one, which can be downloaded from here.

Installation

Download the plugin from here.
Start Eclipse.
Select Help > Software Updates > Find and Install.
Select Search for new features to install.
Click New Archived Site.
Select the plugin ZIP file you downloaded.
Click Finish.
Check the feature.
Complete the wizard.

What's new?

As mentioned above Flex Data Services (FDS) has been externalized. This means you need FDS installed on your local machine. You will find a new preferences page in Eclipse (Window > Preferences > Flex Data Services > FDS Installations) where you can configure the installation location of FDS.

The new project wizard now has a configuration page, which you can use to configure your FDS project.

Other than that it should be business as usual.

Posted by at 10:48 AM

November 11, 2006

FlexUnit for Ant Update#3

You can download a new release of FlexUnit for Ant, which fixes a few bugs people have experienced recently. For more details on how to use FlexUnit for Ant please see my earlier blog. There is also documentation on the flexunit Ant task parameters at the end of this blog. You can download FlexUnit from Adobe Labs.

Binary distribution

Source Distribution

Example Project

FlexUnitExample.zip

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by at 10:04 PM | Comments (1)

August 7, 2006

FDS Plugin for Eclipse Web Tools Platform

I have developed a plugin for the Eclipse Web Tools Platforms (WTP). The plugin provides a project facet, which is used to add Flex Data Services (FDS) functionality to a dynamic web project.

What is the Eclipse Web Tools Platform?

The Eclipse Web Tools Platform is an open source project that provides an “extensible development platform and application frameworks for building software”. The Eclipse WTP is a top-level project that “extends the Eclipse platform with tools for developing J2EE web applications”. The WTP project contains two subprojects:

Web Standards Tools (WST) - the WST subproject aims to “provide common infrastructure to any Eclipse-based development environment targeting Web-enabled applications”.
J2EE Standard Tools (JST) - the JST subproject aims to “provide a basic Eclipse plug-in for developing applications based on J2EE 1.4 targeting J2EE-compliant application servers, as well as a generic J2EE tooling infrastructure for other Eclipse-based development products.”.

Why the Eclipse Web Tools Platform?

To-date within Adobe Consulting EMEA we have delivered all our Flex 2 FDS projects on the Eclipse WTP for the following reasons:

Java Support - Flex Builder doesn't add the Java nature to an FDS project therefore you have no support for Java development within the web module.
Version Control - Flex Builder creates an FDS project in-place on an external application server, as a result the web module assets are not part of the project under Eclipse and hence not subject to version control, especially if you are using the Eclipse team support. I believe you should always version control your web module e.g. all the files within flex.war. Within an enterprise it is highly likely that you will be running multiple FDS projects on different versions of Flex. When a developer or a deployer checks out a project they should receive the complete application. In addition, if you label or branch the codebase you should tag all files related to that version e.g. source files, library files, configuration files, deployment descriptors, API-implementations otherwise it becomes difficult to re-constitute the application at that version.
J2EE Support - if you are developing an enterprise application it is unlikely to contain just Flex and FDS artificats, for example business logic could be encapsulated in EJBs running in the mid-tier.
Debugging - within the Eclipse environment you are able to configure end-to-end debugging that allows you to step-through your Flex RIA-code and your server-side code (e.g. RPC services, EJBs, etc.).

From a runtime perspective FDS fits within the J2EE architecture, however from a development perspective within the IDE it doesn’t fit in to the J2EE development model. Eclipse provides an excellent Java development environment, which is extended by the WTP to aid the development of J2EE web applications. The WTP tooling understands the structure of a web module and an EJB JAR and how they combine to form an Enterprise application (EAR). With this in mind FDS is simply a unit of functionality within a web module, which is the concept of a project facet. A project facet allows you to add units of functionality to a web module, other examples include XDoclet and indeed Java support.

How to install the FDS Plugin

The plugin has been developed against Eclipse 3.1.2 + WTP 1.0.2 + Flex Builder 2. I downloaded the all-in-one WTP + Eclipse and then installed the Flex Builder plugins.

The plugin is developed against Java 5, so you will need the Java 5 JRE installed. I normally put a shortcut to the eclipse.exe on my desktop and edit the properties as follows:

C:\apps\adobe\flex2.0\wtp1.0.3\eclipse.exe -vm "C:\apps\java\jre1.5.0_06\bin\javaw.exe"

Remember to replace "C:\apps\java\jre1.5.0_06\bin\javaw.exe" with the path to "javaw.exe" on your PC.

The plugin is distributed using an Eclipse update site. To install the plugin start Eclipse and open Help > Software Updates > Find and Install. Create a new remote site with the following URL:

http://www.iterationtwo.com/fdsplugin/

Note: The update site is currently on the iteration::two web site as there are file size restrictions on the Adobe blog server. I hope to get it moved to a more permanent home in the near future.

You can also download the plugin from the Flex Exchange.

How to create an FDS aware Web project

You can create an FDS enabled web project one of two ways:

Open File > New > Project and select Web > Dynamic Web Project. Follow the wizard and select the Flex Data Services facet.
Open File > New > Project and select Flex Data Services > Flex Data Services Web Project.

You can of course add or remove a project facet at a later date using the project properties.

Hello World Example

The WTP platform comes with a number of server adapters, for example Tomcat. As yet there is currently no adapter for JRun. The compulsory "Hello World" example shows how to create an FDS Web project running on Tomcat.

Download and install Tomcat 5.5.
Start Eclipse.
Create an FDS project called HelloWorld.
The FDS project facet creates a default application (Main.mxml) under the content directory (WebContent) by default.
Open Main.mxml and add the following: <mx:Label text="Hello World" />
Open the Servers view, Window > Show View > Other > Server > Servers.
In the Servers view right-click and select New > Server.
Select Apache > Tomcat v5.5 Server.
On the next page configure the Tomcat installation directory and the JRE.
On the last page add the HelloWorld application.
Start your Tomcat server, right-click > Start.
Open the Run > Run....
Select Flex Application and click New.
Configure the application as follows, you will need to override the URL defaults:

Click Run.

You could also right-click Main.mxml and select Run As > Flex Application, however you would need to edit the configuration to manually configure the URLs as Flex Builder won't resolve them correctly.

You can now use that same run configuration to debug your application, just click the debug icon on your main toolbar. You can also start the server in debug mode and set breakpoints in your Java code. You can control your embedded server (e.g. start, stop, debug, etc.) by using the icons on the Servers view .

Source Code

The source code is included in the plugin (com.adobe.flex.enterprise.ui).

Posted by at 3:51 PM | Comments (54)

June 30, 2006

Cairngorm 2 + XDoclet2

With the release of Cairngorm on Adobe Labs the package name has changed from org.nevis.cairngorm to com.adobe.cairngorm. I have updated the AS3 plugin for XDoclet2 to reflect the new package name so all generated VOs will now implement com.adobe.cairngorm.vo.ValueObject. You can also download the source from here.

For more information on XDoclet2 please see my earlier blogs:

Posted by at 2:41 PM | Comments (6)

June 28, 2006

New FlexUnit Ant Task

Many thanks to Tony Hillerson of EUI for his contribution following my last blog on FlexUnit + Ant. Tony has taken the FlexUnit task and added the following properties:

haltonfailure - stop the build process if a failure occurs in one of the tests..
failureproperty - the name of a property to set if there is a failure in one of the tests..
verbose - print information about the test run.

The following example shows how to use these properties:

<target name="test-flex">
   <flexunit 
      swf="bin/AntTestRunner.swf"
      toDir="${flex-reports}"
      haltonfailure="false"
      verbose="true"
      failureproperty="flexunit.failed"	/>
		
   <junitreport todir="${flex-reports}">
      <fileset dir="${flex-reports}">
         <include name="TEST-*.xml"/>
      </fileset>
			
      <report format="frames" todir="${reports}/flex"/>
			
   </junitreport>
		
   <fail 
      message="One or more flexunit tests failed. See test reports for details." 
      if="flexunit.failed" />
</target>

Resources

Download the source for the flexunit Ant task.
Download the flexunit JAR.

Posted by at 1:32 PM | Comments (4)

June 1, 2006

FlexUnit + Ant

I have been planning this blog for some time, but was spurred on by a recent blog on Continous Integration in Flex. This blog concentrates on integration between Ant and FlexUnit, I will post a follow-up entry with details on how to setup a CruiseControl server for Continuous Integration.

This blog entry was written against Flex 2.0 Beta 3.

I have seen various postings about integration between FlexUnit with Ant, however most solutions seem to require a Flex server. My motivation here was to create an Ant task that has no dependency on a server. That would allow unit tests to be run in autonomously.

Very early on I decided if I was running the tests from Ant I wanted to re-use the JUnit tasks that already ship with Ant. In particular I wanted to use the JUnitReport task, which merges the XML files generated by the JUnit task to produce an HTML report. Therefore I wanted FlexUnit to print the results in the same XML format as the XML formatter used by the JUnit task.

The question was then how to make the XML test results available to the Ant tasks, my answer was to use XML sockets.

Technical Design

My solution is comprised of a controlling Ant task, flexunit, and a FlexUnit test runner, JUnitTestRunner, which is shown in the diagram below. The flexunit task starts a socket server running inside of a thread and launches the Flash Player, which runs the tests using the JUnitTestRunner. When JUnitTestRunner has finished running the test it formats the results as per the JUnit XML format and sends them to the flexunit task over an XML Socket, the flexunit task then saves them to disk. We can then use the JUnitReport task to create a report or use CruiseControl to create a report.

Requirements

Download the Ant distribution.
Download the example project (FlexUnitExample).

Software Installation

Extract the Ant distribution.
Add <your_ant_directory>\bin to your path.
Extract the FlexUnitExample project to your Eclipse/FB workspace (you only need to extract it into your workspace if you want to load the project into Eclipse/FB - select File > Import and follow the Existing Projects into Workspace wizard).
Edit <your_FlexUnitExample_directory>\build.properties and change the value of the flex.sdk.home property to the location of your Flex2 SDK installation (remember to use forward slashes).
The SWF containing your tests must run in the local trusted sandbox, copy FlexUnitExample.cfg from <your_FlexUnitExample_directory> to C:\Documents and Settings\<your_username>\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust.
Edit FlexUnitExample.cfg so it has the path to <your_FlexUnitExample_directory>\bin.

Example

To run the build script open a command prompt and change directory to <your_FlexUnitExample_directory>. To run the build script execute the following command: ant.

This will execute the Ant build script, which will run the SWF containing the tests and generate a JUnitReport report. The reports directory under <your_FlexUnitExample_directory> will contain the XML files created by JUnitTestRunner, you can view the report by opening <your_FlexUnitExample_directory>\reports\html\index.html. You should see two tests, one that passed and the other that failed.

Resources

You can download the source code for flexunit and JUnitTestRunner below, they are provided as an Eclipse Java Project and an Eclipse Flex Library project respectively.

Download the source for the flexunit Ant task (FlexAntTasks).
Download the source for the JUnitTestRunner (FlexUnitOptional).

You can import these projects into your workspace – extract the files into your workspace and in Eclipse select File > Import and follow the Existing Projects into Workspace wizard.

Posted by at 2:57 PM | Comments (27)

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)

July 31, 2008

*New* FlexAntTask - fails build if test suite doesn't execute

Binary distribution

Source Distribution

Example Project

Ant Task Parameters

September 27, 2007

FlexUnit for Ant now supports Mac OS X

Binary distribution

Source Distribution

Example Project

Ant Task Parameters

February 16, 2007

FDS Plugin V2

What's new?

January 17, 2007

Continuous Integration with CruiseControl + FlexUnit + XDoclet2

What software do I need?

Do I need anything else?

How do I install the software?

How do I run CruiseControl?

How do I configure a project?

FlexUnit for Ant Update#4

Binary distribution

Source Distribution

Example Project

Ant Task Parameters

January 9, 2007

FDS Plugin 2 (Beta)

Prerequisites

Installation

What's new?

November 11, 2006

FlexUnit for Ant Update#3

Binary distribution

Source Distribution

Example Project

Ant Task Parameters

August 7, 2006

FDS Plugin for Eclipse Web Tools Platform

What is the Eclipse Web Tools Platform?

Why the Eclipse Web Tools Platform?

How to install the FDS Plugin

How to create an FDS aware Web project

Hello World Example

Source Code

June 30, 2006

Cairngorm 2 + XDoclet2

June 28, 2006

New FlexUnit Ant Task

June 1, 2006

FlexUnit + Ant

Technical Design

Requirements

Software Installation

Example

Resources

April 28, 2006

XDoclet2 + AS3 + Ant + Cairngorm - Update I

Resources

April 22, 2006

XDoclet2 + AS3 + Ant + Cairngorm

Requirements

Software Installation

Example

Cairngorm

New FlexAntTask - fails build if test suite doesn't execute