[seam-commits] Seam SVN: r12033 - modules/remoting/trunk/docs/en-US.

[seam-commits at lists.jboss.org]

Author: shane.bryzak at jboss.com
Date: 2010-02-10 23:10:27 -0500 (Wed, 10 Feb 2010)
New Revision: 12033

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 00:42:25 UTC (rev 12032)
+++ modules/remoting/trunk/docs/en-US/remoting-model.xml	2010-02-11 04:10:27 UTC (rev 12033)
@@ -55,7 +55,8 @@
     <programlisting><![CDATA[  var action = new Seam.Action();]]></programlisting>    
     
     <para>
-      The following table lists the methods used to define the action.
+      The following table lists the methods used to define the action.  Each of the following methods
+      return a reference to the <literal>Seam.Action</literal> object, so methods can be chained.
     </para>
   
     <table>
@@ -381,15 +382,13 @@
     <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
+      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:
     </para>
     
-    <mediaobject>
-       <imageobject>
-          <imagedata fileref="images/remoting-model-customer-uml-1.png" format="PNG"/> 
-       </imageobject>
-    </mediaobject>    
-    
     <programlisting><![CDATA[@Entity Customer implements Serializable {
   private Integer customerId;
   private String firstName;
@@ -426,11 +425,69 @@
   @PersistenceContext EntityManager entityManager;
   public Customer customer;
   
-  public void createCustomer() {
-    customer = new Customer();
-    conversation.begin();
+  public void editCustomer(Integer customerId) {
+    conversation.begin();  
+    customer = entityManager.find(Customer.class, customerId);
   }
+  
+  public void saveCustomer() {
+    entityManager.merge(customer);
+    conversation.end();
+  }
 }]]></programlisting>
+
+    <para>
+      In the client section of this example, we wish to make changes to an existing <literal>Customer</literal>
+      instance, so we need to use the <literal>editCustomer()</literal> method of <literal>CustomerAction</literal>
+      to first load the customer entity, after which we can access it via the public <literal>customer</literal>
+      field.  Our model object must therefore be configured to fetch the <literal>CustomerAction.customer</literal>
+      property, and to invoke the <literal>editCustomer()</literal> method when the model is fetched.  We start
+      by using the <literal>addBeanProperty()</literal> method to add a bean property to the model:
+    </para>
+    
+    <programlisting><![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.
+    </para>
+
+    <mediaobject>
+       <imageobject>
+          <imagedata fileref="images/remoting-model-customer-uml-1.png" format="PNG"/> 
+       </imageobject>
+    </mediaobject>   
+    
+    <para>
+      We also specify the action that we wish to invoke (i.e. the <literal>editCustomer()</literal> method).  
+      In this example we know the value of the <literal>customerId</literal> that we wish to edit, so we can 
+      specify this value as an action method parameter:
+    </para>
+    
+    <programlisting><![CDATA[  var action = new Seam.Action()
+    .setBeanType("CustomerAction")
+    .setMethod("editCustomer")
+    .addParam(123);]]></programlisting>
+    
+    <para>
+      Once we've specified the bean properties we wish to fetch and the action to invoke, we can then fetch the
+      model.  We pass in a reference to the action object as the first parameter of the <literal>fetch()</literal>
+      method.  Also, since this is an asynchronous request we need to provide a callback method to deal with the 
+      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 + 
+    " " + model.getValue("customer").lastName); };
+  model.fetch(action, callback);]]></programlisting>
+  
+    <para>
+      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>
   
   <section>