[jbosstools-commits] JBoss Tools SVN: r2594 - in trunk/documentation/GettingStartedGuide/docs/userguide/en: modules and 1 other directory.

Author: afedosik Date: 2007-07-23 08:13:31 -0400 (Mon, 23 Jul 2007) New Revision: 2594 Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AddBusinessProcess.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/CURDAppWalkthrough.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GenCURDDatabaseApp.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/ManageJBossAS.xml Removed: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AjaxCRUDApplicationWithSeamAndRichFaces.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/BusinessProcessAndRulesApplication.xml Modified: trunk/documentation/GettingStartedGuide/docs/userguide/en/master.xml Log: http://jira.jboss.com/jira/browse/EXIN-398 New structure for GSG guide Modified: trunk/documentation/GettingStartedGuide/docs/userguide/en/master.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/master.xml 2007-07-23 11:53:37 UTC (rev 2593) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/master.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -3,8 +3,12 @@ "../../resources/support/docbook-dtd/docbookx.dtd" [<!ENTITY GettingStartedWithRHDS SYSTEM "modules/GettingStartedWithRHDS.xml"> -<!ENTITY AjaxCRUDApplicationWithSeamAndRichFaces SYSTEM "modules/AjaxCRUDApplicationWithSeamAndRichFaces.xml"> -<!--<!ENTITY BusinessProcessAndRulesApplication SYSTEM "modules/BusinessProcessAndRulesApplication.xml">--> +<!ENTITY ManageJBossAS SYSTEM "modules/ManageJBossAS.xml"> +<!ENTITY GetStartSeamGen SYSTEM "modules/GetStartSeamGen.xml"> +<!ENTITY GenCURDDatabaseApp SYSTEM "modules/GenCURDDatabaseApp.xml"> +<!ENTITY CURDAppWalkthrough SYSTEM "modules/CURDAppWalkthrough.xml"> +<!ENTITY AddBusinessProcess SYSTEM "modules/AddBusinessProcess.xml"> + ]> <book> @@ -24,11 +28,10 @@ &GettingStartedWithRHDS; -&AjaxCRUDApplicationWithSeamAndRichFaces; -<!--&BusinessProcessAndRulesApplication;--> - <!-- - &GettingStartedGuideforJavaServerFaces; - --> - - +&ManageJBossAS; +&GetStartSeamGen; +&GenCURDDatabaseApp; +&CURDAppWalkthrough; +&AddBusinessProcess; + </book> Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AddBusinessProcess.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AddBusinessProcess.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AddBusinessProcess.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -0,0 +1,480 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="AddBusinessProcess" xreflabel="AddBusinessProcess"> + <?dbhtml filename="AddBusinessProcess.html"?> + <chapterinfo> + <keywordset> + <keyword>Business process</keyword> + <keyword>Seam</keyword> + <keyword>JBoss Rules</keyword> + <keyword>CURD-application</keyword> + </keywordset> + </chapterinfo> + + <title>Business process and rules application</title> + <para>Rules and business processes are important components in many enterprise applications. + They help business analysts to get involved in the design and implementation of the software + project. Rules and business processes are also essential to complex internal states of large, + multi-user systems. The JBoss Rules engine (formerly known as Drools) and jBPM business + process engine are two production-ready open source products supported by Red Hat. It is + very easy to incorporate rules and business processes into a Seam web application using the + Red Hat Developer Studio. In this section, we further re-factor the CRUD application we + already have and add support for an &quot;order management&quot; process. The user scenario is to + simulate the following process and rules:</para> + <itemizedlist> + <listitem>The site administrator logs in and sees a list of outstanding orders</listitem> + <listitem>She goes through the inventory (by hand or using another computer system) and + determines the availability of the products in each order. She enters that information to + each order.</listitem> + <listitem>She starts a process for each order, which determines whether to ship the order + or refund the order based on a business rule applied to the availability status. For + instance, an &quot;in stock&quot; status triggers a &quot;ship&quot; action while the &quot;back order&quot; status + triggers a &quot;refund&quot; action.</listitem> + <listitem>When the business process reaches the &quot;ship&quot; or &quot;refund&quot; state, it will take + appropriate actions (e.g., to submit shipping orders to Fedex or to contact the credit + card company for refund). In this simple case, we will just print out a message on the + console to prove that we can execute any code in those stages.</listitem> + </itemizedlist> + <para>While this process sounds simple, it is the basis for very complex business + processes. In this section of the tutorial, we will show you how this is done via the + following steps:</para> + <itemizedlist> + <listitem>Add a rule definition to the application</listitem> + <listitem>Add a business process that uses that rule to the application</listitem> + <listitem>Start the business process from a web action</listitem> + </itemizedlist> +<section id="ImportConfigurationFilesAndJavaCode"> +<?dbhtml filename="ImportConfigurationFilesAndJavaCode.html"?> +<title>Import configuration files and Java code</title> +<para>Before we start, we need to import some configuration and Java files for the demo project. +Those files are very simple and we will review them as we go along with the tutorial. We import +them here to reduce potential typos and other errors in the tutorial.</para> +<orderedlist> +<listitem>Choose the <emphasis>File > Import ...</emphasis> menu and then select <emphasis>General > Existing</emphasis> project into workspace and +click on the Next button.</listitem> +</orderedlist> +<figure> +<title>Importing Project</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ProjectImporting.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>To make this demo a little more manageable we have already created some demo code +that is available in the rules-bpm directory of your tutorial distribution code. It is + located in the root directory of the distribution. Select the rules-bpm directory and check + the &quot;Copy projects into the workspace&quot; directory check box.</listitem> +</orderedlist> +<para>You will have a different directory on your machine than the screen shot shown below.</para> +<figure> +<title>Selecting Directory To Import</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ImportDirectory.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>After this step you will see a new project called &quot;rules-bpm&quot;. If you expand that +directory, you will see numerous files as shown below. We will look at these files in this + section of the demo. We will first start by copying these files into our EclipseCon project.</listitem> +</orderedlist> + +<figure> +<title>Project Structure</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ProjectStructure.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>Right click on the rules-bpm/build.xml file, and select <emphasis>Run AS ... > Ant</emphasis> Build.</listitem> +</orderedlist> + +<figure> +<title>AntBuild</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/AntBuild.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>Right click on the EclipseCon project and select Refresh from the menu to pick up + the changes made to the demo application. The rules-bpm/build.xml script copies a bunch of files + into your existing EclipseCon project. We will look at them soon.</listitem> +</orderedlist> +</section> +<section id="CreateARuledefinition"> +<?dbhtml filename="CreateARuledefinition.html"?> +<title>Create a rule definition</title> +<para>In this section, we create a business rule that can be used in junction with the business + process. When the rule is executed, it checks the status of the currently selected order. If the + order status is &quot;in stock&quot;, meaning that a person has check off line and verified the + availability of the product ordered, the system changes the order status to &quot;ship&quot;, meaning + that someone will now ship the product as the next step in the process. If the order status + is &quot;back order&quot;, the rule changes the order status to &quot;refund&quot; automatically to trigger the + business process of refunding.</para> + <orderedlist> + <listitem>Select the<emphasis> EclipseCon/resources </emphasis>directory. That is where we are going to put the + rules definition file.</listitem> + <listitem>Select the following menu actions: <emphasis>File > New > Other ... > JBoss Rules > New + Rules Resource</emphasis> to bring up the JBoss Rules wizard.</listitem> + </orderedlist> + <figure> +<title>New Rules File</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/NewRulesFile.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>Fill out the above window with the following values.</listitem> +</orderedlist> +<table> + <title>Rule Table</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Field Name</entry> + <entry>Field Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>File Name</entry> + <entry>process-order.drl</entry> + </row> + <row> + <entry>Type of Rule Resource</entry> + <entry>New DRL (rule package)</entry> + </row> + <row> + <entry>Rule Package Name</entry> + <entry>process.order</entry> + </row> + </tbody> + </tgroup> + </table> + <orderedlist continuation="continues"> +<listitem>Replace the content of the process-order.drl file with the follow rule.</listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[package process.order + import com.mydomain.EclipseCon.Orders; + +rule "Ship order rule" + when + order : Orders(status == "in stock") + then + order.setStatus("ship"); +end + +rule "Refund order rule" + when + order : Orders(status == "back order") + then + order.setStatus("refund"); +end +]]></programlisting> +<para>Notice that the IDE automatically highlights the syntax and provides auto-completion help. + You may wonder how Seam knows to load the process-order.drl file for the application.</para> + <para>If you look in the <emphasis>resources/WEB-INF/components.xml</emphasis> file we copied from the imported + rules-bpm project. It has an element pointing to the process-order.drl file.</para> + <programlisting role="XML"><![CDATA[<drools:rule-base name="securityRules"> + <drools:rule-files> + <value>/security.drl</value> + </drools:rule-files> + </drools:rule-base> +]]></programlisting> +</section> +<section id="CreateABusinessProcessDefinition"> +<?dbhtml filename="CreateABusinessProcessDefinition.html"?> +<title>Create a business process definition</title> +<para>Next, let&apos;s create a business process that manages the order process. The business process + essentially specifies a sequence of actions that has to happen before an order is shipped or + refunded. Since the business analyst typically designs this process, it is very high level and + can be drawn up in a GUI designer.</para> + <orderedlist> + <listitem>Select the<emphasis> EclipseCon/resources </emphasis>folder and select menu actions <emphasis>File > New > File</emphasis>. + Add a new file called process-order.jpdl.xml as shown below:</listitem> + </orderedlist> + <figure> +<title>Creating New File Resource</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/CreatingNewFileResource.png"/> + </imageobject> +</mediaobject> +</figure> + +<orderedlist continuation="continues"> +<listitem>Add the following content to the process-order.jpdl.xml file. It is an empty jBPM +process definition, and allows us to use the jBPM visual designer to further edit it.</listitem> +</orderedlist> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<process-definition + xmlns="" name="process-order"> +</process-definition> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem>Right click on the process-order.jpdl.xml file and select <emphasis>Open with ... > jBPM +Graphical Process Designer</emphasis>.</listitem> +</orderedlist> +<figure> +<title>Opening Graphical Process Designer</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/GraphicalProcessDesigner.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>In the designer, drag and drop nodes and transition lines until you have a process + shown in the following image. This is a high level process and aimed at business level non + technical users.</listitem> +</orderedlist> +<para>To draw a node, click on the type of the node in the palette. You should be able to see +that based on the icon on the node as shown below. Draw a rectangle on the canvas and the + appropriate node will be rendered.</para> + <para>To draw a transition click on the transition icon in the palette, choose the source node + and then the destination node. This will draw a transition from the source to the destination.</para> + <para>To change the name on the node or transition, select the object and change the name in + the properties view or simply double click on the node or the transition line to change it.</para> + <figure> +<title>Diagram View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/DiagramView.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>Save this file. You can click on the Source tab to view the generated XML file for + the process.</listitem> +</orderedlist> +</section> +<section id="AssociateProcessNodesWithJavaCode"> +<?dbhtml filename="AssociateProcessNodesWithJavaCode.html"?> +<title>Associate process nodes with Java code</title> +<para>With the business process in the designer, we can now associate each node with Java code. + The Java code is executed when the node is reached in the process, and the Java code determines + the outcome of each node – hence the next node in the process.</para> + <para>Let&apos;s go through the exercise for the &quot;Check Inventory&quot; node first.</para> + <orderedlist> + <listitem>Right click on the &quot;Check Inventory&quot; node in the designer and select <emphasis>Add + Actions > Node Enter </emphasis>from the menu as shown below.</listitem> + </orderedlist> + <figure> +<title>Node Entering</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/NodeEntering.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>In the Outline view tab, open the tree view of process-order > Check Inventory > +node enter, and you will see action1. The Outline view may be hidden or on the left side of the + IDE.</listitem> +</orderedlist> +<figure> +<title>Outline View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OutlineView.png"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem>Double click on action1 to bring up the wizard. Select Handler on the left and enter + com.mydomain.EclipseCon.process. CheckInventoryAction as the class and bean as the type as shown + below. You can can also search for the class by clicking on the <emphasis>Browse...</emphasis> button.</listitem> +</orderedlist> +<figure> +<title>Action Handler</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ActionHandler.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Explanation: Now, you must wonder where this +com.mydomain.EclipseCon.process.CheckInventoryAction class come from It comes from the +eclipsecon-rules-bpm project we imported. The Java class has a single method that is executed +when the &quot;Check Inventory&quot; node is reached in the process. The method just fires the rule we +previously defined in process-order.drl. After the rule is executed, it updates the +&quot;inventoryStatus&quot; component. Here is the method:</para> +<programlisting role="JAVA"><![CDATA[public void execute(ExecutionContext ctx) throws Exception { + + //get a handle to the rules engine + Component c = (Component) Contexts.getApplicationContext().get( + "orderWorkingMemory.component"); + WorkingMemory wm = (WorkingMemory) ((ManagedWorkingMemory) c + .newInstance()).getWorkingMemory(); + + //get the ordersHome variable that was set in OrderProcessor. + OrdersHome order = (OrdersHome) ctx.getVariable("ordersHome"); + + //Assert Orders to working memory and fire rules + wm.assertObject(order.getInstance()); + wm.fireAllRules(); + + + //persist the updated Orders object + order.persist(); + + //set inventory status so decision node knows what to do + ctx.setVariable("inventoryStatus", order.getInstance().getStatus()); + System.out.println("CHECK INVENTORY - STATUS: " + + order.getInstance().getStatus()); +} +]]></programlisting> +<para>The &quot;inventoryStatus&quot; component is then used in the &quot;Inventory Decision&quot; node to determine +which node to go to next. To do that, open the process-order.jpdl.xml file in the text editor and + change the node from this</para> + <programlisting role="XML"><![CDATA[<decision name="Inventory Decision"> + <transition name="ship" to="Ship Order"></transition> + <transition name="refund" to="Refund Order"></transition> + </decision> +]]></programlisting> +<para>to this:</para> +<programlisting role="XML"><![CDATA[<decision name="Inventory Decision" expression="#{inventoryStatus}"> + <transition name="ship" to="Ship Order"></transition> + <transition name="refund" to="Refund Order"></transition> + </decision> +]]></programlisting> +<para>Now, let&apos;s repeat the exercise to assign handler Java classes to the &quot;Ship Order&quot; and &quot;Refund Order&quot; nodes. </para> +<itemizedlist> +<listitem>Associate &quot;Ship Order&quot; node with the com.mydomain.EclipseCon.process.ShipOrderAction +bean</listitem> +<listitem>Associate &quot;Refund Order&quot; node with the com.mydomain.EclipseCon.process.SendRefundAction bean</listitem> +</itemizedlist> +<para>As we described earlier, in a real world system, those two nodes would invoke Java code + that perform real shipping and refunding tasks. But here we just print out a message as a proof + of concept. You can look into their Java classes if you have time.</para> +</section> +<section id="StartTheProcessFromAWebAction"> +<?dbhtml filename="StartTheProcessFromAWebAction.html"?> +<title>Start the process from a web action</title> +<para>Finally, we need a &quot;hook&quot; to start the entire business process. We will add a new Process + Order button to the Orders.xhtml file.</para> + <para>You can add the new button right next to the existing &quot;Add orderdetails&quot; button. + Copy/paste the following button code in the actionButtons region:</para> + <programlisting role="JSP"><![CDATA[<s:button id="buttonId" value="Process Order" + action="#{orderProcessor.startProcess}" + view="/Orders.xhtml"/> +]]></programlisting> +<para>Explanation: When you click on the Process Order button, Seam invokes +the #{orderProcessor.startProcess} method, which in turn, starts the business process. The Java +code for the #{orderProcessor} component is in the com.mydomain.EclipseCon.process.OrderProcessor +class. Like other Java source files in the process package, the OrderProcessor.java is already +copied to the EclipseCon project when you run the build.xml script from the imported rules-bpm + project. Here is the content of the OrderProcessor.java file. The startProcess() method, which + is invoked from the Process Order button, starts the process-order process we just created.</para> +<programlisting role="JAVA"><![CDATA[@Name("orderProcessor") +public class OrderProcessor { + + //Set the Orders object as a jBPM context variable + @In(create = true) + @Out(scope = ScopeType.BUSINESS_PROCESS) + OrdersHome ordersHome; + + //Execute the jBPM process + @CreateProcess(definition = "process-order") + public String startProcess() { + return "success"; + } +} +]]></programlisting> +</section> +<section id="TryItOut"> +<?dbhtml filename="TryItOut.html"?> +<title>Try it out</title> +<para>Now save the project and restart the server to make sure that it is properly re-deployed. +Navigate to the OrdersList page and enter &quot;In Process&quot; to the status field to search for +un-processed orders.</para> +<para>Select one order and edit the order and change the &quot;status&quot; field to &quot;in stock&quot; and +click &quot;Done&quot;. Please enter the case exactly as indicated here:</para> +<figure> +<title>Order Edit Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OrderEditPage.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Click the &quot;Process Order&quot; button.</para> +<figure> +<title>Order Details</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OrderDetails.png"/> + </imageobject> +</mediaobject> +</figure> +<para>The business process should lead to the ShipOrderAction bean, which will print out the + &quot;SHIP ORDER&quot; message in the console view tab at the bottom of the IDE screen.</para> + <figure> +<title>Console View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ConsoleView.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Select one order and change the &quot;status&quot; field to &quot;back order&quot; and click &quot;Done&quot;. Please +enter the case exactly as indicated here:</para> +<figure> +<title>Changing Status Field</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ChangingStatusField.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Click the &quot;Process Order&quot; button.</para> +<figure> +<title>Invoking Process Order</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/InvokingProcessOrder.png"/> + </imageobject> +</mediaobject> +</figure> +<para>The business process should invoke the SendRefundAction bean, which will print out the +&quot;SEND REFUND&quot; message in the console view tab at the bottom of the IDE screen.</para> +<figure> +<title>Console Panel</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ConsolePanel.png"/> + </imageobject> +</mediaobject> +</figure> +<para>This example shows a simple example of the powerful jBPM and JBoss Rules runtimes +integrated in a Seam application. We have also see how easy it is build these kinds of +applications using the Red Hat Developer Studio.</para> +</section> +<section id="TroubleshootingOnLinux"> +<?dbhtml filename="TroubleshootingOnLinux.html"?> +<title>Troubleshooting on Linux</title> +<para>Linux users may need to do the following to get the Eclipse distribution to work correctly +on their machines.</para> +<orderedlist> +<listitem>On Red Hat based Linux distributions install the xpLib.i386 package</listitem> +<listitem>ln -s libstdc++.so.5.0.7 libstdc++.so.5</listitem> +<listitem>Open the RHDS perspective. If you see the Help view open, close it and restart RHDS</listitem> +<listitem>If none of these work, do the following +<itemizedlist> +<listitem>Clear the Eclipse log file, &lt;workspace&gt;\.metadata\.log</listitem> +<listitem>Start Eclipse with the -debug option: +<para>eclipse -debug</para></listitem> +<listitem>Post the Eclipse log file (&lt;workspace&gt;\.metadata\.log) on the forums.</listitem> +</itemizedlist> +</listitem> +</orderedlist> +</section> + </chapter> \ No newline at end of file Deleted: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AjaxCRUDApplicationWithSeamAndRichFaces.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AjaxCRUDApplicationWithSeamAndRichFaces.xml 2007-07-23 11:53:37 UTC (rev 2593) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/AjaxCRUDApplicationWithSeamAndRichFaces.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -1,700 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="AjaxCRUDApplicationWithSeamAndRichFaces" xreflabel="AjaxCRUDApplicationWithSeamAndRichFaces"> - <?dbhtml filename="AjaxCRUDApplicationWithSeamAndRichFaces.html"?> - <chapterinfo> - <keywordset> - <keyword>Red Hat Developer Studio</keyword> - <keyword>Seam</keyword> - <keyword>JBoss</keyword> - <keyword>CRUD-application</keyword> - </keywordset> - </chapterinfo> - - <title>Ajax CRUD-application with Seam and Rich Faces</title> -<para>In this chapter we will see how easy it is to build Seam applications and integrate -them with Ajax4jsf and Rich Faces. We will bootstrap the application using Seam Gen which is - a CRUD application generator. Seam Gen can be used from either the command line or via an - Eclipse Plugin. Unlike most application generators, Seam Gen can also be used to - incrementally add more functionality to an existing Seam application.</para> - <para>Seam is an incredibly flexible development framework that can be completely - integrated with a Java EE server or in a simple POJO environment like Tomcat. Seam is - also extremely portable, and has been tested on several popular containers like JBoss, - Tomcat, Weblogic, WebSphere. Seam uses JSF as its view layer and can use either JSP or - Facelets as the presentation layer.</para> - <para>Seam Gen generates all the required layers of an application. It uses JPA as the - persistence layer, POJO&apos;s (Plain Old Java Objects) as the business logic layer and - Facelets as the presentation layer.</para> - <para>We will perform the following steps in this chapter of the tutorial:</para> - <itemizedlist> - <listitem>Creating a Seam Project using Seam Gen</listitem> - <listitem>Generating a Seam application using Seam Gen</listitem> - <listitem>Running the Seam application</listitem> - <listitem>Customizing the generated Seam application</listitem> - <listitem>Adding AJAX features to automatically generated JSF Seam UI components</listitem> - <listitem>Replacing standard JSF UI components with AJAX enabled rich UI components - provided by the Red Hat Developer Studio</listitem> - <listitem>Using AJAX components to do live validation on web pages</listitem> - <listitem>Adding Rich Faces components to a Seam application</listitem> - </itemizedlist> -<section id="CreatingASeamProjectUsingSeamGen"> -<?dbhtml filename="CreatingASeamProjectUsingSeamGen.html"?> -<title>Creating a Seam Project using Seam Gen</title> -<itemizedlist> -<listitem>Stop your JBoss AS Server by clicking on the stop button as shown below. We are - doing this so that the generated application can be deployed properly when the server - starts.</listitem> - </itemizedlist> - <figure> -<title>Stopping JBoss AS Server</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/StoppingServer.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>To create a Seam project, select <emphasis>Seam Gen > Setup/Configuration > Setup </emphasis>to -launch the Seam Gen setup window as shown below. Note: </listitem> -</itemizedlist> -<note> - <title>Note:</title> - <para>If this is the first time you run -Seam Gen a file dialog will be shown. In this you need to select &lt;seam&gt;/seam-gen/build.xml - so the plugin knows which seam-gen to use.</para> - </note> -<para></para> - - <figure> -<title>Seam Gen Setup Window</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/SeamGenSetup.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Fill the items in the dialog as shown below and select the <emphasis>OK</emphasis> button.</para> -<table> - <title>Filling Project Items</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Field Name</entry> - <entry>Field Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>Project</entry> - <entry>EclipseCon</entry> - </row> - <row> - <entry>Seam project workspace</entry> - <entry>&lt;your project directory&gt;</entry> - </row> - <row> - <entry>JBoss AS Home directory</entry> - <entry>&lt;JBoss AS Home Dir&gt;</entry> - </row> - <row> - <entry>Driver Location</entry> - <entry>&lt;seam>/&lt;seam-gen&gt;/lib/hsqldb.jar</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The plug-in will initialize the Seam Gen ant tasks that simplify all key Seam - operations. We will invoke several of these ant tasks via the Seam Eclipse Plugin - throughout this tutorial.</para> - <para>The plug-in will also prompt you to create a project. Select &quot;Yes&quot; to create a - Project. This step will create not only an Eclipse project but also all the required - artifacts to get you started.</para> - <para>The plug-in will also prompt you create a database connection. Select - &quot;Yes&quot; to create a WTP Database connection that connects to the default HSQL DB - instance that we have set up. If you are using any other database then set up the - appropriate database settings in the Seam Gen setup window.</para> - <para>At the end of this step you will see an Eclipse project called &quot;EclipseCon&quot; - as shown below. This project has all the necessary elements required to deploy - a Seam application.</para> - <figure> -<title>EclipseCon Project Structure</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/EclipseConProjectStructure.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Start the application server. Open your favorite browser and point to the -following URL http://localhost:8080/EclipseCon. You should see the following page:</listitem> -</itemizedlist> -<figure> -<title>Created Project</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/CreatedProject.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Congratulations! You have written your first Seam application.</para> -<itemizedlist continuation="continues"> -<listitem>Let us take a look at the database connection that was created by the Eclipse - Plugin and browse the database provided. The database connection view should now have a - connection to our sample database as shown below.</listitem> - </itemizedlist> - <figure> -<title>Connections View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ConnectionsView.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Right click on the connection > Reconnect. Just specify &quot;sa&quot; as the user id. The password - field should be blank.</para> - <para>You should now be able to browse the database and see the meta-data and query data using SQL. - Your meta-data should look like the following:</para> - <figure> -<title>Meta-data View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/Metadata.png"/> - </imageobject> -</mediaobject> -</figure> -</section> -<section id="GeneratingACRUDApplicationUsingSeamGen"> -<?dbhtml filename="GeneratingACRUDApplicationUsingSeamGen.html"?> -<title>Generating a CRUD application using Seam Gen</title> -<itemizedlist> -<listitem>The next step in our exercise is to generate a full blown application using Seam Gen. -This application will generate CRUD pages and Search pages for all the entities in the database. -Click on Seam Gen > Generate Entities. Seam Gen will connect to the database we defined in the - setup part of the application and generate all the required components.</listitem> - <listitem>Since Seam Gen is generating files on the file system that Eclipse does not know - about, right click on the project name on your project and choose the Refresh item. This will let - Eclipse know that there are new files and get them updated in the Eclipse project and deployed - in the JBoss instance.</listitem> - <listitem>Restart you application server, just in case those files have not been properly - synchronized with the application server.</listitem> - <listitem>Point your favorite browser to the following URL http://localhost:8080/EclipseCon. - You will see the following page:</listitem> - </itemizedlist> - <figure> -<title>EclipseCon Project</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/CreatedProject12.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let us now look at one of the entities and see what has been generated. Click on the - &quot;Offices List&quot; to see a search page that allows you to filter the list and the list of all the - offices in the database.</listitem> - <listitem>Type in USA in the country field and click on Search to get a list of offices in the - USA as shown below.</listitem> - </itemizedlist> - <figure> -<title>Search Panel</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/SearchPanel.png"/> - </imageobject> -</mediaobject> -</figure> - -<itemizedlist continuation="continues"> -<listitem>Let us now check out the editing capability of the generated Seam application. Select - the first office code and click on the Edit button. You will be prompted for a userID and - password. Use &quot;seamuser&quot; for both user and password. You should at this point see the edit page - as shown below. Notice that the NOT NULL columns in the database table are automatically marked - with the red * to indicate that they are required.</listitem> - </itemizedlist> - <figure> -<title>Generated Edit Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/GeneratedEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Change a few things and save changes. This should update the record in the database. - There you have it. A simple and easy way to bootstrap your applications.</listitem> - <listitem>Let us look at how validations are done in Seam. Go back to and edit another office - record and this time leave the city blank and click on the Save button. You will see the default - Seam validations get triggered. In this case the &quot;value required&quot; validation is fired as shown - below.</listitem> - </itemizedlist> -<figure> -<title>Error Reporting</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ValidationInEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -</section> -<section id="CustomizingTheGeneratedApplication"> -<?dbhtml filename="CustomizingTheGeneratedApplication.html"?> -<title>Customizing the generated application</title> -<itemizedlist> -<listitem>Let us look at a couple of simple things we can change in the generated application - to show you that the generated application can be customized. Let us start by changing the edit - page that we just saw. We will clean up the labels using the Facelet designer as shown below. - Open the view directory in your project and double click on the OfficeEdit.xhtml file.</listitem> -</itemizedlist> -<figure> -<title>Facelet Designer</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/FaceletDesigner.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Unlike other WYSIWYG editors which developers tend to hate, the visual designers in Red Hat - Developer Studio are designed for developers to rapidly find their way in a source file, while - still allowing them to visually look at a document.</para> - -<itemizedlist continuation="continues"> -<listitem>To change a label text, click on a label in the designer. This will position the - cursor at the correct location in the source view. Type the new label there. The designer does - not force the developer to use the WYSIWIG environment. Change all the labels for the edit page.</listitem> - </itemizedlist> - <para>Once you save the page, the IDE automatically rebuilds the application and re-deploys it. - So, just reload your browser and you should see an updated web page like the following. If for - some reason the re-deployment did not work, stop and restart the server normally resolves the issue.</para> - <figure> -<title>Edit Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/EditPage.png"/> - </imageobject> -</mediaobject> -</figure> -</section> -<section id="UsingHibernateToolsToInteractWithTheJPAEntities"> -<?dbhtml filename="UsingHibernateToolsToInteractWithTheJPAEntities.html"?> -<title>Using Hibernate tools to interact with the JPA Entities</title> -<para>As part of generating the application, Seam Gen also generates JPA entities that are used - to interact with the database. Let us quickly take a look at Hibernate tools and see how we can - interact with the database using HQL and the Hibernate Criteria API.</para> - <itemizedlist> - <listitem>Open the Hibernate Configurations View. You should be able to open the console like - the other views we have seen so far in the tutorial. Your view should resemble the following:</listitem> - </itemizedlist> - <figure> -<title>Hibernate Configurations View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateConfigurationsView.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Before we run the HQL, let us open up the &quot;Hibernate Query Result&quot; and the &quot;Hibernate - Dynamic SQL Preview&quot; views. You should be able to do that in a manner similar to other views we - have opened in this tutorial. Alternatively you can open the Hibernate Console Perspective where - these views are opened up by default.</listitem> - <listitem>Click on the &quot;HQL&quot; icon in the &quot;Hibernate Configurations&quot; view. This will open up - the HQL Designer view as shown below. Also, select &quot;EclipseCon&quot; from the drop down menu next to - the green &quot;run&quot; button.</listitem> - </itemizedlist> - <figure> -<title>HQL Designer View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HQLDesignerView.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Type in a simple query as shown above &quot;from Offices o&quot; and click on the green &quot;run&quot; - button. You should see the result of the HQL query in the &quot;Hibernate Query Result&quot; window as - shown below.</listitem> - </itemizedlist> - <figure> -<title>Hibernate Query Result Window</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateQueryResultWindow.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Click on any of the objects in the result and you should be able see the contents of - the objects in the Property view as shown below. If you don&apos;t have the view open in your - perspective, you can open this view like all other views in this tutorial.</listitem> - </itemizedlist> - <figure> -<title>Property View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/PropertyView.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Select the &quot;Hibernate Dynamic SQL Preview&quot; view to the generated SQL. This is a great tool -to see the SQL being generated by Hibernate for your HQL. Not only is this a great debugging tool, - it is also a great way to optimize your HQL queries.</para> - <figure> -<title>Hibernate Dynamic SQL Preview</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateDynamicSQLPreview.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let us try a slightly more complex query. Type in the following query in the query -window and see how the query result changes and the SQL Preview changes.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[select city, state, postalcode - from Offices o - where country = 'USA' -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Let us try the Hibernate criteria APIs next. To use Hibernate Criteria APIs click on -the &quot;CRI&quot; button in the Hibernate Configurations View. This will open the Criteria API designer -view. Type in this simple criteria query as shown below and click on the green run button to see - the results. Also, select &quot;EclipseCon&quot; from the drop down menu next to the green &quot;run&quot; button.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) -]]></programlisting> -<para>The results will be very similar to the HQL query except that the criteria query does not -generate the SQL in the &quot;Hibernate Dynamic SQL Preview&quot; view.</para> -<itemizedlist continuation="continues"> -<listitem>Let us try something a little more complex. Let us filter all offices in the USA as -shown below. The results of this query should be very similar to the results of the HQL.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) - .add(Restrictions.eq("country", "USA")) ; -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Finally let us visually see the entity model of the generated JPA objects. Before we - do that, open the &quot;Hibernate Entity Model&quot; view and select the &quot;Configurations&quot; option in the - &quot;Hibernate Configurations&quot; view. The plug-in will show all the entities in a visual format. - You can either manually align your objects or click on the &quot;Layout&quot; button on the right of the - &quot;Hibernate Entity Model&quot; view to generate a default layout.</listitem> - </itemizedlist> - <figure> -<title>Hibernate Entities</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateEntities.png"/> - </imageobject> -</mediaobject> -</figure> - -</section> -<section id="AddingAJAXAndRichUIFeaturesToASeamApplication"> -<?dbhtml filename="AddingAJAXAndRichUIFeaturesToASeamApplication.html"?> -<title>Adding AJAX and rich UI features to a Seam application</title> -<para>A key feature of JBoss Seam and the Red Hat Developer Studio is that they make AJAX and rich - UI web applications a breeze to develop. In this section of the tutorial, we will show you how - to:</para> - <itemizedlist> - <listitem>Add AJAX features to automatically generated JSF Seam UI components</listitem> - <listitem>Replace standard JSF UI components with AJAX enabled rich UI components provided by the - Red Hat Developer Studio</listitem> - <listitem>Use AJAX components to do live validation on web pages</listitem> - </itemizedlist> - <section id="AddingAJAXFeaturesToGeneratedUIComponents"> -<?dbhtml filename="AddingAJAXFeaturesToGeneratedUIComponents.html"?> -<title>Adding AJAX features to generated UI components</title> -<para>Let us now try to add some AJAX features to the generated Seam application. Click on the - Payments List link on the top of the page. You will see a search page as shown below.</para> - <figure> -<title>Search Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/SearchPage.png"/> - </imageobject> -</mediaobject> -</figure> -<para>You can search for any &quot;checknumber&quot; by typing in the number or by paging through the list - of payments. But what if you only knew a few of the digits/alphabets in the &quot;checknumber&quot;? It - would be very useful to filter the list based on that. AJAX provides very useful techniques to - build these types of applications and Ajax4jsf provides the building blocks to simplify these - techniques.</para> - <para>Double Click on the PaymentsList.xhtml to open the visual facelet designer. You will - notice that in the beginning of the source, Seam Gen has already add the tag library references - to Ajax4jsf and RichFaces as shown below.</para> - <programlisting role="JAVA"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" - xmlns:rich="http://richfaces.ajax4jsf.org/rich" - template="layout/template.xhtml"> -]]></programlisting> -<para>Next, locate the check number input field. We need to add AJAX to this field. Basically, -as we type we want to update the table. Adding AJAX functionality usually requires two things:</para> -<itemizedlist> -<listitem>Letting the framework know on which event to send an AJAX request to the server.</listitem> -<listitem>Specifying what component(s) to update with the output from the server.</listitem> -</itemizedlist> -<para>Ajax4jsf provides a simple JSF component <emphasis role="bold"><property>&lt;aj4:support&gt;</property></emphasis> that simplifies this process. Let us -take our example and add AJAX to it.</para> -<itemizedlist> -<listitem>Click on the checknumber field in the visual designer, it will position you at the -correct location in the source. You will notice that the inputText tag does not have a closing -tag. Let us add a closing tag to the input text field as shown below.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" reRender="paymentsList"/> - </h:inputText> -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Now let us add the AJAX support tag to let Ajax4jsf know that when the user presses a - key we want to go to the server to get a list of payments that match the characters entered in - the checknumber text box. Add the tag that is highlighted below to the inputText tag.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" reRender="paymentsList"/> - </h:inputText> -]]></programlisting> -<para>This tag is pretty self explanatory, it posts the server when a key is pressed and then - takes the response from the server and re-renders the section of the page that has an id of - &quot;paymentsList&quot;.</para> - <itemizedlist continuation="continues"> -<listitem>If you follow along in the page, you will see that the section that displays the -results is in a div tag that has an id of &quot;paymentsList&quot;</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<div class="results" id="paymentsList"> - <h3>search results</h3> - <h:outputText value="No payments exists" - rendered="#{empty paymentsList.resultList}"/> - ... - </div> -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Save the changes and refresh your browser. You will see that as you type characters -in the checknumber field, all payments that begin with those characters will be displayed in the -table automatically.</listitem> -</itemizedlist> -<figure> -<title>Data Fields</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/DataFields.png"/> - </imageobject> -</mediaobject> -<mediaobject> - <imageobject> - <imagedata fileref="images/Buttons.png"/> - </imageobject> -</mediaobject> -</figure> -<para>But there is still one more problem in this page, you will see that the &quot;Next&quot; and - &quot;Previous&quot; buttons will be displayed even for search results that are small as shown above.</para> - <itemizedlist continuation="continues"> -<listitem>The tag that we added in the previous step only updates the table. Let us add an AJAX -region around the page buttons at the bottom of the table. This will allow Ajax4jsf to update -those buttons independently.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<a4j:outputPanel ajaxRendered="true"> - <div class="tableControl"> - ... - </div> - </a4j:outputPanel> -]]></programlisting> -<para>Add an <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> tag around the page buttons as shown above and run the page again. - If the result list is small, you will see that the page buttons are no longer visible as shown - below.</para> - <figure> -<title>Datatable With No Page Buttons</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/NoButtons.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let add one more thing to complete this part of the sample. When we type a character in - the &quot;checknumber&quot; field, there is no visual feedback to the user that there is a request being - made to the server.</listitem> - </itemizedlist> - <para>Ajax4jsf has a pre-built tag <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> that allows you to either render a text or an - image in response to an AJAX event. Add the following code, right after the end of the - <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag.</para> - <programlisting role="JSP"><![CDATA[<a4j:status> - <f:facet name="start"> - <h:graphicImage value="/img/ajax-loader.gif" style="border: 1px solid #E0E0E0"/> - </f:facet> - </a4j:status> -]]></programlisting> -<para>Save changes to the page and refresh the browser. You will see the image when the AJAX -request is active. The image will disappear as soon as the response is received.</para> -<itemizedlist continuation="continues"> -<listitem>Finally, let us place the image beside the &quot;checknumber&quot; text box. Place a -<emphasis role="bold"><property>&lt;h:panelGroup&gt;</property></emphasis> around the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> tags as shown below. -Save changes and refresh the browser. You should see the image right next to the text box.</listitem> - </itemizedlist> - <programlisting role="JSP"><![CDATA[<h:panelGroup> - <h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" - reRender="paymentsList"/> - </h:inputText> - <a4j:status> - <f:facet name="start"> - <h:graphicImage value="/img/ajax-loader.gif" - style="border: 1px solid #E0E0E0"/> - </f:facet> - </a4j:status> - </h:panelGroup> -]]></programlisting> -<para>Although this example was a bit long, it shows how easy it is to add AJAX capabilities to -an existing Seam application.</para> -</section> -<section id="AddingRichfacesComponentsToaSeamApplication"> -<?dbhtml filename="AddingRichfacesComponentsToaSeamApplication.html"?> -<title>Adding RichFaces components to a Seam application</title> -<para>Now that we have seen how AJAX can bring interactivity to an application, let us add rich -controls that will improve the user experience. RichFaces provides numerous rich controls that -can be added to an application. In this section we will add spinner and slider controls that -allow users to change numerical values without using the keyboard.</para> -<para>Double Click on the OrderdetailsEdit.xhtml to open the visual facelet designer. You will - notice that in the beginning of the source, Seam Gen has already included the tag library - references to Ajax4jsf and RichFaces as shown below.</para> - <programlisting role="JSP"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" - xmlns:rich="http://richfaces.ajax4jsf.org/rich" - template="layout/template.xhtml"> -]]></programlisting> -<para>In this page, we are going to replace the &quot;quantityordered&quot; text box with the spinner - control.</para> - <itemizedlist> - <listitem>In the visual view of the page, click on the &quot;quantityordered&quot; text box, this will - select the appropriate markup in the source view. Delete the selected markup.</listitem> - </itemizedlist> - <figure> -<title>Deleting Selected Markup</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/DeletingSelectedMarkup.png"/> - </imageobject> -</mediaobject> -</figure> -<para>We will replace the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag with a pre-built <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> tag. - The spinner control tag is very simple to use and like all other JSF controls, it has a value - attribute that can be bound to any JSF Managed Bean or Seam component. The designer allows you - to visually find all the beans available as shown below. Right - click on the <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> input field and select &quot;<emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> Attributes&quot;.</para> - <figure> -<title>Replacing Tags</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ReplacingTags.png"/> - </imageobject> -</mediaobject> -</figure> -<para>The minValue and maxValue are self explanatory, they represent the minimum and maximum - values for the spinner. Place the following tag in your page.</para> - <programlisting role="JSP"><![CDATA[<rich:inputNumberSpinner - value="#{orderdetailsHome.definedInstance.quantityordered}" - inputStyle="width:30px; height:20px" - minValue="0" - maxValue="100" - required="true"/> -]]></programlisting> - -<itemizedlist continuation="continues"> -<listitem>Save changes and refresh the browser page. Your output page should look like this:</listitem> -</itemizedlist> -<figure> -<title>Output Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OutputPage.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Although this is not the best situation to use a slider, let us take a quick look at -another RichFaces control <emphasis role="bold"><property>&lt;rich:inputNumberSlider&gt;</property></emphasis>. The slider control is similar to the the -spinner control; it is bound to the same object. Replace the spinner with the following markup. -Save the page and refresh your browser window.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<rich:inputNumberSlider - value="#{orderdetailsHome.definedInstance.quantityordered}" - styleClass="slider" - width="200"/> -]]></programlisting> -<figure> -<title>InputNumberSlider Settings</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/InputNumberSliderSettings.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Seam Gen also generates a date picker control for all date fields in an edit page. - Click on &quot;Order List&quot; and edit one of the orders to see an example of the date picker control - that is bundled with Seam.</listitem> -</itemizedlist> - -<figure> -<title>Order List</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OrderedList.png"/> - </imageobject> -</mediaobject> -</figure> - -</section> -<section id="ValidatingTheAJAXWay(LiveValidations)"> -<?dbhtml filename="ValidatingTheAJAXWay(LiveValidations).html"?> -<title>Validating the AJAX way (Live Validations)</title> -<para>Seam Gen also generates field validation code that leverages AJAX techniques, by providing - immediate feedback to users who use these applications. To see an example of this, go back to - the Office Edit page and leave the city blank and tab out of the field. Seam will immediately - validate the field and tell you that the value is required.</para> - <figure> -<title>Office Edit Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OfficeEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -<para>To provide this functionality for every required field in the page Seam generates the - following markup:</para> -<programlisting role="JSP"><![CDATA[<s:decorate id="cityDecoration"> -<h:inputText id="city" - required="true" - size="50" - maxlength="50" - value="#{officesHome.instance.city}"> - <a:support event="onblur" reRender="cityDecoration"/> - </h:inputText> - </s:decorate> -]]></programlisting> -<para>Seam uses Ajax4jsf to make a server side call to validate the field.</para> -</section> -</section> - -<section id="OtherRelevantResourcesOnTheTopic2"> -<?dbhtml filename="OtherRelevantResourcesOnTheTopic2.html"?> -<title>Other relevant resources on the topic</title> -<para>Seam on JBoss: <ulink url="http://www.jboss.com/products/seam">Seam Framework</ulink></para> - -<para>Ten Good Reasons to use Seam: <ulink url="http://www.jboss.com/products/seam/whyseam">Why Seam</ulink></para> -<para>Getting Started: <ulink url="http://labs.jboss.com/jbossseam/gettingstarted">Getting Started with JBoss Seam</ulink></para> -<para>Wiki: <ulink url="http://www.jboss.com/wiki/Wiki.jsp?page=JBossSeam">JBoss Wiki</ulink></para> -<para>FAQ: <ulink url="http://labs.jboss.com/jbossseam/faq/index.html">JBoss Seam FAQ</ulink></para> -<para>Downloads: <ulink url="http://labs.jboss.com/jbossseam/download">JBoss Seam Downloads</ulink></para> -<para>Jira: <ulink url="http://jira.jboss.org/jira/browse/JBSEAM">Jira issue tracker</ulink></para> -<para>Rules Framework: <ulink url="http://www.jboss.com/products/rules">JBoss Rules</ulink></para> -</section> -</chapter> Deleted: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/BusinessProcessAndRulesApplication.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/BusinessProcessAndRulesApplication.xml 2007-07-23 11:53:37 UTC (rev 2593) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/BusinessProcessAndRulesApplication.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -1,480 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="BusinessProcessAndRulesApplication" xreflabel="BusinessProcessAndRulesApplication"> - <?dbhtml filename="BusinessProcessAndRulesApplication.html"?> - <chapterinfo> - <keywordset> - <keyword>Business process</keyword> - <keyword>Seam</keyword> - <keyword>JBoss Rules</keyword> - <keyword>CURD-application</keyword> - </keywordset> - </chapterinfo> - - <title>Business process and rules application</title> - <para>Rules and business processes are important components in many enterprise applications. - They help business analysts to get involved in the design and implementation of the software - project. Rules and business processes are also essential to complex internal states of large, - multi-user systems. The JBoss Rules engine (formerly known as Drools) and jBPM business - process engine are two production-ready open source products supported by Red Hat. It is - very easy to incorporate rules and business processes into a Seam web application using the - Red Hat Developer Studio. In this section, we further re-factor the CRUD application we - already have and add support for an &quot;order management&quot; process. The user scenario is to - simulate the following process and rules:</para> - <itemizedlist> - <listitem>The site administrator logs in and sees a list of outstanding orders</listitem> - <listitem>She goes through the inventory (by hand or using another computer system) and - determines the availability of the products in each order. She enters that information to - each order.</listitem> - <listitem>She starts a process for each order, which determines whether to ship the order - or refund the order based on a business rule applied to the availability status. For - instance, an &quot;in stock&quot; status triggers a &quot;ship&quot; action while the &quot;back order&quot; status - triggers a &quot;refund&quot; action.</listitem> - <listitem>When the business process reaches the &quot;ship&quot; or &quot;refund&quot; state, it will take - appropriate actions (e.g., to submit shipping orders to Fedex or to contact the credit - card company for refund). In this simple case, we will just print out a message on the - console to prove that we can execute any code in those stages.</listitem> - </itemizedlist> - <para>While this process sounds simple, it is the basis for very complex business - processes. In this section of the tutorial, we will show you how this is done via the - following steps:</para> - <itemizedlist> - <listitem>Add a rule definition to the application</listitem> - <listitem>Add a business process that uses that rule to the application</listitem> - <listitem>Start the business process from a web action</listitem> - </itemizedlist> -<section id="ImportConfigurationFilesAndJavaCode"> -<?dbhtml filename="ImportConfigurationFilesAndJavaCode.html"?> -<title>Import configuration files and Java code</title> -<para>Before we start, we need to import some configuration and Java files for the demo project. -Those files are very simple and we will review them as we go along with the tutorial. We import -them here to reduce potential typos and other errors in the tutorial.</para> -<orderedlist> -<listitem>Choose the <emphasis>File > Import ...</emphasis> menu and then select <emphasis>General > Existing</emphasis> project into workspace and -click on the Next button.</listitem> -</orderedlist> -<figure> -<title>Importing Project</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ProjectImporting.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>To make this demo a little more manageable we have already created some demo code -that is available in the rules-bpm directory of your tutorial distribution code. It is - located in the root directory of the distribution. Select the rules-bpm directory and check - the &quot;Copy projects into the workspace&quot; directory check box.</listitem> -</orderedlist> -<para>You will have a different directory on your machine than the screen shot shown below.</para> -<figure> -<title>Selecting Directory To Import</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ImportDirectory.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>After this step you will see a new project called &quot;rules-bpm&quot;. If you expand that -directory, you will see numerous files as shown below. We will look at these files in this - section of the demo. We will first start by copying these files into our EclipseCon project.</listitem> -</orderedlist> - -<figure> -<title>Project Structure</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ProjectStructure.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>Right click on the rules-bpm/build.xml file, and select <emphasis>Run AS ... > Ant</emphasis> Build.</listitem> -</orderedlist> - -<figure> -<title>AntBuild</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/AntBuild.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>Right click on the EclipseCon project and select Refresh from the menu to pick up - the changes made to the demo application. The rules-bpm/build.xml script copies a bunch of files - into your existing EclipseCon project. We will look at them soon.</listitem> -</orderedlist> -</section> -<section id="CreateARuledefinition"> -<?dbhtml filename="CreateARuledefinition.html"?> -<title>Create a rule definition</title> -<para>In this section, we create a business rule that can be used in junction with the business - process. When the rule is executed, it checks the status of the currently selected order. If the - order status is &quot;in stock&quot;, meaning that a person has check off line and verified the - availability of the product ordered, the system changes the order status to &quot;ship&quot;, meaning - that someone will now ship the product as the next step in the process. If the order status - is &quot;back order&quot;, the rule changes the order status to &quot;refund&quot; automatically to trigger the - business process of refunding.</para> - <orderedlist> - <listitem>Select the<emphasis> EclipseCon/resources </emphasis>directory. That is where we are going to put the - rules definition file.</listitem> - <listitem>Select the following menu actions: <emphasis>File > New > Other ... > JBoss Rules > New - Rules Resource</emphasis> to bring up the JBoss Rules wizard.</listitem> - </orderedlist> - <figure> -<title>New Rules File</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/NewRulesFile.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>Fill out the above window with the following values.</listitem> -</orderedlist> -<table> - <title>Rule Table</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Field Name</entry> - <entry>Field Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>File Name</entry> - <entry>process-order.drl</entry> - </row> - <row> - <entry>Type of Rule Resource</entry> - <entry>New DRL (rule package)</entry> - </row> - <row> - <entry>Rule Package Name</entry> - <entry>process.order</entry> - </row> - </tbody> - </tgroup> - </table> - <orderedlist continuation="continues"> -<listitem>Replace the content of the process-order.drl file with the follow rule.</listitem> -</orderedlist> -<programlisting role="JAVA"><![CDATA[package process.order - import com.mydomain.EclipseCon.Orders; - -rule "Ship order rule" - when - order : Orders(status == "in stock") - then - order.setStatus("ship"); -end - -rule "Refund order rule" - when - order : Orders(status == "back order") - then - order.setStatus("refund"); -end -]]></programlisting> -<para>Notice that the IDE automatically highlights the syntax and provides auto-completion help. - You may wonder how Seam knows to load the process-order.drl file for the application.</para> - <para>If you look in the <emphasis>resources/WEB-INF/components.xml</emphasis> file we copied from the imported - rules-bpm project. It has an element pointing to the process-order.drl file.</para> - <programlisting role="XML"><![CDATA[<drools:rule-base name="securityRules"> - <drools:rule-files> - <value>/security.drl</value> - </drools:rule-files> - </drools:rule-base> -]]></programlisting> -</section> -<section id="CreateABusinessProcessDefinition"> -<?dbhtml filename="CreateABusinessProcessDefinition.html"?> -<title>Create a business process definition</title> -<para>Next, let&apos;s create a business process that manages the order process. The business process - essentially specifies a sequence of actions that has to happen before an order is shipped or - refunded. Since the business analyst typically designs this process, it is very high level and - can be drawn up in a GUI designer.</para> - <orderedlist> - <listitem>Select the<emphasis> EclipseCon/resources </emphasis>folder and select menu actions <emphasis>File > New > File</emphasis>. - Add a new file called process-order.jpdl.xml as shown below:</listitem> - </orderedlist> - <figure> -<title>Creating New File Resource</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/CreatingNewFileResource.png"/> - </imageobject> -</mediaobject> -</figure> - -<orderedlist continuation="continues"> -<listitem>Add the following content to the process-order.jpdl.xml file. It is an empty jBPM -process definition, and allows us to use the jBPM visual designer to further edit it.</listitem> -</orderedlist> -<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> -<process-definition - xmlns="" name="process-order"> -</process-definition> -]]></programlisting> -<orderedlist continuation="continues"> -<listitem>Right click on the process-order.jpdl.xml file and select <emphasis>Open with ... > jBPM -Graphical Process Designer</emphasis>.</listitem> -</orderedlist> -<figure> -<title>Opening Graphical Process Designer</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/GraphicalProcessDesigner.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>In the designer, drag and drop nodes and transition lines until you have a process - shown in the following image. This is a high level process and aimed at business level non - technical users.</listitem> -</orderedlist> -<para>To draw a node, click on the type of the node in the palette. You should be able to see -that based on the icon on the node as shown below. Draw a rectangle on the canvas and the - appropriate node will be rendered.</para> - <para>To draw a transition click on the transition icon in the palette, choose the source node - and then the destination node. This will draw a transition from the source to the destination.</para> - <para>To change the name on the node or transition, select the object and change the name in - the properties view or simply double click on the node or the transition line to change it.</para> - <figure> -<title>Diagram View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/DiagramView.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>Save this file. You can click on the Source tab to view the generated XML file for - the process.</listitem> -</orderedlist> -</section> -<section id="AssociateProcessNodesWithJavaCode"> -<?dbhtml filename="AssociateProcessNodesWithJavaCode.html"?> -<title>Associate process nodes with Java code</title> -<para>With the business process in the designer, we can now associate each node with Java code. - The Java code is executed when the node is reached in the process, and the Java code determines - the outcome of each node – hence the next node in the process.</para> - <para>Let&apos;s go through the exercise for the &quot;Check Inventory&quot; node first.</para> - <orderedlist> - <listitem>Right click on the &quot;Check Inventory&quot; node in the designer and select <emphasis>Add - Actions > Node Enter </emphasis>from the menu as shown below.</listitem> - </orderedlist> - <figure> -<title>Node Entering</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/NodeEntering.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>In the Outline view tab, open the tree view of process-order > Check Inventory > -node enter, and you will see action1. The Outline view may be hidden or on the left side of the - IDE.</listitem> -</orderedlist> -<figure> -<title>Outline View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OutlineView.png"/> - </imageobject> -</mediaobject> -</figure> -<orderedlist continuation="continues"> -<listitem>Double click on action1 to bring up the wizard. Select Handler on the left and enter - com.mydomain.EclipseCon.process. CheckInventoryAction as the class and bean as the type as shown - below. You can can also search for the class by clicking on the <emphasis>Browse...</emphasis> button.</listitem> -</orderedlist> -<figure> -<title>Action Handler</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ActionHandler.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Explanation: Now, you must wonder where this -com.mydomain.EclipseCon.process.CheckInventoryAction class come from It comes from the -eclipsecon-rules-bpm project we imported. The Java class has a single method that is executed -when the &quot;Check Inventory&quot; node is reached in the process. The method just fires the rule we -previously defined in process-order.drl. After the rule is executed, it updates the -&quot;inventoryStatus&quot; component. Here is the method:</para> -<programlisting role="JAVA"><![CDATA[public void execute(ExecutionContext ctx) throws Exception { - - //get a handle to the rules engine - Component c = (Component) Contexts.getApplicationContext().get( - "orderWorkingMemory.component"); - WorkingMemory wm = (WorkingMemory) ((ManagedWorkingMemory) c - .newInstance()).getWorkingMemory(); - - //get the ordersHome variable that was set in OrderProcessor. - OrdersHome order = (OrdersHome) ctx.getVariable("ordersHome"); - - //Assert Orders to working memory and fire rules - wm.assertObject(order.getInstance()); - wm.fireAllRules(); - - - //persist the updated Orders object - order.persist(); - - //set inventory status so decision node knows what to do - ctx.setVariable("inventoryStatus", order.getInstance().getStatus()); - System.out.println("CHECK INVENTORY - STATUS: " - + order.getInstance().getStatus()); -} -]]></programlisting> -<para>The &quot;inventoryStatus&quot; component is then used in the &quot;Inventory Decision&quot; node to determine -which node to go to next. To do that, open the process-order.jpdl.xml file in the text editor and - change the node from this</para> - <programlisting role="XML"><![CDATA[<decision name="Inventory Decision"> - <transition name="ship" to="Ship Order"></transition> - <transition name="refund" to="Refund Order"></transition> - </decision> -]]></programlisting> -<para>to this:</para> -<programlisting role="XML"><![CDATA[<decision name="Inventory Decision" expression="#{inventoryStatus}"> - <transition name="ship" to="Ship Order"></transition> - <transition name="refund" to="Refund Order"></transition> - </decision> -]]></programlisting> -<para>Now, let&apos;s repeat the exercise to assign handler Java classes to the &quot;Ship Order&quot; and &quot;Refund Order&quot; nodes. </para> -<itemizedlist> -<listitem>Associate &quot;Ship Order&quot; node with the com.mydomain.EclipseCon.process.ShipOrderAction -bean</listitem> -<listitem>Associate &quot;Refund Order&quot; node with the com.mydomain.EclipseCon.process.SendRefundAction bean</listitem> -</itemizedlist> -<para>As we described earlier, in a real world system, those two nodes would invoke Java code - that perform real shipping and refunding tasks. But here we just print out a message as a proof - of concept. You can look into their Java classes if you have time.</para> -</section> -<section id="StartTheProcessFromAWebAction"> -<?dbhtml filename="StartTheProcessFromAWebAction.html"?> -<title>Start the process from a web action</title> -<para>Finally, we need a &quot;hook&quot; to start the entire business process. We will add a new Process - Order button to the Orders.xhtml file.</para> - <para>You can add the new button right next to the existing &quot;Add orderdetails&quot; button. - Copy/paste the following button code in the actionButtons region:</para> - <programlisting role="JSP"><![CDATA[<s:button id="buttonId" value="Process Order" - action="#{orderProcessor.startProcess}" - view="/Orders.xhtml"/> -]]></programlisting> -<para>Explanation: When you click on the Process Order button, Seam invokes -the #{orderProcessor.startProcess} method, which in turn, starts the business process. The Java -code for the #{orderProcessor} component is in the com.mydomain.EclipseCon.process.OrderProcessor -class. Like other Java source files in the process package, the OrderProcessor.java is already -copied to the EclipseCon project when you run the build.xml script from the imported rules-bpm - project. Here is the content of the OrderProcessor.java file. The startProcess() method, which - is invoked from the Process Order button, starts the process-order process we just created.</para> -<programlisting role="JAVA"><![CDATA[@Name("orderProcessor") -public class OrderProcessor { - - //Set the Orders object as a jBPM context variable - @In(create = true) - @Out(scope = ScopeType.BUSINESS_PROCESS) - OrdersHome ordersHome; - - //Execute the jBPM process - @CreateProcess(definition = "process-order") - public String startProcess() { - return "success"; - } -} -]]></programlisting> -</section> -<section id="TryItOut"> -<?dbhtml filename="TryItOut.html"?> -<title>Try it out</title> -<para>Now save the project and restart the server to make sure that it is properly re-deployed. -Navigate to the OrdersList page and enter &quot;In Process&quot; to the status field to search for -un-processed orders.</para> -<para>Select one order and edit the order and change the &quot;status&quot; field to &quot;in stock&quot; and -click &quot;Done&quot;. Please enter the case exactly as indicated here:</para> -<figure> -<title>Order Edit Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OrderEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Click the &quot;Process Order&quot; button.</para> -<figure> -<title>Order Details</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OrderDetails.png"/> - </imageobject> -</mediaobject> -</figure> -<para>The business process should lead to the ShipOrderAction bean, which will print out the - &quot;SHIP ORDER&quot; message in the console view tab at the bottom of the IDE screen.</para> - <figure> -<title>Console View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ConsoleView.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Select one order and change the &quot;status&quot; field to &quot;back order&quot; and click &quot;Done&quot;. Please -enter the case exactly as indicated here:</para> -<figure> -<title>Changing Status Field</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ChangingStatusField.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Click the &quot;Process Order&quot; button.</para> -<figure> -<title>Invoking Process Order</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/InvokingProcessOrder.png"/> - </imageobject> -</mediaobject> -</figure> -<para>The business process should invoke the SendRefundAction bean, which will print out the -&quot;SEND REFUND&quot; message in the console view tab at the bottom of the IDE screen.</para> -<figure> -<title>Console Panel</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ConsolePanel.png"/> - </imageobject> -</mediaobject> -</figure> -<para>This example shows a simple example of the powerful jBPM and JBoss Rules runtimes -integrated in a Seam application. We have also see how easy it is build these kinds of -applications using the Red Hat Developer Studio.</para> -</section> -<section id="TroubleshootingOnLinux"> -<?dbhtml filename="TroubleshootingOnLinux.html"?> -<title>Troubleshooting on Linux</title> -<para>Linux users may need to do the following to get the Eclipse distribution to work correctly -on their machines.</para> -<orderedlist> -<listitem>On Red Hat based Linux distributions install the xpLib.i386 package</listitem> -<listitem>ln -s libstdc++.so.5.0.7 libstdc++.so.5</listitem> -<listitem>Open the RHDS perspective. If you see the Help view open, close it and restart RHDS</listitem> -<listitem>If none of these work, do the following -<itemizedlist> -<listitem>Clear the Eclipse log file, &lt;workspace&gt;\.metadata\.log</listitem> -<listitem>Start Eclipse with the -debug option: -<para>eclipse -debug</para></listitem> -<listitem>Post the Eclipse log file (&lt;workspace&gt;\.metadata\.log) on the forums.</listitem> -</itemizedlist> -</listitem> -</orderedlist> -</section> - </chapter> \ No newline at end of file Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/CURDAppWalkthrough.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/CURDAppWalkthrough.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/CURDAppWalkthrough.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="CURDAppWalkthrough" xreflabel="CURDAppWalkthrough"> + <?dbhtml filename="CURDAppWalkthrough.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>CURD</keyword> + <keyword>JBoss AS</keyword> + </keywordset> + </chapterinfo> + <title>The CURD Application Walkthrough</title> + +</chapter> + Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GenCURDDatabaseApp.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GenCURDDatabaseApp.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GenCURDDatabaseApp.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="GenCURDDatabaseApp" xreflabel="GenCURDDatabaseApp"> + <?dbhtml filename="GenCURDDatabaseApp.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>CURD</keyword> + <keyword>Database Application</keyword> + </keywordset> + </chapterinfo> + <title>Generate a CURD Database Application</title> + +</chapter> + Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -0,0 +1,700 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="GetStartSeamGen" xreflabel="GetStartSeamGen"> + <?dbhtml filename="GetStartSeamGen.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Seam</keyword> + <keyword>JBoss</keyword> + <keyword>CRUD-application</keyword> + </keywordset> + </chapterinfo> + + <title>Ajax CRUD-application with Seam and Rich Faces</title> +<para>In this chapter we will see how easy it is to build Seam applications and integrate +them with Ajax4jsf and Rich Faces. We will bootstrap the application using Seam Gen which is + a CRUD application generator. Seam Gen can be used from either the command line or via an + Eclipse Plugin. Unlike most application generators, Seam Gen can also be used to + incrementally add more functionality to an existing Seam application.</para> + <para>Seam is an incredibly flexible development framework that can be completely + integrated with a Java EE server or in a simple POJO environment like Tomcat. Seam is + also extremely portable, and has been tested on several popular containers like JBoss, + Tomcat, Weblogic, WebSphere. Seam uses JSF as its view layer and can use either JSP or + Facelets as the presentation layer.</para> + <para>Seam Gen generates all the required layers of an application. It uses JPA as the + persistence layer, POJO&apos;s (Plain Old Java Objects) as the business logic layer and + Facelets as the presentation layer.</para> + <para>We will perform the following steps in this chapter of the tutorial:</para> + <itemizedlist> + <listitem>Creating a Seam Project using Seam Gen</listitem> + <listitem>Generating a Seam application using Seam Gen</listitem> + <listitem>Running the Seam application</listitem> + <listitem>Customizing the generated Seam application</listitem> + <listitem>Adding AJAX features to automatically generated JSF Seam UI components</listitem> + <listitem>Replacing standard JSF UI components with AJAX enabled rich UI components + provided by the Red Hat Developer Studio</listitem> + <listitem>Using AJAX components to do live validation on web pages</listitem> + <listitem>Adding Rich Faces components to a Seam application</listitem> + </itemizedlist> +<section id="CreatingASeamProjectUsingSeamGen"> +<?dbhtml filename="CreatingASeamProjectUsingSeamGen.html"?> +<title>Creating a Seam Project using Seam Gen</title> +<itemizedlist> +<listitem>Stop your JBoss AS Server by clicking on the stop button as shown below. We are + doing this so that the generated application can be deployed properly when the server + starts.</listitem> + </itemizedlist> + <figure> +<title>Stopping JBoss AS Server</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/StoppingServer.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>To create a Seam project, select <emphasis>Seam Gen > Setup/Configuration > Setup </emphasis>to +launch the Seam Gen setup window as shown below. Note: </listitem> +</itemizedlist> +<note> + <title>Note:</title> + <para>If this is the first time you run +Seam Gen a file dialog will be shown. In this you need to select &lt;seam&gt;/seam-gen/build.xml + so the plugin knows which seam-gen to use.</para> + </note> +<para></para> + + <figure> +<title>Seam Gen Setup Window</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/SeamGenSetup.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Fill the items in the dialog as shown below and select the <emphasis>OK</emphasis> button.</para> +<table> + <title>Filling Project Items</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Field Name</entry> + <entry>Field Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>Project</entry> + <entry>EclipseCon</entry> + </row> + <row> + <entry>Seam project workspace</entry> + <entry>&lt;your project directory&gt;</entry> + </row> + <row> + <entry>JBoss AS Home directory</entry> + <entry>&lt;JBoss AS Home Dir&gt;</entry> + </row> + <row> + <entry>Driver Location</entry> + <entry>&lt;seam>/&lt;seam-gen&gt;/lib/hsqldb.jar</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The plug-in will initialize the Seam Gen ant tasks that simplify all key Seam + operations. We will invoke several of these ant tasks via the Seam Eclipse Plugin + throughout this tutorial.</para> + <para>The plug-in will also prompt you to create a project. Select &quot;Yes&quot; to create a + Project. This step will create not only an Eclipse project but also all the required + artifacts to get you started.</para> + <para>The plug-in will also prompt you create a database connection. Select + &quot;Yes&quot; to create a WTP Database connection that connects to the default HSQL DB + instance that we have set up. If you are using any other database then set up the + appropriate database settings in the Seam Gen setup window.</para> + <para>At the end of this step you will see an Eclipse project called &quot;EclipseCon&quot; + as shown below. This project has all the necessary elements required to deploy + a Seam application.</para> + <figure> +<title>EclipseCon Project Structure</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/EclipseConProjectStructure.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Start the application server. Open your favorite browser and point to the +following URL http://localhost:8080/EclipseCon. You should see the following page:</listitem> +</itemizedlist> +<figure> +<title>Created Project</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/CreatedProject.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Congratulations! You have written your first Seam application.</para> +<itemizedlist continuation="continues"> +<listitem>Let us take a look at the database connection that was created by the Eclipse + Plugin and browse the database provided. The database connection view should now have a + connection to our sample database as shown below.</listitem> + </itemizedlist> + <figure> +<title>Connections View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ConnectionsView.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Right click on the connection > Reconnect. Just specify &quot;sa&quot; as the user id. The password + field should be blank.</para> + <para>You should now be able to browse the database and see the meta-data and query data using SQL. + Your meta-data should look like the following:</para> + <figure> +<title>Meta-data View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/Metadata.png"/> + </imageobject> +</mediaobject> +</figure> +</section> +<section id="GeneratingACRUDApplicationUsingSeamGen"> +<?dbhtml filename="GeneratingACRUDApplicationUsingSeamGen.html"?> +<title>Generating a CRUD application using Seam Gen</title> +<itemizedlist> +<listitem>The next step in our exercise is to generate a full blown application using Seam Gen. +This application will generate CRUD pages and Search pages for all the entities in the database. +Click on Seam Gen > Generate Entities. Seam Gen will connect to the database we defined in the + setup part of the application and generate all the required components.</listitem> + <listitem>Since Seam Gen is generating files on the file system that Eclipse does not know + about, right click on the project name on your project and choose the Refresh item. This will let + Eclipse know that there are new files and get them updated in the Eclipse project and deployed + in the JBoss instance.</listitem> + <listitem>Restart you application server, just in case those files have not been properly + synchronized with the application server.</listitem> + <listitem>Point your favorite browser to the following URL http://localhost:8080/EclipseCon. + You will see the following page:</listitem> + </itemizedlist> + <figure> +<title>EclipseCon Project</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/CreatedProject12.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Let us now look at one of the entities and see what has been generated. Click on the + &quot;Offices List&quot; to see a search page that allows you to filter the list and the list of all the + offices in the database.</listitem> + <listitem>Type in USA in the country field and click on Search to get a list of offices in the + USA as shown below.</listitem> + </itemizedlist> + <figure> +<title>Search Panel</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/SearchPanel.png"/> + </imageobject> +</mediaobject> +</figure> + +<itemizedlist continuation="continues"> +<listitem>Let us now check out the editing capability of the generated Seam application. Select + the first office code and click on the Edit button. You will be prompted for a userID and + password. Use &quot;seamuser&quot; for both user and password. You should at this point see the edit page + as shown below. Notice that the NOT NULL columns in the database table are automatically marked + with the red * to indicate that they are required.</listitem> + </itemizedlist> + <figure> +<title>Generated Edit Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/GeneratedEditPage.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Change a few things and save changes. This should update the record in the database. + There you have it. A simple and easy way to bootstrap your applications.</listitem> + <listitem>Let us look at how validations are done in Seam. Go back to and edit another office + record and this time leave the city blank and click on the Save button. You will see the default + Seam validations get triggered. In this case the &quot;value required&quot; validation is fired as shown + below.</listitem> + </itemizedlist> +<figure> +<title>Error Reporting</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ValidationInEditPage.png"/> + </imageobject> +</mediaobject> +</figure> +</section> +<section id="CustomizingTheGeneratedApplication"> +<?dbhtml filename="CustomizingTheGeneratedApplication.html"?> +<title>Customizing the generated application</title> +<itemizedlist> +<listitem>Let us look at a couple of simple things we can change in the generated application + to show you that the generated application can be customized. Let us start by changing the edit + page that we just saw. We will clean up the labels using the Facelet designer as shown below. + Open the view directory in your project and double click on the OfficeEdit.xhtml file.</listitem> +</itemizedlist> +<figure> +<title>Facelet Designer</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/FaceletDesigner.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Unlike other WYSIWYG editors which developers tend to hate, the visual designers in Red Hat + Developer Studio are designed for developers to rapidly find their way in a source file, while + still allowing them to visually look at a document.</para> + +<itemizedlist continuation="continues"> +<listitem>To change a label text, click on a label in the designer. This will position the + cursor at the correct location in the source view. Type the new label there. The designer does + not force the developer to use the WYSIWIG environment. Change all the labels for the edit page.</listitem> + </itemizedlist> + <para>Once you save the page, the IDE automatically rebuilds the application and re-deploys it. + So, just reload your browser and you should see an updated web page like the following. If for + some reason the re-deployment did not work, stop and restart the server normally resolves the issue.</para> + <figure> +<title>Edit Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/EditPage.png"/> + </imageobject> +</mediaobject> +</figure> +</section> +<section id="UsingHibernateToolsToInteractWithTheJPAEntities"> +<?dbhtml filename="UsingHibernateToolsToInteractWithTheJPAEntities.html"?> +<title>Using Hibernate tools to interact with the JPA Entities</title> +<para>As part of generating the application, Seam Gen also generates JPA entities that are used + to interact with the database. Let us quickly take a look at Hibernate tools and see how we can + interact with the database using HQL and the Hibernate Criteria API.</para> + <itemizedlist> + <listitem>Open the Hibernate Configurations View. You should be able to open the console like + the other views we have seen so far in the tutorial. Your view should resemble the following:</listitem> + </itemizedlist> + <figure> +<title>Hibernate Configurations View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/HibernateConfigurationsView.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Before we run the HQL, let us open up the &quot;Hibernate Query Result&quot; and the &quot;Hibernate + Dynamic SQL Preview&quot; views. You should be able to do that in a manner similar to other views we + have opened in this tutorial. Alternatively you can open the Hibernate Console Perspective where + these views are opened up by default.</listitem> + <listitem>Click on the &quot;HQL&quot; icon in the &quot;Hibernate Configurations&quot; view. This will open up + the HQL Designer view as shown below. Also, select &quot;EclipseCon&quot; from the drop down menu next to + the green &quot;run&quot; button.</listitem> + </itemizedlist> + <figure> +<title>HQL Designer View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/HQLDesignerView.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Type in a simple query as shown above &quot;from Offices o&quot; and click on the green &quot;run&quot; + button. You should see the result of the HQL query in the &quot;Hibernate Query Result&quot; window as + shown below.</listitem> + </itemizedlist> + <figure> +<title>Hibernate Query Result Window</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/HibernateQueryResultWindow.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Click on any of the objects in the result and you should be able see the contents of + the objects in the Property view as shown below. If you don&apos;t have the view open in your + perspective, you can open this view like all other views in this tutorial.</listitem> + </itemizedlist> + <figure> +<title>Property View</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/PropertyView.png"/> + </imageobject> +</mediaobject> +</figure> +<para>Select the &quot;Hibernate Dynamic SQL Preview&quot; view to the generated SQL. This is a great tool +to see the SQL being generated by Hibernate for your HQL. Not only is this a great debugging tool, + it is also a great way to optimize your HQL queries.</para> + <figure> +<title>Hibernate Dynamic SQL Preview</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/HibernateDynamicSQLPreview.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Let us try a slightly more complex query. Type in the following query in the query +window and see how the query result changes and the SQL Preview changes.</listitem> + </itemizedlist> + <programlisting role="JAVA"><![CDATA[select city, state, postalcode + from Offices o + where country = 'USA' +]]></programlisting> +<itemizedlist continuation="continues"> +<listitem>Let us try the Hibernate criteria APIs next. To use Hibernate Criteria APIs click on +the &quot;CRI&quot; button in the Hibernate Configurations View. This will open the Criteria API designer +view. Type in this simple criteria query as shown below and click on the green run button to see + the results. Also, select &quot;EclipseCon&quot; from the drop down menu next to the green &quot;run&quot; button.</listitem> + </itemizedlist> + <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) +]]></programlisting> +<para>The results will be very similar to the HQL query except that the criteria query does not +generate the SQL in the &quot;Hibernate Dynamic SQL Preview&quot; view.</para> +<itemizedlist continuation="continues"> +<listitem>Let us try something a little more complex. Let us filter all offices in the USA as +shown below. The results of this query should be very similar to the results of the HQL.</listitem> + </itemizedlist> + <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) + .add(Restrictions.eq("country", "USA")) ; +]]></programlisting> +<itemizedlist continuation="continues"> +<listitem>Finally let us visually see the entity model of the generated JPA objects. Before we + do that, open the &quot;Hibernate Entity Model&quot; view and select the &quot;Configurations&quot; option in the + &quot;Hibernate Configurations&quot; view. The plug-in will show all the entities in a visual format. + You can either manually align your objects or click on the &quot;Layout&quot; button on the right of the + &quot;Hibernate Entity Model&quot; view to generate a default layout.</listitem> + </itemizedlist> + <figure> +<title>Hibernate Entities</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/HibernateEntities.png"/> + </imageobject> +</mediaobject> +</figure> + +</section> +<section id="AddingAJAXAndRichUIFeaturesToASeamApplication"> +<?dbhtml filename="AddingAJAXAndRichUIFeaturesToASeamApplication.html"?> +<title>Adding AJAX and rich UI features to a Seam application</title> +<para>A key feature of JBoss Seam and the Red Hat Developer Studio is that they make AJAX and rich + UI web applications a breeze to develop. In this section of the tutorial, we will show you how + to:</para> + <itemizedlist> + <listitem>Add AJAX features to automatically generated JSF Seam UI components</listitem> + <listitem>Replace standard JSF UI components with AJAX enabled rich UI components provided by the + Red Hat Developer Studio</listitem> + <listitem>Use AJAX components to do live validation on web pages</listitem> + </itemizedlist> + <section id="AddingAJAXFeaturesToGeneratedUIComponents"> +<?dbhtml filename="AddingAJAXFeaturesToGeneratedUIComponents.html"?> +<title>Adding AJAX features to generated UI components</title> +<para>Let us now try to add some AJAX features to the generated Seam application. Click on the + Payments List link on the top of the page. You will see a search page as shown below.</para> + <figure> +<title>Search Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/SearchPage.png"/> + </imageobject> +</mediaobject> +</figure> +<para>You can search for any &quot;checknumber&quot; by typing in the number or by paging through the list + of payments. But what if you only knew a few of the digits/alphabets in the &quot;checknumber&quot;? It + would be very useful to filter the list based on that. AJAX provides very useful techniques to + build these types of applications and Ajax4jsf provides the building blocks to simplify these + techniques.</para> + <para>Double Click on the PaymentsList.xhtml to open the visual facelet designer. You will + notice that in the beginning of the source, Seam Gen has already add the tag library references + to Ajax4jsf and RichFaces as shown below.</para> + <programlisting role="JAVA"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:f="http://java.sun.com/jsf/core" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" + xmlns:rich="http://richfaces.ajax4jsf.org/rich" + template="layout/template.xhtml"> +]]></programlisting> +<para>Next, locate the check number input field. We need to add AJAX to this field. Basically, +as we type we want to update the table. Adding AJAX functionality usually requires two things:</para> +<itemizedlist> +<listitem>Letting the framework know on which event to send an AJAX request to the server.</listitem> +<listitem>Specifying what component(s) to update with the output from the server.</listitem> +</itemizedlist> +<para>Ajax4jsf provides a simple JSF component <emphasis role="bold"><property>&lt;aj4:support&gt;</property></emphasis> that simplifies this process. Let us +take our example and add AJAX to it.</para> +<itemizedlist> +<listitem>Click on the checknumber field in the visual designer, it will position you at the +correct location in the source. You will notice that the inputText tag does not have a closing +tag. Let us add a closing tag to the input text field as shown below.</listitem> +</itemizedlist> +<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" + value="#{paymentsList.payments.checknumber}"> + <a4j:support event="onkeyup" reRender="paymentsList"/> + </h:inputText> +]]></programlisting> +<itemizedlist continuation="continues"> +<listitem>Now let us add the AJAX support tag to let Ajax4jsf know that when the user presses a + key we want to go to the server to get a list of payments that match the characters entered in + the checknumber text box. Add the tag that is highlighted below to the inputText tag.</listitem> +</itemizedlist> +<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" + value="#{paymentsList.payments.checknumber}"> + <a4j:support event="onkeyup" reRender="paymentsList"/> + </h:inputText> +]]></programlisting> +<para>This tag is pretty self explanatory, it posts the server when a key is pressed and then + takes the response from the server and re-renders the section of the page that has an id of + &quot;paymentsList&quot;.</para> + <itemizedlist continuation="continues"> +<listitem>If you follow along in the page, you will see that the section that displays the +results is in a div tag that has an id of &quot;paymentsList&quot;</listitem> +</itemizedlist> +<programlisting role="JSP"><![CDATA[<div class="results" id="paymentsList"> + <h3>search results</h3> + <h:outputText value="No payments exists" + rendered="#{empty paymentsList.resultList}"/> + ... + </div> +]]></programlisting> +<itemizedlist continuation="continues"> +<listitem>Save the changes and refresh your browser. You will see that as you type characters +in the checknumber field, all payments that begin with those characters will be displayed in the +table automatically.</listitem> +</itemizedlist> +<figure> +<title>Data Fields</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/DataFields.png"/> + </imageobject> +</mediaobject> +<mediaobject> + <imageobject> + <imagedata fileref="images/Buttons.png"/> + </imageobject> +</mediaobject> +</figure> +<para>But there is still one more problem in this page, you will see that the &quot;Next&quot; and + &quot;Previous&quot; buttons will be displayed even for search results that are small as shown above.</para> + <itemizedlist continuation="continues"> +<listitem>The tag that we added in the previous step only updates the table. Let us add an AJAX +region around the page buttons at the bottom of the table. This will allow Ajax4jsf to update +those buttons independently.</listitem> +</itemizedlist> +<programlisting role="JSP"><![CDATA[<a4j:outputPanel ajaxRendered="true"> + <div class="tableControl"> + ... + </div> + </a4j:outputPanel> +]]></programlisting> +<para>Add an <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> tag around the page buttons as shown above and run the page again. + If the result list is small, you will see that the page buttons are no longer visible as shown + below.</para> + <figure> +<title>Datatable With No Page Buttons</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/NoButtons.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Let add one more thing to complete this part of the sample. When we type a character in + the &quot;checknumber&quot; field, there is no visual feedback to the user that there is a request being + made to the server.</listitem> + </itemizedlist> + <para>Ajax4jsf has a pre-built tag <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> that allows you to either render a text or an + image in response to an AJAX event. Add the following code, right after the end of the + <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag.</para> + <programlisting role="JSP"><![CDATA[<a4j:status> + <f:facet name="start"> + <h:graphicImage value="/img/ajax-loader.gif" style="border: 1px solid #E0E0E0"/> + </f:facet> + </a4j:status> +]]></programlisting> +<para>Save changes to the page and refresh the browser. You will see the image when the AJAX +request is active. The image will disappear as soon as the response is received.</para> +<itemizedlist continuation="continues"> +<listitem>Finally, let us place the image beside the &quot;checknumber&quot; text box. Place a +<emphasis role="bold"><property>&lt;h:panelGroup&gt;</property></emphasis> around the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> tags as shown below. +Save changes and refresh the browser. You should see the image right next to the text box.</listitem> + </itemizedlist> + <programlisting role="JSP"><![CDATA[<h:panelGroup> + <h:inputText id="checknumber" + value="#{paymentsList.payments.checknumber}"> + <a4j:support event="onkeyup" + reRender="paymentsList"/> + </h:inputText> + <a4j:status> + <f:facet name="start"> + <h:graphicImage value="/img/ajax-loader.gif" + style="border: 1px solid #E0E0E0"/> + </f:facet> + </a4j:status> + </h:panelGroup> +]]></programlisting> +<para>Although this example was a bit long, it shows how easy it is to add AJAX capabilities to +an existing Seam application.</para> +</section> +<section id="AddingRichfacesComponentsToaSeamApplication"> +<?dbhtml filename="AddingRichfacesComponentsToaSeamApplication.html"?> +<title>Adding RichFaces components to a Seam application</title> +<para>Now that we have seen how AJAX can bring interactivity to an application, let us add rich +controls that will improve the user experience. RichFaces provides numerous rich controls that +can be added to an application. In this section we will add spinner and slider controls that +allow users to change numerical values without using the keyboard.</para> +<para>Double Click on the OrderdetailsEdit.xhtml to open the visual facelet designer. You will + notice that in the beginning of the source, Seam Gen has already included the tag library + references to Ajax4jsf and RichFaces as shown below.</para> + <programlisting role="JSP"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:f="http://java.sun.com/jsf/core" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" + xmlns:rich="http://richfaces.ajax4jsf.org/rich" + template="layout/template.xhtml"> +]]></programlisting> +<para>In this page, we are going to replace the &quot;quantityordered&quot; text box with the spinner + control.</para> + <itemizedlist> + <listitem>In the visual view of the page, click on the &quot;quantityordered&quot; text box, this will + select the appropriate markup in the source view. Delete the selected markup.</listitem> + </itemizedlist> + <figure> +<title>Deleting Selected Markup</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/DeletingSelectedMarkup.png"/> + </imageobject> +</mediaobject> +</figure> +<para>We will replace the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag with a pre-built <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> tag. + The spinner control tag is very simple to use and like all other JSF controls, it has a value + attribute that can be bound to any JSF Managed Bean or Seam component. The designer allows you + to visually find all the beans available as shown below. Right + click on the <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> input field and select &quot;<emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> Attributes&quot;.</para> + <figure> +<title>Replacing Tags</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/ReplacingTags.png"/> + </imageobject> +</mediaobject> +</figure> +<para>The minValue and maxValue are self explanatory, they represent the minimum and maximum + values for the spinner. Place the following tag in your page.</para> + <programlisting role="JSP"><![CDATA[<rich:inputNumberSpinner + value="#{orderdetailsHome.definedInstance.quantityordered}" + inputStyle="width:30px; height:20px" + minValue="0" + maxValue="100" + required="true"/> +]]></programlisting> + +<itemizedlist continuation="continues"> +<listitem>Save changes and refresh the browser page. Your output page should look like this:</listitem> +</itemizedlist> +<figure> +<title>Output Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OutputPage.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Although this is not the best situation to use a slider, let us take a quick look at +another RichFaces control <emphasis role="bold"><property>&lt;rich:inputNumberSlider&gt;</property></emphasis>. The slider control is similar to the the +spinner control; it is bound to the same object. Replace the spinner with the following markup. +Save the page and refresh your browser window.</listitem> +</itemizedlist> +<programlisting role="JSP"><![CDATA[<rich:inputNumberSlider + value="#{orderdetailsHome.definedInstance.quantityordered}" + styleClass="slider" + width="200"/> +]]></programlisting> +<figure> +<title>InputNumberSlider Settings</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/InputNumberSliderSettings.png"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist continuation="continues"> +<listitem>Seam Gen also generates a date picker control for all date fields in an edit page. + Click on &quot;Order List&quot; and edit one of the orders to see an example of the date picker control + that is bundled with Seam.</listitem> +</itemizedlist> + +<figure> +<title>Order List</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OrderedList.png"/> + </imageobject> +</mediaobject> +</figure> + +</section> +<section id="ValidatingTheAJAXWay(LiveValidations)"> +<?dbhtml filename="ValidatingTheAJAXWay(LiveValidations).html"?> +<title>Validating the AJAX way (Live Validations)</title> +<para>Seam Gen also generates field validation code that leverages AJAX techniques, by providing + immediate feedback to users who use these applications. To see an example of this, go back to + the Office Edit page and leave the city blank and tab out of the field. Seam will immediately + validate the field and tell you that the value is required.</para> + <figure> +<title>Office Edit Page</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/OfficeEditPage.png"/> + </imageobject> +</mediaobject> +</figure> +<para>To provide this functionality for every required field in the page Seam generates the + following markup:</para> +<programlisting role="JSP"><![CDATA[<s:decorate id="cityDecoration"> +<h:inputText id="city" + required="true" + size="50" + maxlength="50" + value="#{officesHome.instance.city}"> + <a:support event="onblur" reRender="cityDecoration"/> + </h:inputText> + </s:decorate> +]]></programlisting> +<para>Seam uses Ajax4jsf to make a server side call to validate the field.</para> +</section> +</section> + +<section id="OtherRelevantResourcesOnTheTopic2"> +<?dbhtml filename="OtherRelevantResourcesOnTheTopic2.html"?> +<title>Other relevant resources on the topic</title> +<para>Seam on JBoss: <ulink url="http://www.jboss.com/products/seam">Seam Framework</ulink></para> + +<para>Ten Good Reasons to use Seam: <ulink url="http://www.jboss.com/products/seam/whyseam">Why Seam</ulink></para> +<para>Getting Started: <ulink url="http://labs.jboss.com/jbossseam/gettingstarted">Getting Started with JBoss Seam</ulink></para> +<para>Wiki: <ulink url="http://www.jboss.com/wiki/Wiki.jsp?page=JBossSeam">JBoss Wiki</ulink></para> +<para>FAQ: <ulink url="http://labs.jboss.com/jbossseam/faq/index.html">JBoss Seam FAQ</ulink></para> +<para>Downloads: <ulink url="http://labs.jboss.com/jbossseam/download">JBoss Seam Downloads</ulink></para> +<para>Jira: <ulink url="http://jira.jboss.org/jira/browse/JBSEAM">Jira issue tracker</ulink></para> +<para>Rules Framework: <ulink url="http://www.jboss.com/products/rules">JBoss Rules</ulink></para> +</section> +</chapter> Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/ManageJBossAS.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/ManageJBossAS.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/ManageJBossAS.xml 2007-07-23 12:13:31 UTC (rev 2594) @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="ManageJBossAS" xreflabel="ManageJBossAS"> + <?dbhtml filename="ManageJBossAS.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + <keyword>JBoss AS</keyword> + </keywordset> + </chapterinfo> + <title>Manage JBoss AS from Red Hat Developer Studio</title> + +</chapter> +