com.google.gwt.user.server.rpc

## Class RPC

- java.lang.Object
- - com.google.gwt.user.server.rpc.RPC

-     public final class RPC
      extends java.lang.Object

- - ### Method Summary

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

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### decodeRequest

          public static RPCRequest decodeRequest(java.lang.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:
        an `RPCRequest` instance
      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

    - #### decodeRequest

          public static RPCRequest decodeRequest(java.lang.String encodedRequest,
                                 java.lang.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:
        an `RPCRequest` instance
      Throws:
        `java.lang.NullPointerException` - if the encodedRequest is `null`
        `java.lang.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

    - #### decodeRequest

          public static RPCRequest decodeRequest(java.lang.String encodedRequest,
                                 java.lang.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:
        an `RPCRequest` instance
      Throws:
        `java.lang.NullPointerException` - if the encodedRequest is `null`
        `java.lang.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

    - #### encodeResponseForFailure

          public static java.lang.String encodeResponseForFailure(java.lang.reflect.Method serviceMethod,
                                                  java.lang.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
      Returns:
        a string that encodes the exception
      Throws:
        `java.lang.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)

    - #### encodeResponseForFailure

          public static java.lang.String encodeResponseForFailure(java.lang.reflect.Method serviceMethod,
                                                  java.lang.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
      Returns:
        a string that encodes the exception
      Throws:
        `java.lang.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)

    - #### encodeResponseForFailure

          public static java.lang.String encodeResponseForFailure(java.lang.reflect.Method serviceMethod,
                                                  java.lang.Throwable cause,
                                                  SerializationPolicy serializationPolicy,
                                                  int flags)
                                                           throws SerializationException

      Throws:
        `SerializationException`

    - #### encodeResponseForSuccess

          public static java.lang.String encodeResponseForSuccess(java.lang.reflect.Method serviceMethod,
                                                  java.lang.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
      Returns:
        a string that encodes the object, if the object is compatible with the service method's declared return type
      Throws:
        `java.lang.IllegalArgumentException` - if the result is not assignable to the service method's return type
        `java.lang.NullPointerException` - if the service method is `null`
        `SerializationException` - if the result cannot be serialized

    - #### encodeResponseForSuccess

          public static java.lang.String encodeResponseForSuccess(java.lang.reflect.Method serviceMethod,
                                                  java.lang.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
      Returns:
        a string that encodes the object, if the object is compatible with the service method's declared return type
      Throws:
        `java.lang.IllegalArgumentException` - if the result is not assignable to the service method's return type
        `java.lang.NullPointerException` - if the serviceMethod or the serializationPolicy are `null`
        `SerializationException` - if the result cannot be serialized

    - #### encodeResponseForSuccess

          public static java.lang.String encodeResponseForSuccess(java.lang.reflect.Method serviceMethod,
                                                  java.lang.Object object,
                                                  SerializationPolicy serializationPolicy,
                                                  int flags)
                                                           throws SerializationException

      Throws:
        `SerializationException`

    - #### getDefaultSerializationPolicy

          public static SerializationPolicy getDefaultSerializationPolicy()

      Returns a default serialization policy.
      Returns:
        the default serialization policy.

    - #### invokeAndEncodeResponse

          public static java.lang.String invokeAndEncodeResponse(java.lang.Object target,
                                                 java.lang.reflect.Method serviceMethod,
                                                 java.lang.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
      Returns:
        a string which encodes either the method's return or a checked exception thrown by the method
      Throws:
        `java.lang.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

    - #### invokeAndEncodeResponse

          public static java.lang.String invokeAndEncodeResponse(java.lang.Object target,
                                                 java.lang.reflect.Method serviceMethod,
                                                 java.lang.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
      Returns:
        a string which encodes either the method's return or a checked exception thrown by the method
      Throws:
        `java.lang.NullPointerException` - if the serviceMethod or the serializationPolicy are `null`
        `java.lang.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

    - #### invokeAndEncodeResponse

          public static java.lang.String invokeAndEncodeResponse(java.lang.Object target,
                                                 java.lang.reflect.Method serviceMethod,
                                                 java.lang.Object[] args,
                                                 SerializationPolicy serializationPolicy,
                                                 int flags)
                                                          throws SerializationException

      Throws:
        `SerializationException`