com.metaparadigm.jsonrpc
Class JSONRPCBridge

java.lang.Object
  extended by com.metaparadigm.jsonrpc.JSONRPCBridge
All Implemented Interfaces:
java.io.Serializable

public class JSONRPCBridge
extends java.lang.Object
implements java.io.Serializable

This class implements a bridge that unmarshalls JSON objects in JSON-RPC request format, invokes a method on the exported object, and then marshalls the resulting Java objects to JSON objects in JSON-RPC result format.

An instance of the JSONRPCBridge object is automatically placed in the HttpSession object registered under the attribute "JSONRPCBridge" by the JSONRPCServlet.

The bridge is implemented as session specific to improve the security of applications by allowing exporting of object methods only to specific HttpSessions.

To use the bridge to allow calling of Java methods you can easily access the HttpSession specific bridge in JSP using the usebean tag. 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("test", testObject);

This will make available all methods of the object as test.<methodnames> to JSON-RPC clients. This method should generally be performed after an authentication check to only export specific objects to clients that are authorised to use them.

There exists a global bridge singleton object that will allow exporting objects to all HTTP clients. This can be used for registering factory classes although care must be taken with authentication as these objects will be accessible to all clients.

See Also:
Serialized Form

Constructor Summary
JSONRPCBridge()
           
JSONRPCBridge(boolean useDefaultSerializers)
           
 
Method Summary
 JSONRPCResult call(java.lang.Object[] context, JSONObject jsonReq)
           
 void enableReferences()
           
static JSONRPCBridge getGlobalBridge()
          This method retreieves the global bridge singleton.
 JSONSerializer getSerializer()
           
 java.lang.Class lookupClass(java.lang.String name)
          Lookup a class that is registered with this bridge.
 java.lang.Object lookupObject(java.lang.String key)
          Lookup an object that is registered with this bridge.
 void registerCallableReference(java.lang.Class clazz)
          Registers a class to be returned as a callable reference.
 void registerCallback(InvocationCallback callback, java.lang.Class contextInterface)
          Registers a callback to be called before and after method invocation
 void registerClass(java.lang.String name, java.lang.Class clazz)
          Registers a class to export static methods.
static void registerLocalArgResolver(java.lang.Class argClazz, java.lang.Class contextInterface, LocalArgResolver argResolver)
          Registers a Class to be removed from the exported method signatures and instead be resolved locally using context information from the transport.
 void registerObject(java.lang.Object key, java.lang.Object o)
          Registers an object to export all instance methods and static methods.
 void registerObject(java.lang.Object key, java.lang.Object o, java.lang.Class interfaceClass)
          Registers an object to export all instance methods defined by interfaceClass.
 void registerReference(java.lang.Class clazz)
          Registers a class to be returned by reference and not by value as is done by default.
 void registerSerializer(Serializer s)
           
 void setDebug(boolean debug)
           
 void setSerializer(JSONSerializer ser)
           
 void unregisterCallback(InvocationCallback callback, java.lang.Class contextInterface)
          Unregisters a callback
 void unregisterClass(java.lang.String name)
          Unregisters a class exported with registerClass.
static void unregisterLocalArgResolver(java.lang.Class argClazz, java.lang.Class contextInterface, LocalArgResolver argResolver)
          Unregisters a LocalArgResolver.
 void unregisterObject(java.lang.Object key)
          Unregisters an object exported with registerObject.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JSONRPCBridge

public JSONRPCBridge()

JSONRPCBridge

public JSONRPCBridge(boolean useDefaultSerializers)
Method Detail

call

public JSONRPCResult call(java.lang.Object[] context,
                          JSONObject jsonReq)

enableReferences

public void enableReferences()
                      throws java.lang.Exception
Throws:
java.lang.Exception

getGlobalBridge

public static JSONRPCBridge getGlobalBridge()
This method retreieves the global bridge singleton. It should be used with care as objects should generally be registered within session specific bridges for security reasons.

Returns:
returns the global bridge object.

getSerializer

public JSONSerializer getSerializer()

lookupClass

public java.lang.Class lookupClass(java.lang.String name)
                            throws java.lang.Exception
Lookup a class that is registered with this bridge.

Parameters:
name - The registered name of the class to lookup.
Throws:
java.lang.Exception

lookupObject

public java.lang.Object lookupObject(java.lang.String key)
                              throws java.lang.Exception
Lookup an object that is registered with this bridge.

Parameters:
key - The registered name of the object to lookup.
Throws:
java.lang.Exception

registerCallableReference

public void registerCallableReference(java.lang.Class clazz)
                               throws java.lang.Exception
Registers a class to be returned as a callable reference. The JSONBridge will return a callable reference to the JSON-RPC client for registered classes instead of passing them by value. The JSONBridge will take a references to these objects and the JSON-RPC client will create an invocation proxy for objects of this class for which methods will be called on the instance on the server.

