R1-RPC/J Samples

Run the Samples

All the samples are prebuilt as J2EE WAR files. Deploy any of those WAR files to your servlet container to run. Suppose you run Apache Tomcat with the default configuration, then all you have to do is copy the WAR files into $tomcat/webapps/ folder. For instance, copy simple_login.war there; start the Tomcat server, and open a browser with this URL: http://localhost:8080/simple_login.

Build the Samples

All the samples have Ant build scripts under their buildtools folder. To build, first make sure of the follow:

1. Have Ant (version 1.6.5 or higher) installed with the R1-RPC/J build tools. That is, make sure r1tools.jar and the Velocity template engine library jar files are copied into the lib/ directory of your Ant installation.
2. Edit the env.properties file to point to the correct locations such as Flex SDK, etc. This file is in the same directory as the build.xml per each sample.

Run ant on the command line, and the whole application, in many cases with the RPC unit testing application, will be build into a WAR file, in $sample/buildtools/build/ folder. Also note that, VO and façade classes are generated in $samples/buildtools/build/client_src/ from server Java source. (If you want to build the Flex client manually with Flex Builder, this is where to find those classes.

The Details of the Samples

 

The URLs given below uses localhost:8080 as the domain, assuming a default installation of Apache Tomcat or similar servlet container. A typical sample URL would be: http://localhost:8080/simple_rpc/, and a typical RPC unit test URL would be: http://localhost:8080/simple_rpc/rpc_unit_test/.

---

Simple RPC

Available Applications	URL
Application	http://localhost:8080/simple_rpc/
RPC Unit Test	http://localhost:8080/simple_rpc/rpc_unit_test/

This is the simplest example of RPC: the façade just have a simple method:

/**
 * @ASTestInput [ 'James' ]
 * @ASTestResult x == 'Hello, James!'
 */
public String sayHi(String name) {
    return "Hello, " + name + '!';
}

The UI takes a string as name and calls the façade method and display the result in a <TextArea>.

---

Data Type Test

Available Applications	URL
RPC Unit Test	http://localhost:8080/datatype_test/rpc_unit_test/

This is for testing all the supported Java data types. It has only the RPC unit test application is used.

There are a number of façades for various test suites:

• BasicTestFacade.java
• DeepTestFacade.java
• ExoticClassesFacade.java
• GenTestFacade.java

---

Using Value Object Classes

Available Applications	URL
Application	http://localhost:8080/using_vo/

This sample is to test embedded ActionScript 3 code in the Java VO class, and the situation with a Java VO class property of non-VO value, where there should not be a corresponding property in the generated AS3 VO class.

---

Simple RPC with Login

Available Applications	URL
Application	http://localhost:8080/simple_login/
RPC Unit Test	http://localhost:8080/simple_login/rpc_unit_test/

This sample uses plain-text password user login. The server façade class is similar to that of the Simple RPC, but the sayHi() method does not take any parameters, but rather returns the name of the current user. The UI first presents the login screen; once logged in, a "Say Hello to Myself" button does the normal test. On the login screen, you click "Try to Say Hello" button, which should give you a SERVER_AUTH_FAILURE exception thrown by the server-side authentication.

On the server side, it has an implementation for interface LoginHandler, MyLoginHandler, with these methods implemented or overridden:

boolean doEncrypt() { return false; } // overridden
String getPasswordDigest(String id) { ...  }
void savePasswordDigest(String id, String digest) { ...  }
Object loadUser(String id) { ...  }

On the client side, once an RPC object is initialized, it sets the following:

RPC.defaultRPC.passwordEncrypted = false;

By default, the RPC uses encrypted password (CHAP) for login.

The RPC unit test application tests the authorized method. Since we specified the test user name and password in the fa&ccedi;ade class, the testing application automatically login.

---

CHAP Login

Available Applications	URL
Application	http://localhost:8080/chap_login/
RPC Unit Test	http://localhost:8080/chap_login/rpc_unit_test/

This sample uses CHAP user registration and authentication for calling authorized server methods. With CHAP, passwords are never transmitted across wire, so user registration must be a part of the authentication process unless there is a similar process to mimic that offline. The application behaves much the same way as Simple RPC with Login sample except for user registration.

Programming-wise, on the server side, the implementation for LoginHandler, MyLoginHandler, has these methods implemented:

String getPasswordDigest(String id) { ...  }
String createUser(String id, String digest, Object data) { ... }
void savePasswordDigest(String id, String digest) { ...  }
Object loadUser(String id) { ...  }

The RPC unit test application works for the authenticated method, AuthorizedFriendlyFacade.sayHi(). The user must first register and login before testing the remote method call. For testing purpose only, there is an unauthorized facade class, FriendlyFacade, whose method can be called without user logging in; this façade is not used in the application itself.

---

RPC Exception Handling and Session Timeout

Available Applications	URL
Application	http://localhost:8080/rpc_exception_and_session_to/

This sample is a lot like Simple RPC with Login, except that it has a call to a Java method that simply throws an exception. On the client side, In the call of RPC.initSingleRPC(), it turns of session_never_time_out flag, which by default is true, so that session refresh events are not fired and the application will time out for server accesses.

---

RPC Interception (AOP)

Available Applications	URL
Application	http://localhost:8080/rpc_aop/

This sample demonstrates how to use the RPC interception feature with R1-RPC/J. The application behaves much like other authorized RPC testing, but it has more server methods, and many of them are specified to be intercepted by an interceptor of class MyCallInterceptor, which prints out debug messages on System.out for intercepted call events.

---

Chat

Available Applications	URL
Application	http://localhost:8080/chat/

This is the Chat application using R1-RPC/J's messaging capability. To use, launch two browser instances, register a user and login in each of them, and start chatting with each other.

On the server side, a message handler, class MyMessageHandler, is specified in web.xml. The user registration and login system is essentially the same as CHAP login sample, but the UserVO class does more than normal VOs do: it also maintains a message queue for every message destined for that suer. A server internal class, MessageServices, provides the messaging services; it keeps all the current users and dispatches messages. More sophisticated messaging such as JMS is not used in order to keep this sample simlpe and compact.

The messages are represented by various VO classes. In addition to chatting messages, there are system ones such as when users login or logout. The real messaging VO classes, such as ChatMessage and UserJoinMessage, extend a base class, ServerMessage. All these classes have client-side counterparts.

This sample's UI is a little richer than others. It uses a UIController class to handle most of the logic, leaving MXML files cleaner. For more details, please refer to the source code.

Using this sample as a starting point, you can build highly interactive applications with very little overhead.

---

Flash RPC

Available Applications	URL
Application	http://localhost:8080/flash_rpc/

This sample shows how Flash programs use R1-RPC/J to call server side Java. The functionality of this application is the same as Simple RPC. Naturally, you can use any features of R1-RPC/J from a Flash program.

The client Flash program is a .fla created with Flash CS3. The .swf file is gnerated from there. The Ant build script simply compiles the server Java classes and bundles the whole J2EE web application.

---

Spring Example

Available Applications	URL
Application	http://localhost:8080/Spring_example/

This example is a skeleton R1-RPC/J application with the Spring Framework on the server-side. Functionally it is the same as simple_login.