com.isomorphic.rpc
Class RPCManager

java.lang.Object
  |
  +--com.isomorphic.rpc.RPCManager

public class RPCManager
extends java.lang.Object

Provides the ability to decode RPCRequests and DSRequests sent by the browser into Java Objects, and send back Java Object as responses.

This class has a client-side counterpart that is also called RPCManager. The client-side RPCManager enables you to send one or more RPCRequests to an arbitrary URL. In the Java logic at those URLs, you'll need to instantiate this RPCManager to process and respond to the requests.

Note that a single RPC transaction can contain more than one RPC request. See the discussion on queueing in the documentation for the client-side RPCManager on why this is useful.

All RPC requests require a response. If your application needs nothing more than an ack of the successful completion of a given request, use the sendSuccess()/sendFailure() convenience methods on this class to ack the request. The RPCManager keeps track of request/response pairs and automatically streams all responses to the client as a batch once you've provided a response for each request.

Note that when you call any of the send() methods on this class, no data is actually sent back over the wire until you have responded to all requests.

See Also:
RPCRequest, RPCResponse, Init

Constructor Summary
RPCManager(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          RPCManager constructor for use in Servlets or Filters.
RPCManager(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.io.Writer out)
          RPCManager constructor for use in JSPs.
 
Method Summary
 void doCustomResponse()
          If you're using Direct Method Invocation, you can call doCustomResponse() to suppress the normal RPCManager response so that you can send your own custom response via the servletResponse output stream.
 java.lang.Object getData()
          Convenience method for getting the data of a single RPCRequest.
 RPCRequest getRequest()
          Convenience method for getting a single RPCRequest when you know this HTTP request only contains one RPCRequest.
 java.util.List getRequests()
          Returns a list of RPC requests sent in this HTTP transaction.
static boolean isRPC(javax.servlet.http.HttpServletRequest request)
           
static boolean isXmlHttp(javax.servlet.http.HttpServletRequest request)
           
static void processRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Instantiates an RPCManager and invokes execute() on each RPCRequest or DSRequest in this HTTP request.
 int requestCount()
          Returns the number of RPC requests contained in the current HTTP request.
 void send(DSRequest dsRequest, DSResponse dsResponse)
          When responding to DataSource requests sent by the client, use this method.
 void send(DSRequest dsRequest, java.lang.Object data)
          Convenience method.
 void send(java.lang.Object data)
          Convenience method for sending some data back in response to a single RPCRequest.
 void send(RPCRequest rpcRequest, java.lang.Object data)
          Convenience method.
 void send(RPCRequest rpcRequest, RPCResponse rpcResponse)
          When responding to a set of RPC requests sent as part of one HTTP request (if you used startQueue() sendQueue() on the client) you need to pair the responses to the requests.
 void send(RPCResponse rpcResponse)
          Convenience method for sending some data back in response to a single RPCRequest.
 void sendFailure(java.lang.Object request, java.lang.String error)
          If the request processing failed for some reason, you can encode your own failure response in a standard response, or use this convenience method to send a failure notification on the client.

Unless your client-side request specified the willHandleError flag, whatever message you send back here will be alert()ed on the client.
 void sendFailure(java.lang.Object request, java.lang.Throwable t)
          Takes a Throwable, formats the stack trace and calls sendFailure(rpcRequst, error).
 void sendSuccess(RPCRequest rpcRequest)
          Every RPC request requires a response.
 void sendXMLString(DSRequest dsRequest, java.lang.String xml)
          Convenience method.
 void sendXMLString(RPCRequest rpcRequest, java.lang.String xml)
          Convenience method.
 void setResponseCharset(java.lang.String charset)
          Sets the charset of the response.
 

Constructor Detail

RPCManager

public RPCManager(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws java.lang.Exception
RPCManager constructor for use in Servlets or Filters.
Parameters:
request - The 'request' variable provided in the context of the JSP
response - The 'response' variable provided in the context of the JSP
Throws:
ClientMustResubmitException - if the client must resubmit the request.
java.lang.Exception - if the request is malformed.

RPCManager

public RPCManager(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response,
                  java.io.Writer out)
           throws java.lang.Exception
RPCManager constructor for use in JSPs. The RPC requires control of the output stream to send responses to the client. Since JSPs automatically call response.getOutputStream() to provide the 'out' variable in the context of the JSP and since it's further illegal to call getOutputStream() more than once, so you'll need to use this form of the RPCManager constructor when processing RPC requests in a JSP.
Parameters:
request - The 'request' variable provided in the context of the JSP
response - The 'response' variable provided in the context of the JSP
out - The 'out' variable provided in the context of the JSP
Throws:
ClientMustResubmitException - if the client must resubmit the request.
java.lang.Exception - if the request is malformed.
Method Detail

isRPC

public static boolean isRPC(javax.servlet.http.HttpServletRequest request)
Returns:
true if passed the HttpServletRequest contains a SmartClient RPC request, false otherwise.

isXmlHttp

public static boolean isXmlHttp(javax.servlet.http.HttpServletRequest request)
Returns:
true if if the current RPC request was made using the xmlHttpRequest transport, false otherwise.

doCustomResponse

public void doCustomResponse()
If you're using Direct Method Invocation, you can call doCustomResponse() to suppress the normal RPCManager response so that you can send your own custom response via the servletResponse output stream.

This is useful for implementing file download functionality in response to an RPC request.

Note if you are not using DMI, but simply using the RPCManager, you can avoid the RPCManager response by simply not calling RPCManager.send().


setResponseCharset

public void setResponseCharset(java.lang.String charset)
Sets the charset of the response. Must be called before any send() methods are called.

getData

public java.lang.Object getData()
Convenience method for getting the data of a single RPCRequest. Calling this method is equivalent to calling getRequest.getData()

getRequest

public RPCRequest getRequest()
Convenience method for getting a single RPCRequest when you know this HTTP request only contains one RPCRequest. If more than one RPC request was actually sent by the client, this method returns the first one and logs a warning.

getRequests

public java.util.List getRequests()
Returns a list of RPC requests sent in this HTTP transaction. The request objects in this list will be either of type RPCRequest (if you used RPCManager.send() on the client) or of type DSRequest if the request was generated by a databound component or datasource on the client or a mix of RPCRequest and DSRequest objects.

requestCount

public int requestCount()
Returns the number of RPC requests contained in the current HTTP request.
Returns:
number of RPC requests contained in the current HTTP request.

send

public void send(java.lang.Object data)
          throws java.lang.Exception
Convenience method for sending some data back in response to a single RPCRequest. Calling this method is equivalent to calling send(new RPCResponse(data))/
Parameters:
data - to send back
Throws:
java.lang.Exception - if there is an error sending the response

send

public void send(RPCResponse rpcResponse)
          throws java.lang.Exception
Convenience method for sending some data back in response to a single RPCRequest. If you're processing multiple RPC request sent as part of one HTTP request, you need to pair the responses to the requests by calling send(rpcRequest, rpcResponse) instead.
Parameters:
rpcResponse - containing the data to send back
Throws:
java.lang.Exception - if there is an error sending the response

send

public void send(RPCRequest rpcRequest,
                 RPCResponse rpcResponse)
          throws java.lang.Exception
When responding to a set of RPC requests sent as part of one HTTP request (if you used startQueue() sendQueue() on the client) you need to pair the responses to the requests.
Parameters:
rpcRequest - the request you're responding to
rpcResponse - your response
Throws:
java.lang.Exception - if there is an error sending the response

send

public void send(RPCRequest rpcRequest,
                 java.lang.Object data)
          throws java.lang.Exception
Convenience method. This method does the following:
 RPCResponse rpcResponse = new RPCResponse();
 rpcResponse.setData(data);
 rpcResponse.setStatus(RPCResponse.STATUS_SUCCESS);
 send(rpcRequest, rpcResponse);
 
Parameters:
rpcRequest - the request you're responding to
data - to send as the payload of the response
Throws:
java.lang.Exception - if there is an error sending the response

sendXMLString

public void sendXMLString(RPCRequest rpcRequest,
                          java.lang.String xml)
                   throws java.lang.Exception
Convenience method. Transforms the provided XML in a manner equivalent to the isomorphic:XML JSP tag (custom Isomorphic tag) and sets that as the payload of a new RPCResponse. Calling this method is equivalent to parsing the XML and passing the resulting top-level org.w3c.dom.Element object to RPCResponse.setData().
Throws:
java.lang.Exception - if there is an error sending the response

send

public void send(DSRequest dsRequest,
                 DSResponse dsResponse)
          throws java.lang.Exception
When responding to DataSource requests sent by the client, use this method.
Parameters:
dsRequest - the request you're responding to
dsRequest - your response
Throws:
java.lang.Exception - if there is an error sending the response

send

public void send(DSRequest dsRequest,
                 java.lang.Object data)
          throws java.lang.Exception
Convenience method. This method does the following:
 DSResponse dsResponse = new DSResponse();
 dsResponse.setData(data);
 dsResponse.setStatus(DSResponse.STATUS_SUCCESS);
 send(dsRequest, dsResponse);
 
Parameters:
dsRequest - the request you're responding to
data - to send as the payload of the response
Throws:
java.lang.Exception - if there is an error sending the response

sendXMLString

public void sendXMLString(DSRequest dsRequest,
                          java.lang.String xml)
                   throws java.lang.Exception
Convenience method. Transforms the provided XML in a manner equivalent to the isomorphic:XML JSP tag (custom Isomorphic tag) and sets that as the payload of a new DSResponse. Calling this method is equivalent to parsing the XML and passing the resulting top-level an org.w3c.dom.Element object to DSResponse.setData().
Throws:
java.lang.Exception - if there is an error sending the response

sendSuccess

public void sendSuccess(RPCRequest rpcRequest)
                 throws java.lang.Exception
Every RPC request requires a response. If your application does not require a response to a particular request, use this method to ack the successful completion of the request on the server.
Parameters:
rpcRequest - the request that completed successfully
Throws:
java.lang.Exception - if there is an error sending the response

sendFailure

public void sendFailure(java.lang.Object request,
                        java.lang.String error)
                 throws java.lang.Exception
If the request processing failed for some reason, you can encode your own failure response in a standard response, or use this convenience method to send a failure notification on the client.

Unless your client-side request specified the willHandleError flag, whatever message you send back here will be alert()ed on the client.
Parameters:
request - the request that failed
error - the error string to send to the client
Throws:
java.lang.Exception - if there is an error sending the response

sendFailure

public void sendFailure(java.lang.Object request,
                        java.lang.Throwable t)
                 throws java.lang.Exception
Takes a Throwable, formats the stack trace and calls sendFailure(rpcRequst, error).
Parameters:
request - the request that failed
t - the exception you wish to report to the client
Throws:
java.lang.Exception - if there is an error sending the response

processRequest

public static void processRequest(javax.servlet.http.HttpServletRequest request,
                                  javax.servlet.http.HttpServletResponse response)
                           throws javax.servlet.ServletException,
                                  java.io.IOException
Instantiates an RPCManager and invokes execute() on each RPCRequest or DSRequest in this HTTP request.
Parameters:
request - The HttpServletRequest
response - The HttpServletResponse
Throws:
javax.servlet.ServletException - As per HttpServlet.service()
java.io.IOException - As per HttpServlet.service()