[gwt-contrib] [google-web-toolkit] r10035 committed - Edited wiki page RequestFactoryMovingParts through web user interface.

[codesite-noreply]

Revision: 10035
Author:   b...@google.com
Date:     Wed Apr 20 08:29:27 2011
Log:      Edited wiki page RequestFactoryMovingParts through web user  
interface.
http://code.google.com/p/google-web-toolkit/source/detail?r=10035
Modified:
 /wiki/RequestFactoryMovingParts.wiki

=======================================
--- /wiki/RequestFactoryMovingParts.wiki        Tue Apr 19 16:46:49 2011
+++ /wiki/RequestFactoryMovingParts.wiki        Wed Apr 20 08:29:27 2011
@@ -1,18 +1,21 @@
 #summary A summary of the bits that make up RequestFactory
+#labels Phase-Implementation

 * Work in progress *

+For documentation on using RequestFactory, see the  
[http://code.google.com/webtoolkit/doc/latest/DevGuideRequestFactory.html  
RequestFactory developer's guide].
+
 <wiki:toc level='2' />

 = Introduction =

-The RequestFactory system is composed of a number of discrete component  
pieces. This document will describe the rough functionality of the  
RequestFactory components as a aid to developers who wish to work on  
RequestFactory or adapt RequestFactory to non-standard deployment  
environments.  This document assumes a working knowledge of how to use  
RequestFactory.
+The RequestFactory system is composed of a number of discrete component  
pieces. This document will describe the rough functionality of the  
RequestFactory components as an aid to developers who wish to work on  
RequestFactory or adapt RequestFactory to non-standard deployment  
environments.  This document assumes a working knowledge of how to use  
RequestFactory.

 <img src="http://i.imgur.com/WNqrg.jpg"; title="If it doesn't fit on a  
sticky note, it's too complicated." alt="Schematic drawing of the major  
components of RequestFactory"/>

 = Flow =

-  * Instantiate an instance of a `RequestFactory` via `GWT.create()` or  
`RequestFactorySource`
+  * Instantiate an instance of a `RequestFactory` via `GWT.create()` or  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/vm/RequestFactorySource.java  
RequestFactorySource]
   * Obtain an instance of `RequestContext` by calling an accessor method  
defined within the `RequestFactory`
     * Use `RequestContext.create()` and `RequestContext.edit()` to  
accumulate zero or more *operations* to be applied to domain objects by the  
server.
     * Obtain one or more `Request` objects to accumulate *invocations* on  
server code.
@@ -20,9 +23,10 @@
     * Call `Request.fire()` or `RequestContext.fire()` to send the  
accumulated data to the server.
   * The accumulated state is transmitted to the server, where the  
following operations take place:
     * All domain objects referred to by the payload will be loaded.
-    * All accumulated operations will be applied to the domain objects.
+    * Proxy objects are created for each referenced domain object.  These  
proxies are used later in the request processing to minimuze the amount of  
data returned to the client.
+    * All accumulated operations will be applied to the domain objects by  
traversing properties of the proxies.
     * All method invocations in the payload are executed.
-    * The states of entities referred to in the original payload are  
compared to the up-to-date states of the entities after all work has been  
performed.
+    * The versions of entities referred to in the original payload are  
compared to the up-to-date versions of the entities after all work has been  
performed.
       * Entities with updated properties are enqueued to be sent back to  
the client.
       * Entities that can be no longer retrieved after all work has been  
performed are reported as having been deleted.
   * The return payload is assembled and sent to the client.
@@ -83,7 +87,35 @@
 Many samples include a `persist()` method as one of the first examples of  
server code, however this is merely a convention.  RequestFactory does not  
treat this as a special method.

 == Request ==
+
+<img src="http://i.imgur.com/yaYFp.jpg"; alt="Schematic diagram of  
AbstractRequestContext and related types" />
+
+A `Request` and its related type `InstanceRequest` represent a method  
invocation to be performed on the server.  The  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/AbstractRequest.java  
AbstractRequest] base type is extended by the generator for each  
`RequestContext` method declaration.  The `Request` objects associate a  
`RequestData` bag of metadata and parameter values with the user-provided  
`Receiver` that was registered with `Request.to()` or implicitly by  
`Request.fire(Receiver)`.
+
 == !RequestContext ==
+
+A `RequestContext` maps domain code into the client's view.  Each  
`RequestContext` must be annotated with a `@Service` or `@ServiceName`  
annotation.  For a domain method with the following signature
+{{{
+ReturnType methodName(SomeParam p0, int p1, String p2);
+}}}
+the mapped `RequestContext` must have a similar method declaration that  
uses the client types instead of the domain types:
+{{{
+Request<ReturnTypeProxy> methodName(SomeParamProxy p0, int p1, String p2);
+}}}
+
+
+The bulk of the `RequestContext` implementation can be found in  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/AbstractRequestContext.java  
AbstractRequestContext].
+
+== !RequestFactoryinterfaceValidator ==
+
+The  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/server/RequestFactoryInterfaceValidator.java  
RequestFactoryInterfaceValidator] class compares the structures of the  
client-side interfaces with the method signatures of the domain objects.   
Starting from a RequestFactory interface, the validator examines each  
`RequestContext` and the various proxy types reachable from the contexts.   
The validator records the mappings between the client interfaces and the  
domain types and their optional locators as expressed in the `@Proxy` and  
`@Service` annotations.  The `ResolverServiceLayer` uses this accumulated  
data to find the proxy `Class` and `Method` objects that a payload refers  
to.
+
+Individual methods in a `RequestContext` or proxy type can exempted from  
validation by applying the `@SkipInterfaceValidation` annotation.  This  
annotation is only necessary when customizations to the `ServiceLayer` are  
being used to offer alternate method dispatch semantics, to provide  
synthetic properties, or otherwise manipulate `SimpleRequestProcessor`'s  
view of the domain.
+
+== !RequestState ==
+
+A  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/server/RequestState.java  
RequestState] is used by `SimpleRequestProcessor` to encapsulate all  
temporary data necessary to process a single request.  In general, a  
`RequestState` maps domain objects to id objects and the id objects to  
proxy instances.  The proxy instances have ephemeral tag values that  
associate them with their domain objects.
+
 == !ServiceLocator ==

 A `ServiceLocator` is used to provide instance objects for non-static  
domain methods.  Implementations of `ServiceLocators` are assumed to be  
default-instantiable, however this may be changed by providing alternate  
implementation of `ServiceLayer.createServiceLocator()`.
@@ -96,6 +128,14 @@

 == !SimpleRequestProcessor ==

+<img src="http://i.imgur.com/i7eN0.jpg"; title="Boxes within boxes, wheels  
within wheels." alt="Schematic drawing of SimpleRequestProcessor" />
+
+The  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/server/SimpleRequestProcessor.java  
SimpleRequestProcessor] is relatively stateless.  All transient state  
necessary for processing an individual request is contained in a  
`RequestState` object.
+
+= JRE compatible implementation =
+
+RequestFactory provides a JRE-compatible implementation that can be used  
for fast integration tests, server performance monitoring, or ad-hoc  
utility clients.  The implementation is accessed via the  
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/vm/RequestFactorySource.java  
RequestFactorySource] type.
+
 = Random notes without a home =

   * The `gwt.rpc.dumpPayload` environment variable can be set to `true`  
when attempting to debug RequestFactory behavior.

--
http://groups.google.com/group/Google-Web-Toolkit-Contributors