com.metaparadigm.jsonrpc
Class JSONRPCBridge

java.lang.Object
  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.

There is a global bridge singleton object that allows exporting classes and objects to all HTTP clients. In addition to this, an instance of the JSONRPCBridge can optionally be placed in a users' HttpSession object registered under the attribute "JSONRPCBridge" to allow exporting of classes and objects to specific users. A session specific bridge will delegate requests for objects it does not know about to the global singleton JSONRPCBridge instance.

Using session specific bridge instances can improve the security of applications by allowing exporting of certain objects only to specific HttpSessions as well as providing a convenient mechanism for JavaScript clients to access stateful data associated with the current user.

You can create a HttpSession specific bridge in JSP with the usebean tag:

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

Then export an object for your JSON-RPC client to call methods on:

JSONRPCBridge.registerObject("test", testObject);

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

Alternatively, the global bridge singleton object allows exporting of classes and objects to all HTTP clients. It can be fetched with JSONRPCBridge.getGlobalBridge().

To export all public instance methods of an object to all clients:

JSONRPCBridge.getGlobalBridge().registerObject("myObject", myObject);

To export all public static methods of a class to all clients:

JSONRPCBridge.getGlobalBridge().registerClass("MyClass", com.example.MyClass.class);

See Also:

Serialized Form

Constructor Summary

JSONRPCBridge()
Default Constructor.

Method Summary

JSONRPCResult	call(java.lang.Object[] context, JSONObject jsonReq) Call a method using a JSON-RPC request object.
JSONRPCBridgeState	getBridgeState() Get the JSONRPCBridgeState object associated with this bridge.
CallbackController	getCallbackController() Get the CallbackController object associated with this bridge.
static JSONRPCBridge	getGlobalBridge() This method retrieves the global bridge singleton.
java.util.HashMap	getReferenceMap() Gets the map of referenced objects used by this bridge.
static JSONSerializer	getSerializer() Get the global JSONSerializer object.
boolean	isCallableReference(java.lang.Class clazz) Check whether a class is registered as a callable reference type.
boolean	isReference(java.lang.Class clazz) Check whether a class is registered as a reference type.
java.lang.Class	lookupClass(java.lang.String name) Lookup a class that is registered with this bridge.
java.lang.Object	lookupObject(java.lang.Object 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 serializer) Register a new serializer on this bridge.
void	setBridgeState(JSONRPCBridgeState state) Set the JSONRPCBridgeState object for this bridge.
void	setCallbackController(CallbackController cbc) Set the CallbackController object for this bridge.
void	setDebug(boolean debug) Enable or disable debugging message from this bridge instance.
void	setExceptionTransformer(ExceptionTransformer exceptionTransformer)
static void	setSerializer(JSONSerializer ser) Set the global JSONSerializer object.
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()

Default Constructor.

Method Detail

call

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

Call a method using a JSON-RPC request object.

Parameters:

context - The transport context (the HttpServletRequest object in the case of the HTTP transport).

jsonReq - The JSON-RPC request structured as a JSON object tree.

Returns:

a JSONRPCResult object with the result of the invocation or an error.

getBridgeState

public JSONRPCBridgeState getBridgeState()

Get the JSONRPCBridgeState object associated with this bridge.

Returns:

the JSONRPCBridgeState object associated with this bridge.

getCallbackController

public CallbackController getCallbackController()

Get the CallbackController object associated with this bridge.

Returns:

the CallbackController object associated with this bridge.

getGlobalBridge

public static JSONRPCBridge getGlobalBridge()

This method retrieves 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.

getReferenceMap

public java.util.HashMap getReferenceMap()

Gets the map of referenced objects used by this bridge. The reference map contains objects of classes that have been registered as a Reference or CallableReference.

Returns:

a HashMap with the references currently in use on this bridge instance.

getSerializer

public static JSONSerializer getSerializer()

Get the global JSONSerializer object.

Returns:

the global JSONSerializer object.

isCallableReference

public boolean isCallableReference(java.lang.Class clazz)

Check whether a class is registered as a callable reference type.

Parameters:

clazz - The class object to check is a callable reference.

isReference

public boolean isReference(java.lang.Class clazz)

Check whether a class is registered as a reference type.

Parameters:

clazz - The class object to check is a reference.

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.Object 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.

Calling registerClass for a clazz again under the same name will have no effect.

To export instance methods you need to use registerObject.

Parameters:

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.

Calling registerObject for a name that already exists will replace the existing entry.

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 serializer)
                        throws java.lang.Exception

Register a new serializer on this bridge.

Parameters:

serializer - A class implementing the Serializer interface (usually derived from AbstractSerializer).

Throws:

java.lang.Exception

setBridgeState

public void setBridgeState(JSONRPCBridgeState state)

Set the JSONRPCBridgeState object for this bridge.

Parameters:

state - the JSONRPCBridgeState object to be set for this bridge.

setCallbackController

public void setCallbackController(CallbackController cbc)

Set the CallbackController object for this bridge.

Parameters:

cbc - the CallbackController object to be set for this bridge.

setDebug

public void setDebug(boolean debug)

Enable or disable debugging message from this bridge instance.

Parameters:

debug - flag to enable or disable debugging messages

setExceptionTransformer

public void setExceptionTransformer(ExceptionTransformer exceptionTransformer)

setSerializer

public static void setSerializer(JSONSerializer ser)

Set the global JSONSerializer object.

Parameters:

ser - the global JSONSerializer object.

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