Note: A limitation exists in the JSON-RPC client where only the top most object returned from a method can be made into a proxy.

A Callable Reference in JSON format looks like this:

{ "javaClass":"com.metaparadigm.test.Bar",
"objectID":4827452,
"JSONRPCType":"CallableReference" }

Parameters:
clazz - The class object that should be marshalled as a callable reference.
Throws:
java.lang.Exception

registerCallback

public void registerCallback(InvocationCallback callback,
                             java.lang.Class contextInterface)
Registers a callback to be called before and after method invocation

Parameters:
callback - The object implementing the InvocationCallback Interface
contextInterface - The type of transport Context interface the callback is interested in eg. HttpServletRequest.class for the servlet transport.

registerClass

public void registerClass(java.lang.String name,
                          java.lang.Class clazz)
                   throws java.lang.Exception
Registers a class to export static methods. The JSONBridge will export all static methods of the class. This is useful for exporting factory classes that may then return CallableReferences to the JSON-RPC client.

To export instance methods you need to use registerObject.

Parameters:
name - The named prefix to export the class as
clazz - The class to export static methods from.
Throws:
java.lang.Exception

registerLocalArgResolver

public static void registerLocalArgResolver(java.lang.Class argClazz,
                                            java.lang.Class contextInterface,
                                            LocalArgResolver argResolver)
Registers a Class to be removed from the exported method signatures and instead be resolved locally using context information from the transport.

Parameters:
argClazz - The class to be resolved locally
argResolver - The user defined class that resolves the and returns the method argument using transport context information
contextInterface - The type of transport Context object the callback is interested in eg. HttpServletRequest.class for the servlet transport

registerObject

public void registerObject(java.lang.Object key,
                           java.lang.Object o)
Registers an object to export all instance methods and static methods. The JSONBridge will export all instance methods and static methods of the particular object under the name passed in as a key.

This will make available all methods of the object as <key>.<methodnames> to JSON-RPC clients.

Parameters:
key - The named prefix to export the object as
o - The object instance to be called upon

registerObject

public void registerObject(java.lang.Object key,
                           java.lang.Object o,
                           java.lang.Class interfaceClass)
Registers an object to export all instance methods defined by interfaceClass. The JSONBridge will export all instance methods defined by interfaceClass of the particular object under the name passed in as a key. This will make available these methods of the object as <key>.<methodnames> to JSON-RPC clients.

Parameters:
key - The named prefix to export the object as
o - The object instance to be called upon
interfaceClass - The type that this object should be registered as. This can be used to restrict the exported methods to the methods defined in a specific superclass or interface.

registerReference

public void registerReference(java.lang.Class clazz)
                       throws java.lang.Exception
Registers a class to be returned by reference and not by value as is done by default.

The JSONBridge will take a references to these objects and return an opaque object to the JSON-RPC client. When the opaque object is passed back through the bridge in subsequent calls, the original object is substitued in calls to Java methods. This should be used for any objects that contain security information or complex types that are not required in the Javascript client but need to be passed as a reference in methods of exported objects.

A Reference in JSON format looks like this:

{ "javaClass":"com.metaparadigm.test.Foo",
"objectID":5535614,
"JSONRPCType":"Reference" }

Parameters:
clazz - The class object that should be marshalled as a reference.
Throws:
java.lang.Exception

registerSerializer

public void registerSerializer(Serializer s)
                        throws java.lang.Exception
Throws:
java.lang.Exception

setDebug

public void setDebug(boolean debug)

setSerializer

public void setSerializer(JSONSerializer ser)

unregisterCallback

public void unregisterCallback(InvocationCallback callback,
                               java.lang.Class contextInterface)
Unregisters a callback

Parameters:
callback - The previously registered InvocationCallback object
contextInterface - The previously registered transport Context interface.

unregisterClass

public void unregisterClass(java.lang.String name)
                     throws java.lang.Exception
Unregisters a class exported with registerClass. The JSONBridge will unexport all static methods of the class.

Parameters:
name - The registered name of the class to unexport static methods from.
Throws:
java.lang.Exception

unregisterLocalArgResolver

public static void unregisterLocalArgResolver(java.lang.Class argClazz,
                                              java.lang.Class contextInterface,
                                              LocalArgResolver argResolver)
Unregisters a LocalArgResolver.

Parameters:
argClazz - The previously registered local class
argResolver - The previously registered LocalArgResolver object
contextInterface - The previously registered transport Context interface.

unregisterObject

public void unregisterObject(java.lang.Object key)
Unregisters an object exported with registerObject. The JSONBridge will unexport all instance methods and static methods of the particular object under the name passed in as a key.

Parameters:
key - The named prefix of the object to unexport


Copyright © 2005 Metaparadigm Pte Ltd.