Revision: 9167
Author: [email protected]
Date: Fri Oct 29 12:11:01 2010
Log: Edited wiki page AutoBean through web user interface.
http://code.google.com/p/google-web-toolkit/source/detail?r=9167
Modified:
/wiki/AutoBean.wiki
=======================================
--- /wiki/AutoBean.wiki Fri Oct 29 11:32:27 2010
+++ /wiki/AutoBean.wiki Fri Oct 29 12:11:01 2010
@@ -2,7 +2,7 @@
= GWT !AutoBean framework =
-The AutoBean framework provides automatically-generated implementations of
bean-like interfaces. AutoBeans can be used in both client and server
code, to improve code re-use. This document describes the state of
AutoBeans as found in the GWT 2.1.1 release.
+The AutoBean framework provides automatically-generated implementations of
bean-like interfaces. AutoBeans can be used in both client and server
code, to improve code re-use. For example, the `Requestfactory` system
uses AutoBeans extensively in both the client and server code. This
document describes the state of AutoBeans as found in the GWT 2.1.1 release.
<wiki:toc />
@@ -76,12 +76,81 @@
== !AutoBean ==
-
+=== accept() ===
+
+The AutoBean controller provides a visitor API to allow the properties of
an AutoBean to be examined by code that has no prior knowledge of the
interface being wrapped.
+
+=== as() ===
+
+The AutoBean acts as a controller for a shim object that implements the
interface with which the AutoBean is parameterized. For instance, in order
to get the `Person` interface for an `AutoBean<Person>` it is necessary to
call the `as()` method. The reason for this level of indirection is to
avoid any potential for method signature conflicts if the AutoBean were to
also implement its target interface.
+
+=== clone() ===
+
+An AutoBean and the property values stored within it can be cloned. The
`clone()` method has a boolean parameter that will trigger a deep or a
shallow copy. Any tag values associated with the AutoBean will not be
cloned. AutoBeans that wrap a delegate object cannot be cloned.
+
+=== getTag() / setTag() ===
+
+Arbitrary metadata of any type can be associated with an AutoBean by using
the AutoBean as a map-like object. The tag values do not participate in
cloning or serialization operations.
+
+=== isFrozen() / setFrozen() ===
+
+Property mutations can be disabled by calling `setFrozen()`. Any attempts
to call a setter on a frozen AutoBean will result in an
`IllegalStateException`.
+
+=== isWrapper() / unwrap() ===
+
+If the factory method used to instantiate the AutoBean provided a delegate
object, the AutoBean can be detached by calling the `unwrap()` object. The
`isWrapper()` method will indicate
== !AutoBeanFactory ==
== !AutoBeanCodex ==
+== !AutoBeanVisitor ==
+
+AutoBeanVisitor is a concrete, no-op, base type that is intended to be
extended by developers that wish to write reflection-like code over an
AutoBean's target interface.
+
+=== visit() / endVisit() ===
+
+Regardless of the reference structure of an AutoBean graph, a visitor will
visit any given AutoBean exactly once. Users of the AutoBeanVisitor should
not need to implement cycle-detection themselves.
+
+As of GWT 2.1.1, the Context interface is empty and exists to allow for
future expansion.
+
+=== visitReferenceProperty() / visitValueProperty() ===
+
+The property visitation methods in an `AutoBeanVisitor` type will receive
a `PropertyContext` object that allows the value of the property to be
mutated as well as providing type information about the field. If a
reference property being visited extends `Collection` the single
parameterization of that type will be provided. Calling the `canSet()`
method before calling `set()` promotes good code hygiene.
+
+== !AutoBeanUtils ==
+
+=== diff() ===
+
+Performs a shallow comparison between the properties in two AutoBeans and
returns a map of the properties that are not equal to one another. The
beans do not need to be of the same interface type, which allows for a
degree of duck-typing.
+
+=== getAllProperties() ===
+
+Creates a shallow copy of the properties in the AutoBean. Modifying the
structure of the returned map will not have any effect on the state of the
AutoBean. The reference values in the map are not cloned, but are the same
instances held by the AutoBean's properties.
+
== JSON structures ==
+Generally speaking, the serialized form of an object emitted by
AutoBeanCodex mirrors the interface declaration. For instance, the example
Person interface described in the quckstart section of this document might
be serialized as:
+
+{{{
+// Whitespace added for clarity
+{ "name" : "John Doe", "address" : { "street" : "1234 Maple
St", "city" : "Nowhere" } }
+}}}
+
+List and Set properties are encoded as JSON lists.
+
+*Below is not yet implemented*
+Maps are serialized in two forms based on wether or not the key type is a
value or reference type. Value maps are encoded as a typical JSON object.
For example, a `Map<Integer, Foo>` would be encoded as
+{{{
+{ "1" : { "property" : "value"}, "55" : { "property" : "value" } }
+}}}
+
+A map that uses a reference object as a key will instead be encoded as a
list of two lists. For example, a `Map<Person, Address>` would be encoded
as:
+
+{{{
+[ [ { "name" : "John Doe" } , { "name" : "Jim Smith" } ] , [
{ "street" : "1234 Maple Ave" }, { "street" : "5678 Fair Oaks Lane" } ] ]
+}}}
+
+== Categories ==
+
== FAQ ==
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
