R1-RPC/J Tutorial

Version 1.2   July 2008

May 2008

• About This Tutorial
• Manually Develop the Application
• Automated Build with Ant
• Building the RPC Unit Testing Application

---

 

About This Tutorial

R1-RPC/J is a simple, easy-to-understand RPC bridge between Flex client and Java server-side. A kep component of this solution is code generation, which adds one more step in the development process. Fortunately, code generation is quite common in software development, and people are comfortable with that. This tutorial will use a couple of small projects to talk through the development process, starting from totally manual building, to automated building with Ant, to using IDEs such as Flex Builder and Eclipse for Java.

R1-RPC/J in a Nutshell

In a nutshell, the R1-RPC/J solution is a seamless RPC calling from the client ActipScript 3 (AS3) code to the server-side Java services. On the server side, services are exposed as methods in a façade class; the R1-RPC/J code generation tool generates a counterpart &façade class (along with any related Value Object (VO) classes) in AS3 for the client; the client code calls the server methods almost like directly calling the Java methods, and use value objects, defined in Java but created in AS3 by the code generation. In other words, the AS3 client and server-side Java communicate with strongly-typed values, not some generic Objects. The resultant client code is very clean; this is the beauty of this solution.

The R1-RPC/J solution provides a robust user authentication scheme, and services can be simply declared as authorized or non-authorized. To take advantage of this, a few more steps are needed.

The R1-RPC/J solution also includes a great development aid, the automated unit testing mechanism. R1-RPC/J can generate a test suite for each Java façade class, and a client testing UI is created without writing a single line of code (the UI code is available). This test UI makes RPC calls exactly like your real client application. It is a great way to isolate RPC issues from the rest, facilitating team development and test-driven development (for the RPC part of the system).

Developing with R1-RPC/J in a Nutshell

Once the solution of R1-RPC/J is understood, the development process becomes obvious. There are three scenarios: a) simple, non-authorized RPC calls; b) using authorized RPC calls; and c) using the automated unit testing. The processes for the first two scenarios are the same, except that there is more server-side work to be done when user authentication is required.

This is the process of using RPC calls:

1. On the server side, define the Java façade and VO classes.
2. Run the R1-RPC/J code generation tool to produce client-side counterpart façade and VO classes in AS3.
3. Implement the server-side Java façade methods.
4. Deploy the server-side Java system.
5. Develop the client program using RPC calls through the client-side façade objects.

This is the process of creating the RPC unit testing application:

1. On the server side, define the Java façade and VO classes.
2. Run the R1-RPC/J code generation tool to produce client-side counterpart façade and VO classes in AS3.
3. Run the R1-RPC/J test suite generation tool to produce client-side test suite classes in AS3.
4. Build the test application, mostly likely by running the shipped Ant build script.
5. Deploy the server-side Java system, and launch the test client.

Setting Up the Development Environment

The following table lists all the tools and software to install and set up. You can omit the ones for an environment that you do not care. For instance, if all you care about is to build in shells on command line, you do not need to install IDEs.

Manually Develop the Application

Let us manually develop the simple_rpc sample application. The original files for this sample are under ${r1rpc.home}/samples/simple_rpc like so:

${r1rpc.home}/samples/simple_rpc/client-src/Main.mxml
${r1rpc.home}/samples/simple_rpc/server-src/sample/FriendlyFacade.java
${r1rpc.home}/samples/simple_rpc/buildtools/web.xml

First of all, move to directory ${r1rpc.home}/samples/simple_rpc/, and run this command line:

java r1.tools.java2client.ASCodeGen -src server_src -dest client_src sample

This will generate an AS3 file:

${r1rpc.home}/samples/simple_rpc/client-src/sample/FriendlyFacade.as

The server side of this application is run on a Tomcat, in ${webapps.home}/simple_rpc/. Copy the web.xml there under WEB-INF, compile the Java class into WEB-INF/classes/, and copy ${r1rpc.home}/libs/r1rpc-1.2.jar into WEB-INF/lib/. The server side is all set. The server side deployment files look like this:

${webapps.home}/simple_rpc/WEB-INF/web.xml
${webapps.home}/simple_rpc/WEB-INF/lib/r1rpc-1.2.jar
${webapps.home}/simple_rpc/WEB-INF/classes/sample/FriendlyFacade.class

Now, let us build the client. In this application, we need just these files:

${r1rpc.home}/libs/r1rpc-1.2.swc
${r1rpc.home}/samples/simple_rpc/client-src/Main.mxml
${r1rpc.home}/samples/simple_rpc/client-src/sample/FriendlyFacade.as

Use Flex Builder or Flex SDK's mxmlc tool to build the client, and keep the generated HTML wrappers and the swf file in ${webapps.home}/simple_rpc/. Start the server and launch a browser to point to the HTML wrapper to test the remoting.

Automated Build with Ant

All the Flex samples in the R1-RPC/J distribution have Ant build scripts. Many of them are the same; specific samples may have minor differences. For your application development, find a sample that is closest in nature and adapt its Ant build model. Here, we will use the Ant build script for the simple_rpc to demonstrate its use.

Go to ${r1rpc.home}/samples/simple_rpc/buildtools/, where the build.xml is located

${r1rpc.home}/samples/simple_rpc/buildtools/build.xml
${r1rpc.home}/samples/simple_rpc/buildtools/env.properties
${r1rpc.home}/samples/simple_rpc/buildtools/flex-config.xml.base
${r1rpc.home}/samples/simple_rpc/buildtools/web.xml

You must modify entries in env.properties file to reflect your development environment. The shipped version contains entries for our developers, and they must be changed.

#============================================================
# Must-set environmental values.

flexsdk.home=d:/FB3/sdks/3.0.0
r1rpc.home=h:/p4_builds/r1rpc/ship/r1rpc-1.2

r1rpc.jar.file=r1rpc-1.2.jar
r1rpc.swc.file=r1rpc-1.2.swc

webapp.name=simple_rpc
webapp.title=Simple RPC Test

server.src.dir=../server-src
client.src.dir=../client-src


#============================================================
# The client Flex app template.

#webapp.template.dir=


#============================================================
# The Unit Test client Flex app template.

#test.webapp.template.dir=


#============================================================
# The wrapper values; all optional.

#wrapper.version_major=9
#wrapper.version_minor=0
#wrapper.version_revision=124
#wrapper.width=100%
#wrapper.height=100%
#wrapper.bgcolor=#869ca7

Once the entries are set right, simply run ant from the command line, a J2EE war will be generated for you in the build/ directory, created by the script. As a last step, copy ${r1rpc.home}/samples/simple_rpc/buildtools/build/simple_rpc.war to ${webapps.home}/, clean up old remnants there and restart the Tomcat (or whatever your servlet engine). Point your browser to http://localhost:8080/simple_rpc/ to run the application.

Building the RPC Unit Testing Application

In the above simple_rpc sample application building, the war file also includes the RPC unit testing application already. Simply point your browser to http://localhost:8080/simple_rpc/rpc_unit_test/ to run the tests. To learn more about the building of the RPC test application, refer to the build/ directory where the final simple_rpc.war resides; it contains all the intermediate files during the build process, some of which are unit test related, listed below:

build/client_dir/src/testsuites.inc
build/client-src/src/sample/FriendlyFacadeTestSuite.as
build/client-src/src/sample/FriendlyFacade.as
build/client_dir/src/TesterMain.mxml
build/client-src/src/r1/rpc/testing/ui/TestUI.mxml
build/client-src/src/r1/rpc/testing/ui/AboutBox.mxml

The first two files are generated by the R1-RPC/J generation, and the last three are source code copied from R1-RPC/J distribution. You can modify the build script and adapt the UI for your own needs, e.g., adding detailed test instructions to the AboutBox.mxml popup.

 

---

 

Now that we have cleared the way of the development process for R1-RPC/J, you can focus on R1-RPC/J programming topics comprehensively covered in R1-RPC/J User's Guide.