jabsorb
Java to JavaScript Object Request Broker

jabsorb Tutorial

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

Table Of Contents

Requirements

Building jabsorb

Jabsorb is built with ant, and produces 2 important release files:

The .jar file is what you would include in your own web applications in order to service json-rpc calls via jabsorb.

The .war file is an example web application built with jabsorb. It contains several demonstration applications, unit tests and other miscellaneous development features.

There is one other important file that is needed for your application as well:

This is the client side JavaScript module needed to make JSON-RPC calls from the web browser into a jabsorb enabled web application. Note that the build script also creates a minified version of this file, jsonrpc-min.js, for quicker downloading on production systems. Gzipped versions are also created for web servers (such as jetty) that can take advantage of this.

The main ant file is build.xml in the top directory of the unpacked jabsorb distribution.

There is one file used to configure the build:

This can be used to customize locations and names of various build properties.

Typically you will need to edit the build.properties and set the location of your tomcat webapp directory. eg. 

installpath=/Tomcat/Tomcat4.1.31/webapps

Then build jabsorb-1.2.jar by running ant in the same directory. 

ant

This will build jabsorb-1.2.jar which contains the JSONRPCServlet (receives the JSON-RPC requests; see section on adding this to your web.xml), the JSONRPCBridge bean (decodes and dispatches the requests to your Java code; see sections on adding this to your JSP or servlet), and the various serializers and related support code.

Building and installing jabsorb Demos

To build the demo WAR file (Web Application Archive) jabsorb-1.2.war: 

ant test.dist

To install into your ${installpath} directory (your web container location needs to be set in build.properties) 

ant install

You should now be able to access your the demos on your local machine by pointing your browser at: http://localhost:8080/jabsorb-1.2/index.jsp

Other useful ant targets include: 

ant uninstall    // removes the jabsorb .war from tomcat
ant clean        // cleans out previously created build artifacts
ant docs         // builds the javadoc
ant release      // build complete set of release download distributions

The JSONRPCServlet

This servlet, the transport part of jabsorb, 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): 

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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>JSONRPCServlet</servlet-name>
    <servlet-class>org.jabsorb.JSONRPCServlet</servlet-class>
    <!--
      the gzip_threshold indicates the response size at which the servlet will attempt to gzip the response
      if it can.
      Set this to -1 if you want to disable gzip compression for some reason,
      or if you have another filter or other mechanism to handle gzipping for you.
      Set this to 0 to attempt to gzip all responses from this servlet.
      otherwise, set it to the minimum response size at which gzip compression is attempted.
      note:  if the browser making the request does not accept gzip compressed content,
      or the result of gzipping would cause the response size to be larger (this could happen
      with very small responses) then the content will be returned without gzipping regardless
      of this setting, so it is very reasonable idea to set this to 0 for maximum bandwidth
      savings, at the (very minor) expense of having the server attempt to gzip all responses.
    -->
    <init-param>
      <param-name>gzip_threshold</param-name>
      <param-value>200</param-value>
    </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>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 a JSP using the usebean tag or in a Servlet using the HttpSession 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="org.jabsorb.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 = (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 include 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

/!\ this example uses synchronous calls. Use of synchronous calls is highly discouraged in production code because it can cause the browser to freeze if the server does not respond in a timely manner. Asynchronous calls are recommended in all but trivial applications. See the Manual for more information on synchronous and asynchronous calls.

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