com.google.web.bindery.requestfactory.server

## Class ServiceLayerDecorator

- java.lang.Object
- - com.google.web.bindery.requestfactory.server.ServiceLayer
  - - com.google.web.bindery.requestfactory.server.ServiceLayerDecorator

- Direct Known Subclasses:
    FindServiceLayer, LocatorServiceLayer, ReflectiveServiceLayer, ResolverServiceLayer, ServiceLayerCache

      public class ServiceLayerDecorator
      extends ServiceLayer

  Users that intend to alter how RequestFactory interacts with the domain environment can extend this type and provide it to `ServiceLayer.create(ServiceLayerDecorator...)`. The methods defined in this type will automatically delegate to the next decorator or the root service object after being processed by`create()`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) ServiceLayer` | `next` A pointer to the next deepest layer.

    - ### Fields inherited from class com.google.web.bindery.requestfactory.server.ServiceLayer

      `top`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ServiceLayerDecorator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> T` | `createDomainObject(java.lang.Class<T> clazz)` Create an instance of the requested domain type.
    `<T extends Locator<?,?>> T` | `createLocator(java.lang.Class<T> clazz)` Create an instance of the requested `Locator` type.
    `java.lang.Object` | `createServiceInstance(java.lang.Class<? extends RequestContext> requestContext)` Create an instance of a service object that can be used as the target for the given method invocation.
    `<T extends ServiceLocator> T` | `createServiceLocator(java.lang.Class<T> clazz)` Create an instance of the requested `ServiceLocator` type.
    `protected <T> T` | `die(java.lang.Throwable e, java.lang.String message, java.lang.Object... args)` Throw a fatal error up into the top-level processing code.
    `java.lang.ClassLoader` | `getDomainClassLoader()` Returns the ClassLoader that should be used when attempting to access domain classes or resources.
    `java.lang.reflect.Method` | `getGetter(java.lang.Class<?> domainType, java.lang.String property)` Determine the method to invoke when retrieving the given property.
    `java.lang.Object` | `getId(java.lang.Object domainObject)` Return the persistent id for a domain object.
    `java.lang.Class<?>` | `getIdType(java.lang.Class<?> domainType)` Returns the type of object the domain type's `findFoo()` or `Locator.getId()` expects to receive.
    `(package private) ServiceLayer` | `getNext()` Retrieves the next service layer.
    `java.lang.Object` | `getProperty(java.lang.Object domainObject, java.lang.String property)` Retrieve the named property from the domain object.
    `java.lang.reflect.Type` | `getRequestReturnType(java.lang.reflect.Method contextMethod)` Compute the return type for a method declared in a RequestContext by analyzing the generic method declaration.
    `java.lang.reflect.Method` | `getSetter(java.lang.Class<?> domainType, java.lang.String property)` Determine the method to invoke when setting the given property.
    `protected ServiceLayer` | `getTop()` Returns the top-most service layer.
    `java.lang.Object` | `getVersion(java.lang.Object domainObject)` May return `null` to indicate that the domain object has not been persisted.
    `java.lang.Object` | `invoke(java.lang.reflect.Method domainMethod, java.lang.Object... args)` Invoke a domain service method.
    `boolean` | `isLive(java.lang.Object domainObject)` Returns `true` if the given domain object is still live (i.e.
    `<T> T` | `loadDomainObject(java.lang.Class<T> clazz, java.lang.Object domainId)` Load an object from the backing store.
    `java.util.List<java.lang.Object>` | `loadDomainObjects(java.util.List<java.lang.Class<?>> classes, java.util.List<java.lang.Object> domainIds)` Load multiple objects from the backing store.
    `protected <T> T` | `report(java.lang.reflect.InvocationTargetException userGeneratedException)` Report an exception thrown by code that is under the control of the end-developer.
    `protected <T> T` | `report(java.lang.String msg, java.lang.Object... args)` Return a message to the client.
    `boolean` | `requiresServiceLocator(java.lang.reflect.Method contextMethod, java.lang.reflect.Method domainMethod)` Determines if the invocation of a domain method requires a `ServiceLocator` as the 0th parameter when passed into `ServiceLayer.invoke(Method, Object...)`.
    `java.lang.Class<? extends BaseProxy>` | `resolveClass(java.lang.String typeToken)` Given a type token previously returned from `ServiceLayer.resolveTypeToken(Class)`, return the Class literal associated with the token.
    `<T> java.lang.Class<? extends T>` | `resolveClientType(java.lang.Class<?> domainClass, java.lang.Class<T> clientType, boolean required)` Determine the type used by the client code to represent a given domain type.
    `java.lang.Class<?>` | `resolveDomainClass(java.lang.Class<?> clazz)` Determine the domain (server-side) type that the given client type is mapped to.
    `java.lang.reflect.Method` | `resolveDomainMethod(java.lang.String operation)` Return the domain service method associated with a RequestContext method declaration.
    `java.lang.Class<? extends Locator<?,?>>` | `resolveLocator(java.lang.Class<?> domainType)` Return the type of `Locator` that should be used to access the given domain type.
    `java.lang.Class<? extends RequestContext>` | `resolveRequestContext(java.lang.String operation)` Find a RequestContext that should be used to fulfill the requested operation.
    `java.lang.reflect.Method` | `resolveRequestContextMethod(java.lang.String operation)` Find a RequestContext method declaration by name.
    `java.lang.Class<? extends RequestFactory>` | `resolveRequestFactory(java.lang.String binaryName)` Loads and validates a RequestFactory interface.
    `java.lang.Class<?>` | `resolveServiceClass(java.lang.Class<? extends RequestContext> requestContextClass)` Given a `RequestContext` method, find the service class referenced in the `Service` or `ServiceName` annotation.
    `java.lang.Class<? extends ServiceLocator>` | `resolveServiceLocator(java.lang.Class<? extends RequestContext> requestContext)` Given a RequestContext method declaration, resolve the `ServiceLocator` that should be used when invoking the domain method.
    `java.lang.String` | `resolveTypeToken(java.lang.Class<? extends BaseProxy> proxyType)` Return a string used to represent the given type in the wire protocol.
    `void` | `setProperty(java.lang.Object domainObject, java.lang.String property, java.lang.Class<?> expectedType, java.lang.Object value)` Sets a property on a domain object.
    `<T> java.util.Set<ConstraintViolation<T>>` | `validate(T domainObject)` Invoke a JSR 303 validator on the given domain object.

    - ### Methods inherited from class com.google.web.bindery.requestfactory.server.ServiceLayer

      `create`

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

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

- - ### Field Detail

    - #### next

          ServiceLayer next

      A pointer to the next deepest layer.

  - ### Constructor Detail

    - #### ServiceLayerDecorator

          public ServiceLayerDecorator()

  - ### Method Detail

    - #### createDomainObject

          public <T> T createDomainObject(java.lang.Class<T> clazz)

      Description copied from class: `ServiceLayer`
      Create an instance of the requested domain type.
      Specified by:
        `createDomainObject` in class `ServiceLayer`
      Type Parameters:
        `T` - the requested domain type
      Parameters:
        `clazz` - the requested domain type
      Returns:
        an instance of the requested domain type

    - #### createLocator

          public <T extends Locator<?,?>> T createLocator(java.lang.Class<T> clazz)

      Description copied from class: `ServiceLayer`
      Create an instance of the requested `Locator` type.
      Specified by:
        `createLocator` in class `ServiceLayer`
      Type Parameters:
        `T` - the requested Locator type
      Parameters:
        `clazz` - the requested Locator type
      Returns:
        an instance of the requested Locator type

    - #### createServiceInstance

          public java.lang.Object createServiceInstance(java.lang.Class<? extends RequestContext> requestContext)

      Description copied from class: `ServiceLayer`
      Create an instance of a service object that can be used as the target for the given method invocation.
      Specified by:
        `createServiceInstance` in class `ServiceLayer`
      Parameters:
        `requestContext` - the RequestContext type for which a service object must be instantiated.
      Returns:
        an instance of the requested service object

    - #### createServiceLocator

          public <T extends ServiceLocator> T createServiceLocator(java.lang.Class<T> clazz)

      Description copied from class: `ServiceLayer`
      Create an instance of the requested `ServiceLocator` type.
      Specified by:
        `createServiceLocator` in class `ServiceLayer`
      Type Parameters:
        `T` - the requested ServiceLocator type
      Parameters:
        `clazz` - the requested ServiceLocator type
      Returns:
        an instance of the requested ServiceLocator type

    - #### getDomainClassLoader

          public java.lang.ClassLoader getDomainClassLoader()

      Description copied from class: `ServiceLayer`
      Returns the ClassLoader that should be used when attempting to access domain classes or resources.

      The default implementation returns `Thread.currentThread().getContextClassLoader()`.

      Specified by:
        `getDomainClassLoader` in class `ServiceLayer`

    - #### getGetter

          public java.lang.reflect.Method getGetter(java.lang.Class<?> domainType,
                                           java.lang.String property)

      Description copied from class: `ServiceLayer`
      Determine the method to invoke when retrieving the given property.
      Specified by:
        `getGetter` in class `ServiceLayer`
      Parameters:
        `domainType` - a domain entity type
        `property` - the name of the property to be retrieved
      Returns:
        the Method that should be invoked to retrieve the property or `null` if the method could not be located

    - #### getId

          public java.lang.Object getId(java.lang.Object domainObject)

      Description copied from class: `ServiceLayer`
      Return the persistent id for a domain object. May return `null` to indicate that the domain object has not been persisted. The value returned from this method must be a simple type (e.g. Integer, String) or a domain type for which a mapping to an EntityProxy or Value proxy exists.

      The values returned from this method may be passed to `ServiceLayer.loadDomainObject(Class, Object)` in the future.

      Specified by:
        `getId` in class `ServiceLayer`
      Parameters:
        `domainObject` - a domain object
      Returns:
        the persistent id of the domain object or `null` if the object is not persistent

    - #### getIdType

          public java.lang.Class<?> getIdType(java.lang.Class<?> domainType)

      Description copied from class: `ServiceLayer`
      Returns the type of object the domain type's `findFoo()` or `Locator.getId()` expects to receive.
      Specified by:
        `getIdType` in class `ServiceLayer`
      Parameters:
        `domainType` - a domain entity type
      Returns:
        the type of the persistent id value used to represent the domain type

    - #### getProperty

          public java.lang.Object getProperty(java.lang.Object domainObject,
                                     java.lang.String property)

      Description copied from class: `ServiceLayer`
      Retrieve the named property from the domain object.
      Specified by:
        `getProperty` in class `ServiceLayer`
      Parameters:
        `domainObject` - the domain object being examined
        `property` - the property name
      Returns:
        the value of the property

    - #### getRequestReturnType

          public java.lang.reflect.Type getRequestReturnType(java.lang.reflect.Method contextMethod)

      Description copied from class: `ServiceLayer`
      Compute the return type for a method declared in a RequestContext by analyzing the generic method declaration.
      Specified by:
        `getRequestReturnType` in class `ServiceLayer`

    - #### getSetter

          public java.lang.reflect.Method getSetter(java.lang.Class<?> domainType,
                                           java.lang.String property)

      Description copied from class: `ServiceLayer`
      Determine the method to invoke when setting the given property.
      Specified by:
        `getSetter` in class `ServiceLayer`
      Parameters:
        `domainType` - a domain entity type
        `property` - the name of the property to be set
      Returns:
        the Method that should be invoked to set the property or `null` if the method could not be located

    - #### getVersion

          public java.lang.Object getVersion(java.lang.Object domainObject)

      Description copied from class: `ServiceLayer`
      May return `null` to indicate that the domain object has not been persisted. The value returned from this method must be a simple type (e.g. Integer, String) or a domain type for which a mapping to an EntityProxy or Value proxy exists.
      Specified by:
        `getVersion` in class `ServiceLayer`
      Parameters:
        `domainObject` - a domain object
      Returns:
        the version of the domain object or `null` if the object is not persistent

    - #### invoke

          public java.lang.Object invoke(java.lang.reflect.Method domainMethod,
                                java.lang.Object... args)

      Description copied from class: `ServiceLayer`
      Invoke a domain service method. The underlying eventually calls `Method.invoke(Object, Object...)`.
      Specified by:
        `invoke` in class `ServiceLayer`
      Parameters:
        `domainMethod` - the method to invoke
        `args` - the arguments to pass to the method
      Returns:
        the value returned from the method invocation

    - #### isLive

          public boolean isLive(java.lang.Object domainObject)

      Description copied from class: `ServiceLayer`
      Returns `true` if the given domain object is still live (i.e. not deleted) in the backing store.
      Specified by:
        `isLive` in class `ServiceLayer`
      Parameters:
        `domainObject` - a domain entity
      Returns:
        `true` if `domainObject` could be retrieved at a later point in time

    - #### loadDomainObject

          public <T> T loadDomainObject(java.lang.Class<T> clazz,
                               java.lang.Object domainId)

      Description copied from class: `ServiceLayer`
      Load an object from the backing store. This method may return `null` to indicate that the requested object is no longer available.
      Specified by:
        `loadDomainObject` in class `ServiceLayer`
      Type Parameters:
        `T` - the type of object to load
      Parameters:
        `clazz` - the type of object to load
        `domainId` - an id previously returned from `ServiceLayer.getId(Object)`
      Returns:
        the requested object or `null` if it is irretrievable

    - #### loadDomainObjects

          public java.util.List<java.lang.Object> loadDomainObjects(java.util.List<java.lang.Class<?>> classes,
                                                           java.util.List<java.lang.Object> domainIds)

      Description copied from class: `ServiceLayer`
      Load multiple objects from the backing store. This method is intended to allow more efficient access to the backing store by providing all objects referenced in an incoming payload.

      The default implementation of this method will delegate to `ServiceLayer.loadDomainObject(Class, Object)`.

      Specified by:
        `loadDomainObjects` in class `ServiceLayer`
      Parameters:
        `classes` - type type of each object to load
        `domainIds` - the ids previously returned from `ServiceLayer.getId(Object)`
      Returns:
        the requested objects, elements of which may be `null` if the requested objects were irretrievable

    - #### requiresServiceLocator

          public boolean requiresServiceLocator(java.lang.reflect.Method contextMethod,
                                       java.lang.reflect.Method domainMethod)

      Description copied from class: `ServiceLayer`
      Determines if the invocation of a domain method requires a `ServiceLocator` as the 0th parameter when passed into `ServiceLayer.invoke(Method, Object...)`.
      Specified by:
        `requiresServiceLocator` in class `ServiceLayer`
      Parameters:
        `contextMethod` - a method defined in a RequestContext
        `domainMethod` - a domain method
      Returns:
        `true` if a ServiceLocator is required

    - #### resolveClass

          public java.lang.Class<? extends BaseProxy> resolveClass(java.lang.String typeToken)

      Description copied from class: `ServiceLayer`
      Given a type token previously returned from `ServiceLayer.resolveTypeToken(Class)`, return the Class literal associated with the token.
      Specified by:
        `resolveClass` in class `ServiceLayer`
      Parameters:
        `typeToken` - a string token
      Returns:
        the type represented by the token

    - #### resolveClientType

          public <T> java.lang.Class<? extends T> resolveClientType(java.lang.Class<?> domainClass,
                                                           java.lang.Class<T> clientType,
                                                           boolean required)

      Description copied from class: `ServiceLayer`
      Determine the type used by the client code to represent a given domain type. If multiple proxy types have been mapped to the same domain type, the `clientType` parameter is used to ensure assignability.
      Specified by:
        `resolveClientType` in class `ServiceLayer`
      Parameters:
        `domainClass` - the server-side type to be transported to the client
        `clientType` - the type to which the returned type must be assignable
        `required` - if `true` and no mapping is available, throw an exception, otherwise the method will return `null`
      Returns:
        a class that represents `domainClass` on the client which is assignable to `clientType`

    - #### resolveDomainClass

          public java.lang.Class<?> resolveDomainClass(java.lang.Class<?> clazz)

      Description copied from class: `ServiceLayer`
      Determine the domain (server-side) type that the given client type is mapped to.
      Specified by:
        `resolveDomainClass` in class `ServiceLayer`
      Parameters:
        `clazz` - a client-side type
      Returns:
        the domain type that `clientType` represents

    - #### resolveDomainMethod

          public java.lang.reflect.Method resolveDomainMethod(java.lang.String operation)

      Description copied from class: `ServiceLayer`
      Return the domain service method associated with a RequestContext method declaration. The `requestContextMethod` will have been previously resolved by `#resolveRequestContextMethod(String, String)`.
      Specified by:
        `resolveDomainMethod` in class `ServiceLayer`
      Returns:
        the domain service method that should be invoked

    - #### resolveLocator

          public java.lang.Class<? extends Locator<?,?>> resolveLocator(java.lang.Class<?> domainType)

      Description copied from class: `ServiceLayer`
      Return the type of `Locator` that should be used to access the given domain type.
      Specified by:
        `resolveLocator` in class `ServiceLayer`
      Parameters:
        `domainType` - a domain (server-side) type
      Returns:
        the type of Locator to use, or `null` if the type conforms to the RequestFactory entity protocol

    - #### resolveRequestContext

          public java.lang.Class<? extends RequestContext> resolveRequestContext(java.lang.String operation)

      Description copied from class: `ServiceLayer`
      Find a RequestContext that should be used to fulfill the requested operation.
      Specified by:
        `resolveRequestContext` in class `ServiceLayer`
      Parameters:
        `operation` - the operation
      Returns:
        the RequestContext or `null` if no RequestContext exists that can fulfill the operation

    - #### resolveRequestContextMethod

          public java.lang.reflect.Method resolveRequestContextMethod(java.lang.String operation)

      Description copied from class: `ServiceLayer`
      Find a RequestContext method declaration by name.
      Specified by:
        `resolveRequestContextMethod` in class `ServiceLayer`
      Parameters:
        `operation` - the operation's name
      Returns:
        the method declaration, or `null` if the method does not exist

    - #### resolveRequestFactory

          public java.lang.Class<? extends RequestFactory> resolveRequestFactory(java.lang.String binaryName)

      Description copied from class: `ServiceLayer`
      Loads and validates a RequestFactory interface.
      Specified by:
        `resolveRequestFactory` in class `ServiceLayer`
      Parameters:
        `binaryName` - the RequestFactory's type token (usually the type's binary name)
      Returns:
        the RequestFactory type

    - #### resolveServiceClass

          public java.lang.Class<?> resolveServiceClass(java.lang.Class<? extends RequestContext> requestContextClass)

      Description copied from class: `ServiceLayer`
      Given a `RequestContext` method, find the service class referenced in the `Service` or `ServiceName` annotation.
      Specified by:
        `resolveServiceClass` in class `ServiceLayer`
      Parameters:
        `requestContextClass` - a RequestContext interface
      Returns:
        the type of service to use

    - #### resolveServiceLocator

          public java.lang.Class<? extends ServiceLocator> resolveServiceLocator(java.lang.Class<? extends RequestContext> requestContext)

      Description copied from class: `ServiceLayer`
      Given a RequestContext method declaration, resolve the `ServiceLocator` that should be used when invoking the domain method. This method will only be called if `ServiceLayer.requiresServiceLocator(Method, Method)` returned `true` for the associated domain method.
      Specified by:
        `resolveServiceLocator` in class `ServiceLayer`
      Parameters:
        `requestContext` - the RequestContext for which a ServiceLocator must be located
      Returns:
        the type of ServiceLocator to use

    - #### resolveTypeToken

          public java.lang.String resolveTypeToken(java.lang.Class<? extends BaseProxy> proxyType)

      Description copied from class: `ServiceLayer`
      Return a string used to represent the given type in the wire protocol.
      Specified by:
        `resolveTypeToken` in class `ServiceLayer`
      Parameters:
        `proxyType` - a client-side EntityProxy or ValueProxy type
      Returns:
        the type token used to represent the proxy type

    - #### setProperty

          public void setProperty(java.lang.Object domainObject,
                         java.lang.String property,
                         java.lang.Class<?> expectedType,
                         java.lang.Object value)

      Description copied from class: `ServiceLayer`
      Sets a property on a domain object.
      Specified by:
        `setProperty` in class `ServiceLayer`
      Parameters:
        `domainObject` - the domain object to operate on
        `property` - the name of the property to set
        `expectedType` - the type of the property
        `value` - the new value

    - #### validate

          public <T> java.util.Set<ConstraintViolation<T>> validate(T domainObject)

      Description copied from class: `ServiceLayer`
      Invoke a JSR 303 validator on the given domain object. If no validator is available, this method is a no-op.
      Specified by:
        `validate` in class `ServiceLayer`
      Type Parameters:
        `T` - the type of data being validated
      Parameters:
        `domainObject` - the domain objcet to validate
      Returns:
        the violations associated with the domain object

    - #### die

          protected final <T> T die(java.lang.Throwable e,
                  java.lang.String message,
                  java.lang.Object... args)
                         throws UnexpectedException

      Throw a fatal error up into the top-level processing code. This method should be used to provide diagnostic information that will help the end-developer track down problems when that data would expose implementation details of the server to the client.
      Parameters:
        `e` - a throwable with more data, may be `null`
        `message` - a printf-style format string
        `args` - arguments for the message
      Throws:
        `UnexpectedException` - this method never returns normally
      See Also:
        `report(String, Object...)`

    - #### getTop

          protected final ServiceLayer getTop()

      Returns the top-most service layer. General-purpose ServiceLayer decorators should use the instance provided by `getTop()` when calling public methods on the ServiceLayer API to allow higher-level decorators to override behaviors built into lower-level decorators.
      Returns:
        the ServiceLayer returned by `ServiceLayer.create(ServiceLayerDecorator...)`

    - #### report

          protected final <T> T report(java.lang.reflect.InvocationTargetException userGeneratedException)
                            throws ReportableException

      Report an exception thrown by code that is under the control of the end-developer.
      Parameters:
        `userGeneratedException` - an `InvocationTargetException` thrown by an invocation of user-provided code
      Throws:
        `ReportableException` - this method never returns normally

    - #### report

          protected final <T> T report(java.lang.String msg,
                     java.lang.Object... args)
                            throws ReportableException

      Return a message to the client. This method should not include any data that was not sent to the server by the client to avoid leaking data.
      Parameters:
        `msg` - a printf-style format string
        `args` - arguments for the message
      Throws:
        `ReportableException` - this method never returns normally
      See Also:
        `die(Throwable, String, Object...)`

    - #### getNext

          final ServiceLayer getNext()

      Retrieves the next service layer. Used only by the server-package code and accessed by used code via `super.doSomething()`.