Google Web Toolkit
Search Google Code:

# Class RPC

public final class RPC
extends Object
Utility class for integrating with the RPC system. This class exposes methods for decoding of RPC requests, encoding of RPC responses, and invocation of RPC calls on service objects. The operations exposed by this class can be reused by framework implementors such as Spring and G4jsf to support a wide range of service invocation policies.

### Canonical Example

The following example demonstrates the canonical way to use this class.

    public String processCall(String payload) throws SerializationException {
      try {
        RPCRequest rpcRequest = RPC.decodeRequest(payload, this.getClass());
        return RPC.invokeAndEncodeResponse(this, rpcRequest.getMethod(),
            rpcRequest.getParameters());
      } catch (IncompatibleRemoteServiceException ex) {
        return RPC.encodeResponseForFailure(null, ex);
      }
    }

### Advanced Example

The following example shows a more advanced way of using this class to create an adapter between GWT RPC entities and POJOs.

    public void doPost(HttpServletRequest httpRequest,
        HttpServletResponse httpResponse) {
      String payload = readPayloadAsUtf8(httpRequest);

      try {
        try {
          RPCRequest rpcRequest = RPC.decodeRequest(payload);

          Object targetInstance = getInstanceToHandleRequest(httpRequest,
              rpcRequest);

          Method targetMethod = maybeMapRequestedMethod(targetInstance,
              rpcRequest.getMethod());

          Object[] targetParameters = maybeMapParameters(rpcRequest.getParameters());

          try {
            Object result = targetMethod.invoke(targetInstance, targetParameters);

            result = maybeMapResult(rpcRequest.getMethod(), result);

            /*
             * Encode the object that will be given to the client code's
             * AsyncCallback::onSuccess(Object) method.
             */
            String encodedResult = RPC.encodeResponseForSuccess(
                rpcRequest.getMethod(), result);

            sendResponseForSuccess(httpResponse, encodedResult);
          } catch (IllegalArgumentException e) {
            SecurityException securityException = new SecurityException(
                "Blocked attempt to invoke method " + targetMethod);
            securityException.initCause(e);
            throw securityException;
          } catch (IllegalAccessException e) {
            SecurityException securityException = new SecurityException(
                "Blocked attempt to access inaccessible method "
                    + targetMethod
                    + (targetInstance != null ? " on target " + targetInstance
                        : ""));
            securityException.initCause(e);
            throw securityException;
          } catch (InvocationTargetException e) {
            Throwable cause = e.getCause();

            Throwable mappedThrowable = maybeMapThrowable(cause,
                rpcRequest.getMethod());

            /*
             * Encode the exception that will be passed back to the client's
             * client code's AsyncCallback::onFailure(Throwable) method.
             */
            String failurePayload = RPC.encodeResponseForFailure(
                rpcRequest.getMethod(), mappedThrowable);

            sendResponseForFailure(httpResponse, failurePayload);
          }
        } catch (IncompatibleRemoteServiceException e) {
          sendResponseForFailure(httpResponse, RPC.encodeResponseForFailure(null,
              e));
        }
      } catch (Throwable e) {
        /*
         * Return a generic error which will be passed to the client code's
         * AsyncCallback::onFailure(Throwable) method.
         */
        sendResponseForGenericFailure(httpResponse);
      }
    }

## Methods

decodeRequest(String) | Returns an RPCRequest that is built by decoding the contents of an encoded RPC request.
decodeRequest(String, Class) | Returns an RPCRequest that is built by decoding the contents of an encoded RPC request and optionally validating that type can handle the request.
decodeRequest(String, Class, SerializationPolicyProvider) | Returns an RPCRequest that is built by decoding the contents of an encoded RPC request and optionally validating that type can handle the request.
encodeResponseForFailure(Method, Throwable) | Returns a string that encodes an exception.
encodeResponseForFailure(Method, Throwable, SerializationPolicy) | Returns a string that encodes an exception.
encodeResponseForSuccess(Method, Object) | Returns a string that encodes the object.
encodeResponseForSuccess(Method, Object, SerializationPolicy) | Returns a string that encodes the object.
getDefaultSerializationPolicy() | Returns a default serialization policy.
invokeAndEncodeResponse(Object, Method, Object[]) | Returns a string that encodes the result of calling a service method, which could be the value returned by the method or an exception thrown by it.
invokeAndEncodeResponse(Object, Method, Object[], SerializationPolicy) | Returns a string that encodes the result of calling a service method, which could be the value returned by the method or an exception thrown by it.

## Method Detail

### decodeRequest

public static RPCRequest decodeRequest(String encodedRequest)
Returns an RPCRequest that is built by decoding the contents of an encoded RPC request.

This method is equivalent to calling decodeRequest(String, Class) with `null` for the type parameter.

#### Parameters

encodedRequest
  a string that encodes the RemoteService interface, the service method to call, and the arguments to for the service method

#### Return Value

an RPCRequest instance

### decodeRequest

public static RPCRequest decodeRequest(String encodedRequest, Class type)
Returns an RPCRequest that is built by decoding the contents of an encoded RPC request and optionally validating that type can handle the request. If the type parameter is not `null`, the implementation checks that the type is assignable to the RemoteService interface requested in the encoded request string.

