3:29 a.m.
Author: shane.bryzak(a)jboss.com
Date: 2010-02-11 04:29:11 -0500 (Thu, 11 Feb 2010)
New Revision: 12034
Modified:
modules/remoting/trunk/docs/en-US/remoting-model.xml
Log:
more model api docs
Modified: modules/remoting/trunk/docs/en-US/remoting-model.xml
===================================================================
--- modules/remoting/trunk/docs/en-US/remoting-model.xml 2010-02-11 04:10:27 UTC (rev
12033)
+++ modules/remoting/trunk/docs/en-US/remoting-model.xml 2010-02-11 09:29:11 UTC (rev
12034)
@@ -52,7 +52,7 @@
<literal>Seam.Action</literal> takes no parameters:
</para>
- <programlisting><![CDATA[ var action = new
Seam.Action();]]></programlisting>
+ <programlisting role="XHTML"><![CDATA[ var action = new
Seam.Action();]]></programlisting>
<para>
The following table lists the methods used to define the action. Each of the
following methods
@@ -165,7 +165,7 @@
the Model API in JavaScript you must first create a new Model object:
</para>
- <programlisting><![CDATA[ var model = new
Seam.Model();]]></programlisting>
+ <programlisting role="XHTML"><![CDATA[ var model = new
Seam.Model();]]></programlisting>
<table>
<title>Seam.Model method reference</title>
@@ -235,6 +235,12 @@
Can only be used before the model is fetched.
</para>
+ <para>
+ Example:
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[
addBeanProperty("account", "AccountAction", "account",
"@Qualifier1", "@Qualifier2");]]></programlisting>
+
<itemizedlist>
<listitem>
<literal>alias</literal> - the local alias for the bean
value.
@@ -247,7 +253,8 @@
<literal>property</literal> - the name of the bean
property.
</listitem>
<listitem>
- <literal>qualifiers</literal> (optional) - a list of bean
qualifiers.
+ <literal>qualifiers</literal> (optional) - a list of bean
qualifiers. This parameter (and any
+ after it) are treated as bean qualifiers.
</listitem>
</itemizedlist>
</entry>
@@ -382,44 +389,32 @@
<para>
To fetch a model, one or more values must first be specified using
<literal>addBean()</literal> or
<literal>addBeanProperty()</literal> before invoking the
<literal>fetch()</literal> operation.
- Let's work through an example - here we have an entity bean called
<literal>Customer</literal>
- and a bean called <literal>CustomerAction</literal>. The
<literal>CustomerAction</literal> bean
- is used to create and edit <literal>Customer</literal> instances.
Since we're only interested in
- editing a customer right now, the following code only shows the
<literal>editCustomer()</literal>
- method:
+ Let's work through an example - here we have an entity bean called
<literal>Customer</literal>:
</para>
-
- <programlisting><![CDATA[@Entity Customer implements Serializable {
+
+ <programlisting role="JAVA"><![CDATA[@Entity Customer implements
Serializable {
private Integer customerId;
private String firstName;
private String lastName;
- @Id @GeneratedValue public Integer getCustomerId() {
- return customerId;
- }
+ @Id @GeneratedValue public Integer getCustomerId() { return customerId; }
+ public void setCustomerId(Integer customerId) { this.customerId = customerId; }
- public void setCustomerId(Integer customerId) {
- this.customerId = customerId;
- }
+ public String getFirstName() { return firstName; }
+ public void setFirstName(String firstName) { this.firstName = firstName; }
- public String getFirstName() {
- return firstName;
- }
-
- public void setFirstName(String firstName) {
- this.firstName = firstName;
- }
-
- public String getLastName() {
- return lastName;
- }
-
- public void setLastName(String lastName) {
- this.lastName = lastName;
- }
+ public String getLastName() { return lastName; }
+ public void setLastName(String lastName) { this.lastName = lastName; }
}]]></programlisting>
+
+ <para>
+ We also have a bean called <literal>CustomerAction</literal>, which is
responsible for creating and editing
+ <literal>Customer</literal> instances. Since we're only interested
in editing a customer right now, the
+ following code only shows the <literal>editCustomer()</literal>
method:
+ </para>
+
- <programlisting><![CDATA[@ConversationScoped @Named
+ <programlisting role="JAVA"><![CDATA[@ConversationScoped @Named
public class CustomerAction {
@Inject Conversation conversation;
@PersistenceContext EntityManager entityManager;
@@ -445,15 +440,15 @@
by using the <literal>addBeanProperty()</literal> method to add a bean
property to the model:
</para>
- <programlisting><![CDATA[ var model = new Seam.Model();
+ <programlisting role="XHTML"><![CDATA[ var model = new
Seam.Model();
model.addBeanProperty("customer", "CustomerAction",
"customer");]]></programlisting>
<para>
The first parameter of <literal>addBeanProperty()</literal> is the
<emphasis>alias</emphasis> (in this case
<literal>customer</literal>), which is used to access the value via the
<literal>getValue()</literal> method.
The <literal>addBeanProperty()</literal> and
<literal>addBean()</literal> methods can be called multiple times
- to bind multiple values to the model. An important thing to note is that the
values can come from multiple
- server-side beans, they don't all need to come from the same bean.
+ to bind multiple values to the model. An important thing to note is that the
values may come from multiple
+ server-side beans, they aren't all required to come from the same bean.
</para>
<mediaobject>
@@ -468,7 +463,7 @@
specify this value as an action method parameter:
</para>
- <programlisting><![CDATA[ var action = new Seam.Action()
+ <programlisting role="XHTML"><![CDATA[ var action = new
Seam.Action()
.setBeanType("CustomerAction")
.setMethod("editCustomer")
.addParam(123);]]></programlisting>
@@ -480,7 +475,7 @@
response. The callback method is passed a reference to the model object as a
parameter.
</para>
- <programlisting><![CDATA[ var callback = function(model) {
alert("Fetched customer: " model.getValue("customer").firstName +
+ <programlisting role="XHTML"><![CDATA[ var callback =
function(model) { alert("Fetched customer: "
model.getValue("customer").firstName +
" " + model.getValue("customer").lastName); };
model.fetch(action, callback);]]></programlisting>
@@ -488,12 +483,130 @@
When the server receives a model fetch request, it first invokes the action (if one
is specified) before
reading the requested property values and returning them to the client.
</para>
+
+ <section>
+ <title>Fetching a bean value</title>
+
+ <para>
+ Alternatively, if you don't wish to fetch a bean
<emphasis>property</emphasis> but rather a bean itself
+ (such as a value created by a producer method) then the
<literal>addBean()</literal> method is used instead.
+ Let's say we have a producer method that returns a qualified
<literal>UserSettings</literal> value:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[ @Produces
@ConversationScoped @Settings UserSettings getUserSettings() {
+ /* snip code */
+ }]]></programlisting>
+
+ <para>
+ We would add this value to our model with the following code:
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[
model.addBean("settings", "UserSettings",
"@Settings");]]></programlisting>
+
+ <para>
+ The first parameter is the local alias for the value, the second parameter is the
fully qualified
+ class of the bean, and the third (and subsequent) parameter/s are optional bean
qualifiers.
+ </para>
+
+ </section>
</section>
<section>
+ <title>Modifying model values</title>
+
+ <para>
+ Once a model has been fetched its values may be read using the
<literal>getValue()</literal> method.
+ Continuing on with the previous example, we would retrieve the
<literal>Customer</literal> object via
+ it's local alias (<literal>customer</literal>) like this:
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[ var customer =
model.getValue("customer");]]></programlisting>
+
+ <para>
+ We are then free to read or modify the properties of the value (or any of the other
values within its
+ object graph).
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[ alert("Customer name
is: " + customer.firstName + " " + customer.lastName);
+ customer.setLastName("Jones"); // was Smith, but Peggy got married on the
weekend]]></programlisting>
+
+ </section>
+
+ <section>
<title>Expanding a model</title>
+ <para>
+ We can use the Model API's ability to expand a model to load uninitialized
branches of the objects in
+ the model's object graph. To understand how this works exactly, let's
flesh out our example a little
+ more by adding an <literal>Address</literal> entity class, and creating
a one-to-many relationship
+ between <literal>Customer</literal> and
<literal>Address</literal>.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/remoting-model-customer-address-uml.png"
format="PNG"/>
+ </imageobject>
+ </mediaobject>
+
+ <programlisting role="JAVA"><![CDATA[@Entity Address implements
Serializable {
+ private Integer addressId;
+ private Customer customer;
+ private String unitNumber;
+ private String streetNumber;
+ private String streetName;
+ private String suburb;
+ private String zip;
+ private String state;
+ private String country;
+
+ @Id @GeneratedValue public Integer getAddressId() { return addressId; }
+ public void setAddressId(Integer addressId) { this.addressId = addressId; }
+
+ @ManyToOne public Customer getCustomer() { return customer; }
+ public void setCustomer(Customer customer) { this.customer = customer; }
+
+ /* Snipped other getter/setter methods */
+
+}]]></programlisting>
+
+ <para>
+ Here's the new field and methods that we also need to add to the
<literal>Customer</literal> class:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[ private
Collection<Address> addresses;
+
+ @OneToMany(fetch = FetchType.LAZY, mappedBy = "customer", cascade =
CascadeType.ALL)
+ public Collection<Address> getAddresses() { return addresses; }
+ public void setAddresses(Collection<Address> addresses) { this.addresses =
addresses; }]]></programlisting>
+
+ <para>
+ As we can see, the <literal>@OneToMany</literal> annotation on the
<literal>getAddresses()</literal>
+ method specifies a <literal>fetch</literal> attribute of
<literal>LAZY</literal>, meaning that by
+ default the customer's addresses won't be loaded automatically when the
customer is. When reading the
+ <emphasis>uninitialized</emphasis>
<literal>addresses</literal> property value from a newly-fetched
+ <literal>Customer</literal> object in JavaScript, a value of
<literal>undefined</literal> will be returned.
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[
getValue("customer").addresses == undefined; // returns
true]]></programlisting>
+
+ <para>
+ We can <emphasis>expand</emphasis> the model by making a special
request to initialize this uninitialized
+ property value. The <literal>expand()</literal> operation takes three
parameters - the value containing
+ the property to be initialized, the name of the property and an optional callback
method. The following
+ example shows us how the customer's <literal>addresses</literal>
property can be initialized:
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[
model.expand(model.getValue("customer"),
"addresses");]]></programlisting>
+
+ <para>
+ The <literal>expand()</literal> operation makes an asynchronous request
to the server, where the
+ property value is initialized and the value returned to the client. When the
client receives the
+ response, it reads the initialized value and appends it to the model.
+ </para>
+
+ <programlisting role="XHTML"><![CDATA[ // The addresses property
now contains an array of address objects
+ alert(model.getValue("customer").addresses.length + " addresses
loaded");]]></programlisting>
+
</section>
<section>