JSON-RPC-Java

---

JSON-RPC-Java Tutorial

This tutorial briefly describes how to build JSON-RPC-Java and then get your JavaScript client code to call methods in a Java server application using JSON-RPC-Java and the included JavaScript JSON-RPC client.

Table Of Contents

• Requirements
• Building JSON-RPC-Java
• Building and installing JSON-RPC-Java Demos
• The JSONRPCServlet
• Adding the JSONRPCServlet to your web.xml
• The JSONRPCBridge
• Using the JSONRPCBridge in a JSP page
• Using the JSONRPCBridge in a Servlet
• Example JavaScript client application

Requirements

• ant 1.6 or later (to build)
• A Java Servlet container (such Apache Tomcat, the Tomcat service in JBoss, etc.).

Building JSON-RPC-Java

Edit build.xml in the top directory of the unpacked JSON-RPC-Java distribution and set the location of your tomcat installation. eg.

<property name="tomcat" location="/opt/jakarta-tomcat-5.5.7"/>

Then build jsonrpc.jar by running ant in the same directory.

ant

This will build jsonrpc.jar which contains the JSONRPCServlet (recieves the JSON-RPC requests; see section on adding this to your web.xml) and the JSONRPCBridge bean (decodes and dispatches the requests to your Java code; see sections on adding this to your JSP or servlet).

Building and installing JSON-RPC-Java Demos

To build the demo WAR file (Web Application Archive) jsonrpc.war:

ant test.dist

To install into your ${tomcat}/webapps directory (tomcat location needs to be set build.xml)

ant install

You should now be able to access your the demos on your local machine by pointing your browser at: http://localhost:8080/jsonrpc/

The JSONRPCServlet

This servlet, the transport part of JSON-RPC-Java, handles JSON-RPC requests over HTTP and dispatches them to a JSONRPCBridge instance registered in the HttpSession object.

Adding the JSONRPCServlet to your web.xml

Use the following web.xml (or add the servlet and servlet-mapping to your existing one):

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <servlet>
    <servlet-name>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-name>
    <servlet-class>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-name>
    <url-pattern>/JSON-RPC</url-pattern>
  </servlet-mapping>
</web-app>

The JSONRPCBridge

The JSONRPCBridge holds references to exported objects and decodes and dispatches method calls to them.

An instance of the JSONRPCBridge can be placed in an HttpSession object registered under the attribute "JSONRPCBridge" to allow the JSONRPCServlet to locate the bridge.

Session specific bridges can improve the security of applications by allowing exporting of object methods only to specific users (see the manual for notes about using the global bridge). In this way you can export privileged objects to users after they have gone through your application authentication mechanism.

To use the bridge to allow calling of Java methods you can put an instance of the bridge in a HttpSession in JSP using the usebean tag or in a Servlet using the HttpSesison API.

Using the JSONRPCBridge in a JSP page

Put a session scoped instance of the bridge into the HttpSession. eg.

...
<jsp:useBean id="JSONRPCBridge" scope="session"
   class="com.metaparadigm.jsonrpc.JSONRPCBridge" />
...

Then export the object you wish to call methods on. eg.

...
<% JSONRPCBridge.registerObject("myTestObject", aTestObject); %>
...

You will also need to emit the HTML to source the jsonrpc.js JavaScript code and your own client code. Add something like this to your header section:

...
  <script type="text/javascript" src="jsonrpc.js">
  <script type="text/javascript" src="myapp.js">
...

That is all that is requied to make available all methods of the object as myTestObject.<methodnames> to JSON-RPC clients.

Take a look at the example hello.jsp for more details.

Using the JSONRPCBridge in a Servlet

Put an instance of the bridge into the HttpSession. eg. in your service() method add the following code:

...
// Find the JSONRPCBridge for this session or create one
// if it doesn't exist. Note the bridge must be named "JSONRPCBridge"
// in the HttpSession for the JSONRPCServlet to find it.
HttpSession session = request.getSession();
JSONRPCBridge json_bridge = null;
json_bridge = (JSONRPCBridge) session.getAttribute("JSONRPCBridge");
if(json_bridge == null) {
    json_bridge = new JSONRPCBridge();
    session.setAttribute("JSONRPCBridge", json_bridge);
}
...

Then export the object you wish to call methods on. eg.

...
json_bridge.registerObject("myTestObject", aTestObject);
...

You will also need to emit the HTML to source the jsonrpc.js JavaScript code and your own client code. Add something like this to your header section:

...
out.println("<script type=\"text/javascript\" src=\"jsonrpc.js\"></script>");
out.println("<script type=\"text/javascript\" src=\"myapp.js\"></script>"); 
...

That is all that is requied to make available all methods of the object as myTestObject.<methodnames> to JSON-RPC clients.

Example JavaScript client application

The following example shows the simplest JSON-RPC client application

onLoad = function()
{
    try {

	jsonrpc = new JSONRpcClient("/<your webapp name here>/JSON-RPC");

        // Call a Java method on the server
        var result = jsonrpc.myTestObject.myFunction("hello");
        alert(result);

    } catch(e) {
	alert(e);
    }
}

Take a look at the example hello.js for more details