Revision: 10056
Author: [email protected]
Date: Fri Apr 22 07:44:46 2011
Log: Edited wiki page RequestFactoryMovingParts through web user
interface.
http://code.google.com/p/google-web-toolkit/source/detail?r=10056
Modified:
/wiki/RequestFactoryMovingParts.wiki
=======================================
--- /wiki/RequestFactoryMovingParts.wiki Fri Apr 22 06:18:48 2011
+++ /wiki/RequestFactoryMovingParts.wiki Fri Apr 22 07:44:46 2011
@@ -73,7 +73,7 @@
A proxy is a lightweight interface that exposes a subset of the property
accessors of domain types to the RequestFactory client. All
developer-defined proxies must extend either 'EntityProxy'
or 'ValueProxy'. While the two proxy types extend a common `BaseProxy'
type, this type exists solely to reduce API method count and is not
directly usable by developers.
-Every proxy must be annotated with a `@ProxyFor` or `@ProxyForName`
annotation to declare which domain type the proxy provides access to. It
is legal for multiple proxy types to be mapped to the same domain type.
+Every proxy must be annotated with a `@ProxyFor` or `@ProxyForName`
annotation to declare which domain type the proxy provides access to. It
is legal for multiple proxy types to be mapped to the same domain type.
The effects of `@ProxyFor` and `@ProxyForName` are equivalent, although the
latter uses string values instead of class literals to support the
compilation of clients without access to server classes.
Proxies that map non-default-instantiable domain types can define a
`Locator` in their `@ProxyFor` annotation.
@@ -110,7 +110,15 @@
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].
+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]. Implementations of user-defined methods are
provided by a generator or reflection-based proxy. The generated subtypes
of `AbstractRequestProxy` provide their own `AutoBeanFactory` interfaces
which define only those proxy types that are reachable from the methods
defined within the `RequestContext` interface in order to improve code
pruning.
+
+The `ProxySerializer` provided by the `RequestFactory` is essentially a
loopback version of `AbstractRequestContext` implemented in
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/ProxySerializerImpl.java
ProxySerializerImpl].
+
+== !RequestFactory ==
+
+The `RequestFactory` interface defines the top-level API used by
developers. Through the `RequestFactory` interface, the developer can
obtain instances of `RequestContext` objects, serialize and restore id and
proxy objects, and use the `find()` method to retrieve previously-accessed
entities.
+
+Most of the `RequestFactory` API is implemented by
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/AbstractRequestFactory.java
AbstractRequestFactory], with the user-defined methods added via
code-generation or a reflection-based proxy. The `AbstractRequestFactory`
type send events to a user-provided `EventBus` and delegates payload
handling to a optional `RequestTransport` type. The factory also maintains
a map of encoded id and version pairs to suppress redundant `UPDATE`
messages.
== !RequestFactoryinterfaceValidator ==
@@ -138,6 +146,19 @@
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.
+== !StableId ==
+
+Every `EntityProxy` has a stable id object that can be accessed via
`EntityProxy.stableId()` and is implemented via
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/SimpleProxyId.java
SimpleProxyId]. Most operations involving the lifecycle or encoding of id
objects are contained in
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/IdFactory.java
IdFactory], which is a base type of `AbstractRequestFactory`, and
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/impl/IdUtil.java
IdUtil].
+
+The `SimpleProxyId` may use one or more of the following fields to track
identity information: `encodedAddress`, `clientId`, and `syntheticId`. The
`encodedAddress` is an opaque string that is never directly interpreted by
the client and contains a serialized representation of the domain entity's
id property. The `clientId` and `syntheticId` fields are used for objects
that do not have a persistent identity on the server.
+
+At runtime, id objects have the following flavors:
+ * Persistent, which represent entities that have been persisted by the
server. These id objects only define a meaningful `encodedAddress`.
Persistent ids and their serialized forms are valid indefinitely.
+ * Ephemeral, which have a `null` `encodedAddress`. Ephemeral ids are
used to track client-created proxies before being persisted on the server.
In the general use pattern, ephemeral ids are upgraded to persistent ids
upon receipt of a `PERSIST` message from the server that provides an
`encodedAddress` for a given `clientId`. Ephemeral ids and their
serialized forms are valid for the lifespan of a `RequestFactory` instance.
+ * Synthetic, which are valid for the lifetime of a single
`RequestContext` and are used to encode object references to `ValueProxies`
in serialized payloads.
+
+An instance of the `SimpleProxyId` type provides stable `hashCode()` and
`equals()` behavior across its entire lifetime, allowing it to be used as a
`Map` key. This guarantee applies across an upgrade from ephemeral to
persistent status. The implementation of `IdFactory.getId()` will reuse
the same instance of an ephemeral or formerly-ephemeral object when
upgraded to persistent status, however developers should not generally
depend the runtime object identity of id objects.
+
== Wire format ==
RequestFactory supports two wire formats, a custom JSON-based protocol for
communicating with `SimpleRequestProcessor` and a JSON-RPC format for
communicating with other web services. These JSON messages are generated
from AutoBean types defined in
[http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/web/bindery/requestfactory/shared/messages/MessageFactory.java
MessageFactory].
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