Invoking this method with `null` for the type parameter, `decodeRequest(encodedRequest, null)`, is equivalent to calling `decodeRequest(encodedRequest)`.

#### Parameters

encodedRequest
  a string that encodes the RemoteService interface, the service method, and the arguments to pass to the service method
type
  if not `null`, the implementation checks that the type is assignable to the RemoteService interface encoded in the encoded request string.

#### Return Value

an RPCRequest instance

### decodeRequest

public static RPCRequest decodeRequest(String encodedRequest, Class type, SerializationPolicyProvider serializationPolicyProvider)
Returns an RPCRequest that is built by decoding the contents of an encoded RPC request and optionally validating that type can handle the request. If the type parameter is not `null`, the implementation checks that the type is assignable to the RemoteService interface requested in the encoded request string.

If the serializationPolicyProvider parameter is not `null`, it is asked for a SerializationPolicy to use to restrict the set of types that can be decoded from the request. If this parameter is `null`, then only subtypes of IsSerializable or types which have custom field serializers can be decoded.

Invoking this method with `null` for the type parameter, `decodeRequest(encodedRequest, null)`, is equivalent to calling `decodeRequest(encodedRequest)`.

#### Parameters

encodedRequest
  a string that encodes the RemoteService interface, the service method, and the arguments to pass to the service method
type
  if not `null`, the implementation checks that the type is assignable to the RemoteService interface encoded in the encoded request string.
serializationPolicyProvider
  if not `null`, the implementation asks this provider for a SerializationPolicy which will be used to restrict the set of types that can be decoded from this request

#### Return Value

an RPCRequest instance

### encodeResponseForFailure

public static String encodeResponseForFailure(Method serviceMethod, Throwable cause)
throws SerializationException
Returns a string that encodes an exception. If method is not `null`, it is an error if the exception is not in the method's list of checked exceptions.

#### Parameters

serviceMethod
  the method that threw the exception, may be `null`
cause
  the Throwable that was thrown

#### Return Value

a string that encodes the exception

### encodeResponseForFailure

public static String encodeResponseForFailure(Method serviceMethod, Throwable cause, SerializationPolicy serializationPolicy)
throws SerializationException
Returns a string that encodes an exception. If method is not `null`, it is an error if the exception is not in the method's list of checked exceptions.

If the serializationPolicy parameter is not `null`, it is used to determine what types can be encoded as part of this response. If this parameter is `null`, then only subtypes of IsSerializable or types which have custom field serializers may be encoded.

#### Parameters

serviceMethod
  the method that threw the exception, may be `null`
cause
  the Throwable that was thrown
serializationPolicy
  determines the serialization policy to be used

#### Return Value

a string that encodes the exception

### encodeResponseForSuccess

public static String encodeResponseForSuccess(Method serviceMethod, Object object)
throws SerializationException
Returns a string that encodes the object. It is an error to try to encode an object that is not assignable to the service method's return type.

#### Parameters

serviceMethod
  the method whose result we are encoding
object
  the instance that we wish to encode

#### Return Value

a string that encodes the object, if the object is compatible with the service method's declared return type

### encodeResponseForSuccess

public static String encodeResponseForSuccess(Method serviceMethod, Object object, SerializationPolicy serializationPolicy)
throws SerializationException
Returns a string that encodes the object. It is an error to try to encode an object that is not assignable to the service method's return type.

If the serializationPolicy parameter is not `null`, it is used to determine what types can be encoded as part of this response. If this parameter is `null`, then only subtypes of IsSerializable or types which have custom field serializers may be encoded.

#### Parameters

serviceMethod
  the method whose result we are encoding
object
  the instance that we wish to encode
serializationPolicy
  determines the serialization policy to be used

#### Return Value

a string that encodes the object, if the object is compatible with the service method's declared return type

### getDefaultSerializationPolicy

public static SerializationPolicy getDefaultSerializationPolicy()
Returns a default serialization policy.

#### Return Value

the default serialization policy.

### invokeAndEncodeResponse

public static String invokeAndEncodeResponse(Object target, Method serviceMethod, Object[] args)
throws SerializationException
Returns a string that encodes the result of calling a service method, which could be the value returned by the method or an exception thrown by it.

This method does no security checking; security checking must be done on the method prior to this invocation.

#### Parameters

target
  instance on which to invoke the serviceMethod
serviceMethod
  the method to invoke
args
  arguments used for the method invocation

#### Return Value

a string which encodes either the method's return or a checked exception thrown by the method

### invokeAndEncodeResponse

public static String invokeAndEncodeResponse(Object target, Method serviceMethod, Object[] args, SerializationPolicy serializationPolicy)
throws SerializationException
Returns a string that encodes the result of calling a service method, which could be the value returned by the method or an exception thrown by it.

If the serializationPolicy parameter is not `null`, it is used to determine what types can be encoded as part of this response. If this parameter is `null`, then only subtypes of IsSerializable or types which have custom field serializers may be encoded.

This method does no security checking; security checking must be done on the method prior to this invocation.

#### Parameters

target
  instance on which to invoke the serviceMethod
serviceMethod
  the method to invoke
args
  arguments used for the method invocation
serializationPolicy
  determines the serialization policy to be used

#### Return Value

a string which encodes either the method's return or a checked exception thrown by the method