Revision: 10055
Author: b...@google.com
Date: Fri Apr 22 06:18:48 2011
Log: Edited wiki page RequestFactoryMovingParts through web user
interface.
http://code.google.com/p/google-web-toolkit/source/detail?r=10055
Modified:
/wiki/RequestFactoryMovingParts.wiki
=======================================
--- /wiki/RequestFactoryMovingParts.wiki Wed Apr 20 11:46:29 2011
+++ /wiki/RequestFactoryMovingParts.wiki Fri Apr 22 06:18:48 2011
@@ -27,7 +27,8 @@
* 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 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 in the return payload graph (i.e. those reachable from
the return values of an invocation) are returned to the client with a
subset of properties controlled by the original `Request.with()`
specification.
+ * Entities referred to solely in the invocation arguments graph are
checked to see if their version properties have changed. If so, an
`UPDATE` message is sent to the client for each changed entity, but no
property data is sent. This allows ephemeral ids to updated in a
chained-persist use pattern.
* 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.
* The various `Receivers` attached to `Requests` or the
`RequestContext` are invoked to report success, failure, or validation
violations.
@@ -48,16 +49,18 @@
=== Entity ===
-An "Entity" is any object with a well-defined identity and version.
Entities are mapped on the client as `EntityProxy` subtypes, while all
other POJOS can be mapped as `ValueProxy` subtypes.
+An "Entity" is any object with a well-defined identity and version.
Entities are mapped on the client as `EntityProxy` subtypes, while all
other POJOS can be mapped as `ValueProxy` subtypes. No assumption is made
about the semantic meaning of the version property (no requirement to be
`Comparable` or otherwise ordered), just that it is non-`equal()` to "old"
version values.
While entity domain objects need not extend any particular base type or
interface, they must implement the following informal protocol:
- * The domain type is default-instantiable
- * `I getId()` must return a stable value
- * `V getVersion()` must change every time the meaningful state of the
domain object changes. No assumption is made about the semantic meaning of
the value, just that it is non-`equal()` to state version values.
+ * The domain type is default-instantiable if the client is allowed to
use `RequestContext.create()` to arbitrarily create new instances.
+ * `I getId()` must return a stable value.
+ * `V getVersion()` must change every time the meaningful state of the
domain object changes.
* `static Entity findEntity(I id)` is used to retrieve a
previously-referenced entity, using a value returned by `getId()`. The
`findEntity()` method may return `null` to indicate that the entity has
been deleted or is otherwise unavailable. A specific naming scheme is used
for this method: `find + Entity.class.getSimpleName()`.
Domain types that cannot satisfy some or all of the requirements of the
entity protocol may participate as entities by using a `Locator`.
+The id and version properties may return any type that can be transported
by `RequestFactory`. Objects with composite ids or versions may return a
domain object, provided that there is an associated proxy for the domain
type. For example, if users wish to treat embedded objects as entities,
the enclosing domain object can be used as the id.
+
Entities can be transferred in a sparse manner, as any undefined
properties can be later retrieved since the entity has a persistent id. By
default, reference properties are not transferred unless explicitly
specified by a `Request.with()`predicate.
=== Values ===
@@ -113,7 +116,7 @@
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.
+Individual methods in a `RequestContext` or proxy type can be 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 ==
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
