music and code by Gazbond

RPC-Servlet

Getting started with RPC-Servlet.


Categories: --All--, Java, jQuery

RCP-Servlet is a simple extensible RPC (remote procedural call) framework for exposing Java objects over HTTP as web services.

The framework allows services to define how they are accessed remotely via a series of handler interfaces as well providing implementations for a purely JSON based RPC protocol.

The framework also provides a JSON RPC client in the form of a jQuery plug-in.

The framework is loosely based on Redstone XML-RPC Library and inspired by working with the stateful web services of the Globus Toolkit and as such is a solution for stateful web services that is easy to use and compatible with AJAX style web applications.

Installing RCP-Servlet:

RCP-Servlet was created with Java SE 6 so it is probably best to run it with Tomcat 6.

Download Tomcat 6 from here and extract.

Clone RpcServlet from GitHub using the following:

$ git clone git@github.com:gazbond/RpcServlet.git

Change directory to [rpc-servlet-directory] and run the ant build file using the following:

$ ant

You should then see:

RpcServlet
	|-web
		|-WEB-INF
			|-classes
                |-rpc-services.properties
				|-gizmo
				|-org

Create the file rpc-servlet.xml in [tomcat-directory]/conf/Catalina/localhost/ with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="[rpc-servlet-directory]/web" path="/rpc-servlet"/>

Start Tomcat and go to http://localhost:8080/rpc-servlet/ in your browser.

There are three HTML files that demonstrate what RCP-Servlet can do:

1) test.html

This file simply invokes all the methods of the test service to demonstrate how RCP-Servlet handles various scenarios.
The test services source file can be found at gizmo.uk.toolkit.rpc.services.examples.TestService.
This test service declares various overloaded echo() methods that show how RCP-Servlet selects the correct overloaded method based on the remotely provided parameters received.
It also declares various methods to show how returning void or null and throwing exceptions or errors is handled.
It is also a session scope service so there are methods for demonstrating how instance variables are saved in session scope between remote invocations.

Screenshot

2) random.html

This file can be used to generate a random string of a particular length and reload a previously generated random string via the random service.
The random services source file is at gizmo.uk.toolkit.rpc.services.examples.RandomService.
The random service declares createRandomString(int length) and getLastRandomString() methods and is another session scope service so therefore it can save instance variables between remote invocations.

Screenshot

3) chat.html

This file is a very basic chat room application that uses the chat service to allow users to post messages to a message board.
The chat services source file can be found at gizmo.uk.toolkit.rpc.services.examples.ChatService.
A user logs in by providing a username and clicking the login button.
The chat service provides login(String username) and logout(String username) methods to accomplish this and being an application scope service stores the logged in users in a collection which is available to all users.
A logged in user can then post a message using the post(String username, String message) method of the chat service.
The posts are stored in an application scope collection and are displayed using the chat services getPosts(int page, int rows) method.
A list of logged in users is also shown and clicking a specific user will display the posts of that user.
This is accomplished with the chat services getUsers(int page, int rows) and getPosts(String username, int page, int rows) methods.

Screenshot

Creating services:

Creating your own service is very simple, all you need to do is decide whether your service should exist in request, session or application scope and then create a subclass of BaseJsonRequestScopeService, BaseJsonSessionScopeService or BaseJsonApplicationScopeService and code your service in the normal way you would write any Java class.
You then need to tell RCP-Servlet about your service.
RCP-Servlet reads a properties file that defines the service name and corresponding fully qualified class name. For example:

random = gizmo.uk.toolkit.rpc.services.examples.RandomService
test = gizmo.uk.toolkit.rpc.services.examples.TestService
chat = gizmo.uk.toolkit.rpc.services.examples.ChatService

The location of this file is set in the [rpc-servlet-directory]/web/WEB-INF/web.xml file as a parameter of RCP-Servlet’s init-param configuration called rpc-services-config. For example:

<servlet>
    <servlet-name>RpcServlet</servlet-name>
    <servlet-class>gizmo.uk.toolkit.rpc.RpcServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
    <init-param>
        <param-name>rpc-services-config</param-name>
        <param-value>/gizmo/uk/toolkit/rpc/services/examples/rpc-services.properties</param-value>
    </init-param>
</servlet>

To access your service remotely using the jQuery plugin simple use the following:

$.rpc.invoke(url, method, params, function(data) {

    // handle returned data here
});

And thats it… simples :)

Comments are closed.