Package 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 bycreate().

Field Summary

Fields

Modifier and Type	Field	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	Description
ServiceLayerDecorator()

Method Summary

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

next

ServiceLayer next

A pointer to the next deepest layer.

Constructor Details

ServiceLayerDecorator

public ServiceLayerDecorator()

Method Details

createDomainObject

public <T> T createDomainObject(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(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 Object createServiceInstance(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(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 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 Method getGetter(Class<?> domainType,
 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 Object getId(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 Class<?> getIdType(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 Object getProperty(Object domainObject,
 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 Type getRequestReturnType(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 Method getSetter(Class<?> domainType,
 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 Object getVersion(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 Object invoke(Method domainMethod,
 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(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(Class<T> clazz,
 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 List<Object> loadDomainObjects(List<Class<?>> classes,
 List<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(Method contextMethod,
 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 Class<? extends BaseProxy> resolveClass(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> Class<? extends T> resolveClientType(Class<?> domainClass,
 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 Class<?> resolveDomainClass(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 Method resolveDomainMethod(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

invalid reference

#resolveRequestContextMethod(String, String)

.

Specified by:

resolveDomainMethod in class ServiceLayer

Returns:

the domain service method that should be invoked

resolveLocator

public Class<? extends Locator<?,?>> resolveLocator(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 Class<? extends RequestContext> resolveRequestContext(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 Method resolveRequestContextMethod(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 Class<? extends RequestFactory> resolveRequestFactory(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 Class<?> resolveServiceClass(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 Class<? extends ServiceLocator> resolveServiceLocator(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 String resolveTypeToken(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(Object domainObject,
 String property,
 Class<?> expectedType,
 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> 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(Throwable e,
 String message,
 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(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(String msg,
 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().