Author: shane.bryzak(a)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>