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
`(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

All Methods Instance Methods Concrete Methods
`<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()`.