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

Modifier and Type	Field and Description
(package private) ServiceLayer	top A pointer to the top-most ServiceLayer instance.

Constructor Summary

Constructors

Constructor and Description
ServiceLayer() Not generally-extensible.

Method Summary

Modifier and Type	Method and Description
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