public final class

RPC

extends Object
java.lang.Object
   ↳ com.google.gwt.user.server.rpc.RPC

Class Overview

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. {@example com.google.gwt.examples.rpc.server.CanonicalExample#processCall(String)}

Advanced Example

The following example shows a more advanced way of using this class to create an adapter between GWT RPC entities and POJOs. {@example com.google.gwt.examples.rpc.server.AdvancedExample#doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)}

Summary

Public Methods
static RPCRequest decodeRequest(String encodedRequest)
Returns an RPCRequest that is built by decoding the contents of an encoded RPC request.
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.
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.
static String encodeResponseForFailure(Method serviceMethod, Throwable cause)
Returns a string that encodes an exception.
static String encodeResponseForFailure(Method serviceMethod, Throwable cause, SerializationPolicy serializationPolicy)
Returns a string that encodes an exception.
static String encodeResponseForFailure(Method serviceMethod, Throwable cause, SerializationPolicy serializationPolicy, int flags)
static String encodeResponseForSuccess(Method serviceMethod, Object object)
Returns a string that encodes the object.
static String encodeResponseForSuccess(Method serviceMethod, Object object, SerializationPolicy serializationPolicy, int flags)
static String encodeResponseForSuccess(Method serviceMethod, Object object, SerializationPolicy serializationPolicy)
Returns a string that encodes the object.
static SerializationPolicy getDefaultSerializationPolicy()
Returns a default serialization policy.
static String invokeAndEncodeResponse(Object target, Method serviceMethod, Object[] args, SerializationPolicy 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.
static String invokeAndEncodeResponse(Object target, Method serviceMethod, Object[] args)
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.
static String invokeAndEncodeResponse(Object target, Method serviceMethod, Object[] args, SerializationPolicy serializationPolicy, int flags)
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

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
Returns
Throws
IncompatibleRemoteServiceException if any of the following conditions apply:
  • if the types in the encoded request cannot be deserialized
  • if the ClassLoader acquired from Thread.currentThread().getContextClassLoader() cannot load the service interface or any of the types specified in the encodedRequest
  • the requested interface is not assignable to RemoteService
  • the service method requested in the encodedRequest is not a member of the requested service interface
  • the type parameter is not null and is not assignable to the requested RemoteService interface

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
Returns
Throws
NullPointerException if the encodedRequest is null
IllegalArgumentException if the encodedRequest is an empty string
IncompatibleRemoteServiceException if any of the following conditions apply:
  • if the types in the encoded request cannot be deserialized
  • if the ClassLoader acquired from Thread.currentThread().getContextClassLoader() cannot load the service interface or any of the types specified in the encodedRequest
  • the requested interface is not assignable to RemoteService
  • the service method requested in the encodedRequest is not a member of the requested service interface
  • the type parameter is not null and is not assignable to the requested RemoteService interface

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.
Returns
Throws
NullPointerException if the encodedRequest is null
IllegalArgumentException if the encodedRequest is an empty string
IncompatibleRemoteServiceException if any of the following conditions apply:
  • if the types in the encoded request cannot be deserialized
  • if the ClassLoader acquired from Thread.currentThread().getContextClassLoader() cannot load the service interface or any of the types specified in the encodedRequest
  • the requested interface is not assignable to RemoteService
  • the service method requested in the encodedRequest is not a member of the requested service interface
  • the type parameter is not null and is not assignable to the requested RemoteService interface

public static String encodeResponseForFailure (Method serviceMethod, Throwable cause)

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
Returns
  • a string that encodes the exception
Throws
NullPointerException if the the cause is null
SerializationException if the result cannot be serialized
UnexpectedException if the result was an unexpected exception (a checked exception not declared in the serviceMethod's signature)

public static String encodeResponseForFailure (Method serviceMethod, Throwable cause, SerializationPolicy serializationPolicy)

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
Returns
  • a string that encodes the exception
Throws
NullPointerException if the the cause or the serializationPolicy are null
SerializationException if the result cannot be serialized
UnexpectedException if the result was an unexpected exception (a checked exception not declared in the serviceMethod's signature)

public static String encodeResponseForFailure (Method serviceMethod, Throwable cause, SerializationPolicy serializationPolicy, int flags)

Throws
SerializationException

public static String encodeResponseForSuccess (Method serviceMethod, Object object)

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
Returns
  • a string that encodes the object, if the object is compatible with the service method's declared return type
Throws
IllegalArgumentException if the result is not assignable to the service method's return type
NullPointerException if the service method is null
SerializationException if the result cannot be serialized

public static String encodeResponseForSuccess (Method serviceMethod, Object object, SerializationPolicy serializationPolicy, int flags)

Throws
SerializationException

public static String encodeResponseForSuccess (Method serviceMethod, Object object, SerializationPolicy serializationPolicy)

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
Returns
  • a string that encodes the object, if the object is compatible with the service method's declared return type
Throws
IllegalArgumentException if the result is not assignable to the service method's return type
NullPointerException if the serviceMethod or the serializationPolicy are null
SerializationException if the result cannot be serialized

public static SerializationPolicy getDefaultSerializationPolicy ()

Returns a default serialization policy.

Returns
  • the default serialization policy.

public static String invokeAndEncodeResponse (Object target, Method serviceMethod, Object[] args, SerializationPolicy 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.

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
Returns
  • a string which encodes either the method's return or a checked exception thrown by the method
Throws
NullPointerException if the serviceMethod or the serializationPolicy are null
SecurityException if the method cannot be accessed or if the number or type of actual and formal arguments differ
SerializationException if an object could not be serialized by the stream
UnexpectedException if the serviceMethod throws a checked exception that is not declared in its signature

public static String invokeAndEncodeResponse (Object target, Method serviceMethod, Object[] args)

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
Returns
  • a string which encodes either the method's return or a checked exception thrown by the method
Throws
SecurityException if the method cannot be accessed or if the number or type of actual and formal arguments differ
SerializationException if an object could not be serialized by the stream
UnexpectedException if the serviceMethod throws a checked exception that is not declared in its signature

public static String invokeAndEncodeResponse (Object target, Method serviceMethod, Object[] args, SerializationPolicy serializationPolicy, int flags)

Throws
SerializationException