R1-Tools User's Guide

May 2008

• Introduction to R1-Tools
• Command-Line Tools for R1-RPC/J Code Generation
• Ant Tasks for R1-RPC/J Code Generation
• Ant Tasks for Adobe® Flex™ Operations

---

 

Introduction to R1-Tools

The R1-Tools is a Java library, included in the R1-RPC/J Toolkit. It contains the code generations tools for R1-RPC/J, and a number of generic Ant tasks for Adobe® Flex™ project building operations.

The R1-RPC/J Code Genration Tools

The R1-RPC/J code genration tools include an ActionScript 3 code generator for server-side Java façade and VO classes and a client test suite code generator for server-side Java façade classes. Both tools can be run on the command-line and as Ant tasks.

The Generic Ant Tasks for Adobe® Flex™ Operations

Generic Ant tasks are also provided for building and documentating Adobe® Flex™ projects, such as mxmlc, compc, htmlwrapper and asdoc. They maintain certain advantages over what is available on the market now.

Command-Line Tools for R1-RPC/J Code Generation

The command-line tools for R1-RPC/J code generation are built as Javadoc doctlets, and use the Velocity template engine; therefore, at runtime, the JDK's tools.jar library and Velocity libraries must be in the classpath.

The client code generator is class r1.tools.java2client.ASCodeGen. Running this class without parameters prints out the usage message:

c:\>java r1.tools.java2client.ASCodeGen

Running ASCodeGen doclet to generate remote facade and VO classes.

usage: java r1.tools.java2client.ASCodeGen
            <Java_Packages>|<Java_Source_Files>
 -subpackages          Optional. When specified, takes package names
                       separated by colon; all sub-packages are included also.
                       An alternative to specifying packages or source file names.
 -exclude              Optional. When specified in the same format as
                       -subpackages, those package are excluded.
 -dest                 base directory for generated test client soure
                       files
 -exceptionOnError     when specified, throws an exception on error (used
                       by the ant task).
 -src                  base directory for Java source files
 -useFacadeInterface   when specified, the generated facade class will
                       implment a generate interface.
 -verbose              when specified, display more information in the process.

The client test suite generator is class r1.tools.java2client.ASTestGen. Likewise, running it without parameters prints out the usage message:

c:\>java r1.tools.java2client.ASTestGen

usage: java r1.tools.java2client.ASTestGen
            <Java_Packages>|<Java_Source_Files>
 -subpackages        Optional. When specified, takes package names
                     separated by colon; all sub-packages are included also.
                     An alternative to specifying packages or source file names.
 -exclude            Optional. When specified in the same format as
                     -subpackages, those package are excluded.
 -dest               base directory for generated test client soure files
 -exceptionOnError   when specified, throws an exception on error (used by
                     the ant task).
 -src                base directory for Java source files
 -verbose            when specified, display more information in the process.

The exceptionOnError should not used on command-line; it is for their Ant tasks.

Ant Tasks for R1-RPC/J Code Generation

The R1-RPC/J Toolkit includes good Ant build script support. It contains Ant tasks, <java2as> and <astestgen>, for the two code generation tools, as well as Ant tasks for general Adobe® Flex™ application compilation and deploying.

All the Ant tasks work with Ant version 1.6.5 or higher. First, copy r1tools.jar and the Velocity template engine library jar files into the lib/ directory of your Ant installation. In your Ant build scripts (usually named build.xml), add a line like this:

<taskdef resource="ant.tasks" classpath="r1tools.jar" />

Note that, in the Ant build script, the flexsdk.home property must be set in order to use these tasks.

An example of client code generation is like this:

<java2as destBase="${build.client.src.dir}">
    <fileset dir="${server.src.dir}">
        <include name="**/*.java" />
    </fileset>
</java2as>

The following is an example of RPC unit test case generation:

<astestgen testAppTitle="${test.webapp.title}" rpcUri="../rpc"
        destBase="${build.client.src.dir}">
    <fileset dir="${server.src.dir}">
        <include name="**/*.java" />
    </fileset>
</astestgen>

Ant Tasks for Adobe® Flex™ Operations

There are different Ant task packages available for Adobe® Flex™ operations. All of them are free. But somehow many of them come slightly short of expection.

The R1-Tools, packaged in r1tools.jar, also provides a set of Ant tasks for generic Adobe® Flex™ operations, such as mxmlc, compc, asdoc, and htmlwrapper. The key characteristics, or advantages, include the following:

1. The mxmlc, compc, and asdoc tasks can take <fileset> values, in which you can specify source files to include and exclude. This is particularly useful for compc and asdoc tasks.
2. The mxmlc and compc tasks compare the timestamps of the source and of the target, and do a conditional compile.
3. Most of the other parameters are specified as <arg> values, which means that they are just regular command-line parameters and no re-definitions are introduced.
4. The htmlwrapper task can take a base directory for the templates, rather than a template type name. You can keep, modify, and source control the template files like any other resources in your project without worrying about the hassle making changes inside the Flex SDK installation.

The following two tables lists the attributes of these Ant tasks.