All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.web.bindery.requestfactory.server.ServiceLayer Maven / Gradle / Ivy

There is a newer version: 2.10.0
Show newest version
/*
 * Copyright 2010 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.web.bindery.requestfactory.server;

import com.google.web.bindery.requestfactory.shared.BaseProxy;
import com.google.web.bindery.requestfactory.shared.Locator;
import com.google.web.bindery.requestfactory.shared.RequestContext;
import com.google.web.bindery.requestfactory.shared.RequestFactory;
import com.google.web.bindery.requestfactory.shared.ServiceLocator;

import java.lang.reflect.Method;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Set;

import javax.validation.ConstraintViolation;

/**
 * The ServiceLayer mediates all interactions between the
 * {@link SimpleRequestProcessor} and the domain environment. The core service
 * logic can be decorated by extending an {@link ServiceLayerDecorator}.
 * 

* This API is subject to change in future releases. */ public abstract class ServiceLayer { /* * NB: This type cannot be directly extended by the user since it has a * package-protected constructor. This means that any API-compatibility work * that needs to happen can be done in ServiceLayerDecorator in order to keep * this interface as clean as possible. */ /** * Provides a flag to disable the ServiceLayerCache for debugging purposes. */ private static final boolean ENABLE_CACHE = Boolean.valueOf(System.getProperty( "gwt.rf.ServiceLayerCache", "true")); /** * Create a RequestFactory ServiceLayer that is optionally modified by the * given decorators. * * @param decorators the decorators that will modify the behavior of the core * service layer implementation * @return a ServiceLayer instance */ public static ServiceLayer create(ServiceLayerDecorator... decorators) { List list = new ArrayList(); // Always hit the cache first ServiceLayerDecorator cache = ENABLE_CACHE ? new ServiceLayerCache() : new ServiceLayerDecorator(); list.add(cache); // The the user-provided decorators if (decorators != null) { list.addAll(Arrays.asList(decorators)); } // Support for Locator objects list.add(new LocatorServiceLayer()); // Interact with domain objects list.add(new ReflectiveServiceLayer()); // Add shortcut for find's operation list.add(new FindServiceLayer()); // Locate domain objects list.add(new ResolverServiceLayer()); // Make the last layer point to the cache list.get(list.size() - 1).top = cache; // Point each entry at the next for (int i = list.size() - 2; i >= 0; i--) { ServiceLayerDecorator layer = list.get(i); layer.next = list.get(i + 1); layer.top = cache; } return cache; } /** * A pointer to the top-most ServiceLayer instance. */ ServiceLayer top; /** * Not generally-extensible. */ ServiceLayer() { } /** * Create an instance of the requested domain type. * * @param the requested domain type * @param clazz the requested domain type * @return an instance of the requested domain type */ public abstract T createDomainObject(Class clazz); /** * Create an instance of the requested {@link Locator} type. * * @param the requested Locator type * @param clazz the requested Locator type * @return an instance of the requested Locator type */ public abstract > T createLocator(Class clazz); /** * Create an instance of a service object that can be used as the target for * the given method invocation. * * @param requestContext the RequestContext type for which a service object * must be instantiated. * @return an instance of the requested service object */ public abstract Object createServiceInstance(Class requestContext); /** * Create an instance of the requested {@link ServiceLocator} type. * * @param the requested ServiceLocator type * @param clazz the requested ServiceLocator type * @return an instance of the requested ServiceLocator type */ public abstract T createServiceLocator(Class clazz); /** * Returns the ClassLoader that should be used when attempting to access * domain classes or resources. *

* The default implementation returns * {@code Thread.currentThread().getContextClassLoader()}. */ public abstract ClassLoader getDomainClassLoader(); /** * Determine the method to invoke when retrieving the given property. * * @param domainType a domain entity type * @param property the name of the property to be retrieved * @return the Method that should be invoked to retrieve the property or * {@code null} if the method could not be located */ public abstract Method getGetter(Class domainType, String property); /** * Return the persistent id for a domain object. May return {@code 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 * {@link #loadDomainObject(Class, Object)} in the future. * * @param domainObject a domain object * @return the persistent id of the domain object or {@code null} if the * object is not persistent */ public abstract Object getId(Object domainObject); /** * Returns the type of object the domain type's {@code findFoo()} or * {@link com.google.web.bindery.requestfactory.shared.Locator#getId(Object) * Locator.getId()} expects to receive. * * @param domainType a domain entity type * @return the type of the persistent id value used to represent the domain * type */ public abstract Class getIdType(Class domainType); /** * Retrieve the named property from the domain object. * * @param domainObject the domain object being examined * @param property the property name * @return the value of the property */ public abstract Object getProperty(Object domainObject, String property); /** * Compute the return type for a method declared in a RequestContext by * analyzing the generic method declaration. */ public abstract Type getRequestReturnType(Method contextMethod); /** * Determine the method to invoke when setting the given property. * * @param domainType a domain entity type * @param property the name of the property to be set * @return the Method that should be invoked to set the property or * {@code null} if the method could not be located */ public abstract Method getSetter(Class domainType, String property); /** * May return {@code 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. * * @param domainObject a domain object * @return the version of the domain object or {@code null} if the object is * not persistent */ public abstract Object getVersion(Object domainObject); /** * Invoke a domain service method. The underlying eventually calls * {@link Method#invoke(Object, Object...)}. * * @param domainMethod the method to invoke * @param args the arguments to pass to the method * @return the value returned from the method invocation */ public abstract Object invoke(Method domainMethod, Object... args); /** * Returns {@code true} if the given domain object is still live (i.e. not * deleted) in the backing store. * * @param domainObject a domain entity * @return {@code true} if {@code domainObject} could be retrieved at a later * point in time */ public abstract boolean isLive(Object domainObject); /** * Load an object from the backing store. This method may return {@code null} * to indicate that the requested object is no longer available. * * @param the type of object to load * @param clazz the type of object to load * @param domainId an id previously returned from {@link #getId(Object)} * @return the requested object or {@code null} if it is irretrievable */ public abstract T loadDomainObject(Class clazz, Object domainId); /** * 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 * {@link #loadDomainObject(Class, Object)}. * * @param classes type type of each object to load * @param domainIds the ids previously returned from {@link #getId(Object)} * @return the requested objects, elements of which may be {@code null} if the * requested objects were irretrievable */ public abstract List loadDomainObjects(List> classes, List domainIds); /** * Determines if the invocation of a domain method requires a * {@link ServiceLocator} as the 0th parameter when passed into * {@link #invoke(Method, Object...)}. * * @param contextMethod a method defined in a RequestContext * @param domainMethod a domain method * @return {@code true} if a ServiceLocator is required */ public abstract boolean requiresServiceLocator(Method contextMethod, Method domainMethod); /** * Given a type token previously returned from * {@link #resolveTypeToken(Class)}, return the Class literal associated with * the token. * * @param typeToken a string token * @return the type represented by the token */ public abstract Class resolveClass(String typeToken); /** * 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 * {@code clientType} parameter is used to ensure assignability. * * @param domainClass the server-side type to be transported to the client * @param clientType the type to which the returned type must be assignable * @param required if {@code true} and no mapping is available, throw an * exception, otherwise the method will return {@code null} * @return a class that represents {@code domainClass} on the client which is * assignable to {@code clientType} */ public abstract Class resolveClientType(Class domainClass, Class clientType, boolean required); /** * Determine the domain (server-side) type that the given client type is * mapped to. * * @param clientType a client-side type * @return the domain type that {@code clientType} represents */ public abstract Class resolveDomainClass(Class clientType); /** * Return the domain service method associated with a RequestContext method * declaration. The {@code requestContextMethod} will have been previously * resolved by {@link #resolveRequestContextMethod(String, String)}. * * @param requestContext the RequestContext requested by the client * @param requestContextMethod a RequestContext method declaration. Note that * this Method may be defined in a supertype of * {@code requestContext} * @return the domain service method that should be invoked */ public abstract Method resolveDomainMethod(String operation); /** * Return the type of {@link Locator} that should be used to access the given * domain type. * * @param domainType a domain (server-side) type * @return the type of Locator to use, or {@code null} if the type conforms to * the RequestFactory entity protocol */ public abstract Class> resolveLocator(Class domainType); /** * Find a RequestContext that should be used to fulfill the requested * operation. * * @param operation the operation * @return the RequestContext or {@code null} if no RequestContext exists that * can fulfill the operation */ public abstract Class resolveRequestContext(String operation); /** * Find a RequestContext method declaration by name. * * @param operation the operation's name * @return the method declaration, or {@code null} if the method does not * exist */ public abstract Method resolveRequestContextMethod(String operation); /** * Loads and validates a RequestFactory interface. * * @param token the RequestFactory's type token (usually the type's binary * name) * @return the RequestFactory type */ public abstract Class resolveRequestFactory(String token); /** * Given a {@link RequestContext} method, find the service class referenced in * the {@link com.google.web.bindery.requestfactory.shared.Service Service} or * {@link com.google.web.bindery.requestfactory.shared.ServiceName * ServiceName} annotation. * * @param requestContextClass a RequestContext interface * @return the type of service to use */ public abstract Class resolveServiceClass(Class requestContextClass); /** * Given a RequestContext method declaration, resolve the * {@link ServiceLocator} that should be used when invoking the domain method. * This method will only be called if * {@link #requiresServiceLocator(Method, Method)} returned {@code true} for * the associated domain method. * * @param requestContext the RequestContext for which a ServiceLocator must be * located * @return the type of ServiceLocator to use */ public abstract Class resolveServiceLocator( Class requestContext); /** * Return a string used to represent the given type in the wire protocol. * * @param proxyType a client-side EntityProxy or ValueProxy type * @return the type token used to represent the proxy type */ public abstract String resolveTypeToken(Class proxyType); /** * Sets a property on a domain object. * * @param domainObject the domain object to operate on * @param property the name of the property to set * @param expectedType the type of the property * @param value the new value */ public abstract void setProperty(Object domainObject, String property, Class expectedType, Object value); /** * Invoke a JSR 303 validator on the given domain object. If no validator is * available, this method is a no-op. * * @param the type of data being validated * @param domainObject the domain objcet to validate * @return the violations associated with the domain object */ public abstract Set> validate(T domainObject); }