com.google.web.bindery.requestfactory.server

## Class ServiceLayer

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

Direct Known Subclasses:
  ServiceLayerDecorator

    public abstract class ServiceLayer
    extends java.lang.Object

The ServiceLayer mediates all interactions between the `SimpleRequestProcessor` and the domain environment. The core service logic can be decorated by extending an `ServiceLayerDecorator`.

This API is subject to change in future releases.

### Field Summary

Fields
`(package private) ServiceLayer` `top` A pointer to the top-most ServiceLayer instance.

### Constructor Summary

Constructors
Constructor and Description
`ServiceLayer()` Not generally-extensible.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`static ServiceLayer` `create(ServiceLayerDecorator... decorators)` Create a RequestFactory ServiceLayer that is optionally modified by the given decorators.
`abstract <T> T` `createDomainObject(java.lang.Class<T> clazz)` Create an instance of the requested domain type.
`abstract <T extends Locator<?,?>> T` `createLocator(java.lang.Class<T> clazz)` Create an instance of the requested `Locator` type.
`abstract 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.
`abstract <T extends ServiceLocator> T` `createServiceLocator(java.lang.Class<T> clazz)` Create an instance of the requested `ServiceLocator` type.
`abstract java.lang.ClassLoader` `getDomainClassLoader()` Returns the ClassLoader that should be used when attempting to access domain classes or resources.
`abstract java.lang.reflect.Method` `getGetter(java.lang.Class<?> domainType, java.lang.String property)` Determine the method to invoke when retrieving the given property.
`abstract java.lang.Object` `getId(java.lang.Object domainObject)` Return the persistent id for a domain object.
`abstract java.lang.Class<?>` `getIdType(java.lang.Class<?> domainType)` Returns the type of object the domain type's `findFoo()` or `Locator.getId()` expects to receive.
`abstract java.lang.Object` `getProperty(java.lang.Object domainObject, java.lang.String property)` Retrieve the named property from the domain object.
`abstract 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.
`abstract java.lang.reflect.Method` `getSetter(java.lang.Class<?> domainType, java.lang.String property)` Determine the method to invoke when setting the given property.
`abstract java.lang.Object` `getVersion(java.lang.Object domainObject)` May return `null` to indicate that the domain object has not been persisted.
`abstract java.lang.Object` `invoke(java.lang.reflect.Method domainMethod, java.lang.Object... args)` Invoke a domain service method.
`abstract boolean` `isLive(java.lang.Object domainObject)` Returns `true` if the given domain object is still live (i.e.
`abstract <T> T` `loadDomainObject(java.lang.Class<T> clazz, java.lang.Object domainId)` Load an object from the backing store.
`abstract 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.
`abstract 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 `invoke(Method, Object...)`.
`abstract java.lang.Class<? extends BaseProxy>` `resolveClass(java.lang.String typeToken)` Given a type token previously returned from `resolveTypeToken(Class)`, return the Class literal associated with the token.
`abstract <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.
`abstract java.lang.Class<?>` `resolveDomainClass(java.lang.Class<?> clientType)` Determine the domain (server-side) type that the given client type is mapped to.
`abstract java.lang.reflect.Method` `resolveDomainMethod(java.lang.String operation)` Return the domain service method associated with a RequestContext method declaration.
`abstract 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.
`abstract java.lang.Class<? extends RequestContext>` `resolveRequestContext(java.lang.String operation)` Find a RequestContext that should be used to fulfill the requested operation.
`abstract java.lang.reflect.Method` `resolveRequestContextMethod(java.lang.String operation)` Find a RequestContext method declaration by name.
`abstract java.lang.Class<? extends RequestFactory>` `resolveRequestFactory(java.lang.String token)` Loads and validates a RequestFactory interface.
`abstract 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.
`abstract 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.
`abstract java.lang.String` `resolveTypeToken(java.lang.Class<? extends BaseProxy> proxyType)` Return a string used to represent the given type in the wire protocol.
`abstract 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.
`abstract <T> java.util.Set<ConstraintViolation<T>>` `validate(T domainObject)` Invoke a JSR 303 validator on the given domain object.

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

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

### Field Detail

#### top

    ServiceLayer top

A pointer to the top-most ServiceLayer instance.

### Constructor Detail

#### ServiceLayer

    ServiceLayer()

Not generally-extensible.

### Method Detail

#### create

    public static ServiceLayer create(ServiceLayerDecorator... decorators)

Create a RequestFactory ServiceLayer that is optionally modified by the given decorators.

Parameters:
  `decorators` - the decorators that will modify the behavior of the core service layer implementation
Returns:
  a ServiceLayer instance

#### createDomainObject

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

Create an instance of the requested domain type.

Type Parameters:
  `T` - the requested domain type
Parameters:
  `clazz` - the requested domain type
Returns:
  an instance of the requested domain type

#### createLocator

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

Create an instance of the requested `Locator` type.

Type Parameters:
  `T` - the requested Locator type
Parameters:
  `clazz` - the requested Locator type
Returns:
  an instance of the requested Locator type

#### createServiceInstance

    public abstract 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.

Parameters:
  `requestContext` - the RequestContext type for which a service object must be instantiated.
Returns:
  an instance of the requested service object

#### createServiceLocator

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

Create an instance of the requested `ServiceLocator` type.

Type Parameters:
  `T` - the requested ServiceLocator type
Parameters:
  `clazz` - the requested ServiceLocator type
Returns:
  an instance of the requested ServiceLocator type

#### getDomainClassLoader

    public abstract java.lang.ClassLoader getDomainClassLoader()

Returns the ClassLoader that should be used when attempting to access domain classes or resources.

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

#### getGetter

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

Determine the method to invoke when retrieving the given property.

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 abstract java.lang.Object getId(java.lang.Object domainObject)

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 `loadDomainObject(Class, Object)` in the future.

Parameters:
  `domainObject` - a domain object
Returns:
  the persistent id of the domain object or `null` if the object is not persistent

#### getIdType

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

Returns the type of object the domain type's `findFoo()` or `Locator.getId()` expects to receive.

Parameters:
  `domainType` - a domain entity type
Returns:
  the type of the persistent id value used to represent the domain type

#### getProperty

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

Retrieve the named property from the domain object.

Parameters:
  `domainObject` - the domain object being examined
  `property` - the property name
Returns:
  the value of the property

#### getRequestReturnType

    public abstract 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.

#### getSetter

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

Determine the method to invoke when setting the given property.

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 abstract java.lang.Object getVersion(java.lang.Object domainObject)

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.

Parameters:
  `domainObject` - a domain object
Returns:
  the version of the domain object or `null` if the object is not persistent

#### invoke

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

Invoke a domain service method. The underlying eventually calls `Method.invoke(Object, Object...)`.

Parameters:
  `domainMethod` - the method to invoke
  `args` - the arguments to pass to the method
Returns:
  the value returned from the method invocation

#### isLive

    public abstract boolean isLive(java.lang.Object domainObject)

Returns `true` if the given domain object is still live (i.e. not deleted) in the backing store.

Parameters:
  `domainObject` - a domain entity
Returns:
  `true` if `domainObject` could be retrieved at a later point in time

#### loadDomainObject

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

Load an object from the backing store. This method may return `null` to indicate that the requested object is no longer available.

Type Parameters:
  `T` - the type of object to load
Parameters:
  `clazz` - the type of object to load
  `domainId` - an id previously returned from `getId(Object)`
Returns:
  the requested object or `null` if it is irretrievable

#### loadDomainObjects

    public abstract 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. 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 `loadDomainObject(Class, Object)`.

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

#### requiresServiceLocator

    public abstract 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 `invoke(Method, Object...)`.

Parameters:
  `contextMethod` - a method defined in a RequestContext
  `domainMethod` - a domain method
Returns:
  `true` if a ServiceLocator is required

#### resolveClass

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

Given a type token previously returned from `resolveTypeToken(Class)`, return the Class literal associated with the token.

Parameters:
  `typeToken` - a string token
Returns:
  the type represented by the token

#### resolveClientType

    public abstract <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. If multiple proxy types have been mapped to the same domain type, the `clientType` parameter is used to ensure assignability.

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 abstract java.lang.Class<?> resolveDomainClass(java.lang.Class<?> clientType)

Determine the domain (server-side) type that the given client type is mapped to.

Parameters:
  `clientType` - a client-side type
Returns:
  the domain type that `clientType` represents

#### resolveDomainMethod

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

Return the domain service method associated with a RequestContext method declaration. The `requestContextMethod` will have been previously resolved by `#resolveRequestContextMethod(String, String)`.

Parameters:
  `requestContext` - the RequestContext requested by the client
  `requestContextMethod` - a RequestContext method declaration. Note that this Method may be defined in a supertype of `requestContext`
Returns:
  the domain service method that should be invoked

#### resolveLocator

    public abstract 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.

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 abstract java.lang.Class<? extends RequestContext> resolveRequestContext(java.lang.String operation)

Find a RequestContext that should be used to fulfill the requested operation.

Parameters:
  `operation` - the operation
Returns:
  the RequestContext or `null` if no RequestContext exists that can fulfill the operation

#### resolveRequestContextMethod

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

Find a RequestContext method declaration by name.

Parameters:
  `operation` - the operation's name
Returns:
  the method declaration, or `null` if the method does not exist

#### resolveRequestFactory

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

Loads and validates a RequestFactory interface.

Parameters:
  `token` - the RequestFactory's type token (usually the type's binary name)
Returns:
  the RequestFactory type

#### resolveServiceClass

    public abstract 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.

Parameters:
  `requestContextClass` - a RequestContext interface
Returns:
  the type of service to use

#### resolveServiceLocator

    public abstract 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. This method will only be called if `requiresServiceLocator(Method, Method)` returned `true` for the associated domain method.

Parameters:
  `requestContext` - the RequestContext for which a ServiceLocator must be located
Returns:
  the type of ServiceLocator to use

#### resolveTypeToken

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

Return a string used to represent the given type in the wire protocol.

Parameters:
  `proxyType` - a client-side EntityProxy or ValueProxy type
Returns:
  the type token used to represent the proxy type

#### setProperty

    public abstract 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.

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 abstract <T> java.util.Set<ConstraintViolation<T>> validate(T domainObject)

Invoke a JSR 303 validator on the given domain object. If no validator is available, this method is a no-op.

Type Parameters:
  `T` - the type of data being validated
Parameters:
  `domainObject` - the domain objcet to validate
Returns:
  the violations associated with the domain object