Author: smukhina Date: 2007-05-03 07:03:01 -0400 (Thu, 03 May 2007) New Revision: 1992 Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/install.png trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedForCreatingaJSFApplication.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforCreatingaStrutsApplication.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJSFwithHibernate.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJavaServerFaces.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedStrutsValidationExamples.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml.bak Log: Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/install.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/install.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedForCreatingaJSFApplication.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedForCreatingaJSFApplication.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedForCreatingaJSFApplication.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,350 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="GettingStartedForCreatingAJSFApplication" xreflabel="GettingStartedForCreatingAJSFApplication"> + <?dbhtml filename="GettingStartedForCreatingAJSFApplication.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Getting Started Guide for +Creating a JSF Application</title> +<section id="CreatingAJSFApplication"> +<?dbhtml filename="GettingStartedForCreatingAJSFApplication.html"?> +<title>Creating a Simple JSF Application</title> +<para>We are going to show you how to create a simple JSF application using the Red Hat Developer Studio + plug-in for Eclipse. The completed application will ask a user to enter a name and click +a button. The resulting new page will display the familiar message, &quot;Hello &lt;name&gt;!&quot; +This document will show you how to create such an application from the beginning, along +the way demonstrating some of the powerful features of Red Hat Developer Studio. You will design the +JSF application and then run the application from inside Red Hat Developer Studio. +We&apos;ll assume that you have already launched Eclipse with Red Hat Developer Studio installed and +also that the Red Hat Developer Studio perspective is the current perspective. (If not, make it active by +selecting Window/Open Perspective/Red Hat Developer Studio from the menu bar or by selecting Window/ +Open Perspective/Other... from the menu bar and then selecting Red Hat Developer Studio from +the Select Perspective dialog box.)</para> +</section> +<section id="SettingUpTheProject"> +<?dbhtml filename="SettingUpTheProject.html"?> +<title>Setting Up the Project</title> +<para>We are first going to create a new project for the application.</para> +<orderedlist> +<listitem><para>Go to the menu bar and select File/New/Project... .</para></listitem> +<listitem><para>Select Red Hat Developer Studio/JSF Project in the New Project dialog box.</para></listitem> +<listitem><para>Click Next</para></listitem> +<listitem><para>Enter jsfHello as the project name.</para></listitem> +<listitem><para>Leave everything else as is, and click Finish.</para></listitem> + +</orderedlist> +</section> +<section id="TheJSFApplicationConfigurationFile"> +<?dbhtml filename="TheJSFApplicationConfigurationFile.html"?> +<title>The JSF Application Configuration File</title> +<para>A jsfHello node should appear in the upper-left Package Explorer view.</para> +<orderedlist continuation="continues"> +<listitem><para>Click the plus sign next to jsfHello to reveal the child nodes.</para></listitem> +<listitem><para>Click the plus sign next to WebContent under jsfHello.</para></listitem> +<listitem><para>Click the plus sign next to WEB-INF under WebContent.</para></listitem> + +<listitem><para>Then double-click on the faces-config.xml node to display the JSF application configuration file editor.</para></listitem> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +</orderedlist> +</section> +<section id="AddingNavigationToTheApplication"> +<?dbhtml filename="AddingNavigationToTheApplication.html"?> +<title>Adding Navigation to the Application</title> +<para>In our simple application, the flow is defined as a single navigation rule connecting two +views (presentation files). At this point, we will create the placeholders for the two JSP presentation +files and then the navigation rule to connect them as views. Later, we will complete +the coding for the JSP presentation files. With Red Hat Developer Studio, we can do all of this in the +Diagram mode of the configuration file editor.</para> +<section id="AddingTwoViews(JSPPages)"> +<?dbhtml filename="AddingTwoViews(JSPPages).html"?> +<title>Adding Two Views (JSP Pages)</title> +<orderedlist continuation="continues"> +<listitem><para>Right-click anywhere on the diagram and select New View... from the pop-up +menu</para></listitem> +<listitem><para>In the dialog box, type pages/inputname as the value for From-view-id</para></listitem> +<listitem><para>Leave everything else as is</para></listitem> +<listitem><para>Click Finish.</para> +<para>If you look in the Package Explorer view you should see a pages folder under WebContent. Opening it +will reveal the JSP file you just created</para> +</listitem> +<listitem><para>Back on the diagram, right-click anywhere and select New View... from the popup +menu</para></listitem> +<listitem><para>In the dialog box, type pages/greeting as the value for From-view-id</para></listitem> +<listitem><para>Leave everything else as is</para></listitem> +<listitem><para>Click Finish</para></listitem> +</orderedlist> +<section id="CreatingTheTransition(NavigationRule)"> +<?dbhtml filename="CreatingTheTransition(NavigationRule).html"?> +<title>Creating the Transition (Navigation Rule)</title> +<orderedlist continuation="continues"> +<listitem><para>In the diagram, select the connection icon third from the top along the upper left +side of the diagram</para></listitem> +</orderedlist> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> + +<para>to get an arrow cursor with a two-pronged plug at the arrow&apos;s bottom.</para> +<orderedlist continuation="continues"> +<listitem><para>Click on the pages/inputname page icon and then click on the pages/greeting page icon</para></listitem> + +</orderedlist> +<para>A transition should appear between the two icons.</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem><para>Select File/Save from the menu bar.</para></listitem> +</orderedlist> +</section> +</section> +</section> +<section id="AddingAManagedBeanToTheApplication"> +<?dbhtml filename="AddingAManagedBeanToTheApplication.html"?> +<title>Adding a Managed Bean to the Application</title> +<para>To store data in the application, we will use a managed bean.</para> +<orderedlist continuation="continues"> +<listitem><para>Click on the Tree tab at the bottom of the editing window</para></listitem> +<listitem><para>Select the Managed Beans node and then click the Add... button displayed along +the right side of the editor window</para></listitem> +<listitem><para>Type in jsfHello.PersonBean for Class and personBean for Name. Leave +Scope as is and Generate Source Code as is (checked)</para></listitem> +<listitem><para>Click Finish</para></listitem> +<listitem><para>personBean will now be selected and three sections of information, Managed +Bean, Properties, and Advanced, will be displayed about it. Under the Properties +section, click the Add... button</para></listitem> +<listitem><para>For Property-Name type in name. Leave everything else as is. (When Property- +Class is not filled in, String is the assumed type.)</para></listitem> +<listitem><para>Click Finish</para></listitem> +<listitem><para>Select the personBean node in the tree</para></listitem> +</orderedlist> +<para>You should see this now:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem><para>Select File/Save from the menu bar.</para></listitem> +</orderedlist> +<para>You have now registered the managed bean and created a stub-coded class file for it.</para> +</section> +<section id="EditingTheJSPViewFiles"> +<?dbhtml filename="EditingTheJSPViewFiles.html"?> +<title>Editing the JSP View Files</title> + +<para>Now we will finish editing the JSP files for our two &quot;views&quot; using Exadel&apos;s JSP Visual Page</para> +<section id="Inputname.jsp"> +<title>inputname.jsp</title> +<orderedlist continuation="continues"> +<listitem><para>Click on the Diagram tab for the configuration file editor</para></listitem> +<listitem><para>Open the editor for this first JSP file by double-clicking on the /pages/inputname. +jsp icon</para></listitem> +</orderedlist> + +<para>The Visual Page Editor will open in a screen split between source code along the top and +a WYSIWIG view along the bottom:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<para>Some JSF code will already be in the file because we selected a template when creating the page.</para> +<orderedlist continuation="continues"> +<listitem><para>Select the Visual tab, so we can work with the editor completely in its WYSIWYG +mode</para></listitem> +<listitem><para>To the right of the editor, in the Exadel Palette, expand the JSF HTML palette folder +by selecting it</para></listitem> +</orderedlist> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem><para>34. Click on form within this folder, drag the cursor over to the editor, +and drop it inside the red box in the editor</para></listitem> + +<listitem><para>Another red box will appear inside the first red box.</para></listitem> + +<listitem><para>Right-click on the innermost box and select &lt;h:form&gt; Attributes from the menu</para></listitem> +<listitem><para>In the value field next to id, type greeting and click on the Close button</para></listitem> +<listitem><para>Type Please enter name: inside the boxes</para></listitem> +<listitem><para>Select inputText within the JSF HTML palette folder and drag it into the innermost +box in the editor after &quot;Please enter name:&quot;</para></listitem> +<listitem><para>In the attributes dialog, click in the value field next to the value attribute and click +on the ... button</para></listitem> +<listitem><para>Then, select the Managed Beans/personBean/name node and click on the Ok +button</para></listitem> +<listitem><para>Back in the attributes dialog, select the Advanced tab, type in name as the value +for the id attribute, and then click on the Finish button</para></listitem>' +<listitem><para>Select commandButton within the JSF HTML palette folder and drag it into the +innermost box in the editor after the input box</para></listitem> +<listitem><para>In the attributes dialog, click in the value field next to the action attribute and click +on the ... button</para></listitem> +<listitem><para>Then, select the View Actions/greeting node and click on the Ok button</para></listitem> +<listitem><para>Back in the attributes dialog box, type in Say Hello as the value for the value +attribute (&quot;Say Hello&quot;) and then click on the Finish button</para></listitem> +</orderedlist> +<para>The source coding should be something like this now:</para> +<programlisting role="XML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<html> +<head> +<title></title> +</head> +<body> +<f:view> +<h:form id="greeting"> +<para>Please enter a name:</para> +<h:inputText id="name" value="#{personBean.name}"/> +<h:commandButton value=" Say Hello " action="greeting"/> +</h:form> +</f:view> +</body> +</html> +]]></programlisting> +<para>The editor should look like this:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem><para>Save the file by selecting File/Save from the menu bar.</para></listitem> +</orderedlist> +</section> +<section id="Greeting.jsp"> +<title>greeting.jsp</title> +<orderedlist continuation="continues"> +<listitem><para>Click on the faces-config.xml tab to bring the diagram back</para></listitem> +<listitem><para>Open the editor for the second file by double-clicking on the /pages/greeting.jsp +icon</para></listitem> +<listitem><para>Select the Visual tab, so we can work with the editor completely in its WYSIWYG +mode</para></listitem> +<listitem><para>Type Hello (note space after hello) into the box</para></listitem> +<listitem><para>Select outputText within the JSF HTML palette folder and drag it into the innermost +box in the editor after &quot;Hello&quot;</para></listitem> +<listitem><para>In the attributes dialog, click in value field next to the value attribute and click on +the ... button</para></listitem> +<listitem><para>Then, select the Managed Beans/personBean/name node, click on the Ok button, +and then click on the Finish button</para></listitem> +<listitem><para>Right after the output field, type an exclamation point (!)</para></listitem> +</orderedlist> +<para>The source coding should be something like this now:</para> +<programlisting role="XML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<html> +<head> +<title></title> +</head> +<body> +<f:view> +Hello <h:outputText value="#{personBean.name}"/>! +</f:view> +</body> +</html> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Save the file.</para></listitem></orderedlist> +</section> +</section> +<section id="CreatingTheStartPage"> +<?dbhtml filename="CreatingTheStartPage.html"?> +<title>Creating the Start Page</title> +<para>You also need to create a start page as an entry point into the application.</para> +<orderedlist continuation="continues"> +<listitem><para>In the Package Explorer view to the left, right-click jsfHello/WebContent and select +New/JSP File</para></listitem> +<listitem><para>For Name type in index, for Template select JSPRedirect and click Finish.</para></listitem> +</orderedlist> +<para>A JSP editor will open up on the newly created file.</para> + +<orderedlist continuation="continues"> +<listitem><para>In the Source part of the split screen, type /pages/inputname.jsf in between +the quotes for the page attribute</para></listitem> +</orderedlist> +<para>The source coding should look like this now:</para> +<programlisting role="JSP"><![CDATA[<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head></head> +<body> +<jsp:forward page="/pages/inputname.jsf" /> +</body> +</html> +]]></programlisting> + +<para>Note the .jsf extension for the file name. This is a mapping defined in the web.xml file +for the project for invoking JavaServer Faces when you run the application.</para> +<orderedlist continuation="continues"> +<listitem><para>Select File/Save from the menu bar.</para></listitem> +</orderedlist> +</section> +<section id="RunningTheApplicationJSF"> +<?dbhtml filename="RunningTheApplicationJSF.html"?> +<title>Running the Application</title> +<para>Everything is now ready for running our application without having to leave Red Hat Developer Studio +by using the Tomcat engine that comes with the Red Hat Developer Studio plug-in. For controlling +Tomcat within Red Hat Developer Studio, the toolbar contains a special panel</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<orderedlist continuation="continues"> +<listitem><para>Start up Tomcat by clicking on the first icon from left. (If Tomcat is already running, +stop it by clicking on the third icon from the left and then start it again. Remember, +the JSF run-time requires restarting the servlet engine when any changes have been +made.) After the messages in the Console tabbed view stop scrolling, Tomcat is available.</para></listitem> + +<listitem><para>Click on the Red Hat run icon in the toolbar:</para></listitem> +</orderedlist> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<para>This is the equivalent of launching the browser and typing http://localhost:8080/jsfHello into your + browser. Our JSF application should now appear.</para> + </section> + </chapter> \ No newline at end of file Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforCreatingaStrutsApplication.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforCreatingaStrutsApplication.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforCreatingaStrutsApplication.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,420 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter id="GettingStartedGuideforCreatingaStrutsApplication" xreflabel="GettingStartedGuideforCreatingaStrutsApplication"> + <?dbhtml filename="GettingStartedGuideforCreatingaStrutsApplication.html"?> + <title>Getting Started Guide for Creating a Struts Application</title> +<para>We are going to show you how to create a simple Struts application using the Red Hat Developer Studio +plug-in for Eclipse. The completed application will ask a user to enter a name and click a button. +The resulting new page will display the familiar message, Hello &lt;name&gt;!</para> +<para>This document will show you how to create such an application from the beginning, along +the way demonstrating some of the powerful features of Red Hat Developer Studio. You will design the +application, generate stub code for the application, fill in the stub coding, compile the application, +and run the application all from inside Red Hat Developer Studio.</para> +<para>Well assume that you have already launched Eclipse with Exadel Studio or Exadel Studio +Pro installed and also that the Red Hat Developer Studio perspective is the current perspective. (If not, +make it active by selecting Window/Open Perspective/Red Hat Developer Studio from the menu bar.)</para> + + <section id="StartingUp"> + <title>Starting Up</title> +<para>We are first going to create a new project for the application.</para> + <orderedlist> +<listitem><para>Go to the menu bar and select File/New/Project... .</para></listitem> +<listitem><para>Select Exadel Studio/Struts/Struts Project in the New Project dialog box.</para></listitem> +<listitem><para>Click Next >.</para></listitem> +<listitem><para>Enter StrutsHello as the project name.</para></listitem> +<listitem><para>Leave everything else as is, and click Next >.</para></listitem> +<listitem><para>Click Next> again.</para></listitem> + <listitem><para>7. Make sure that struts-bean.tld, struts-html.tld, and struts-logic.tld are checked in the list of included tag libraries and then click Finish.</para></listitem> +</orderedlist> +<para>A StrutsHello node should appear in the upper-left Package Explorer view.</para> + <orderedlist continuation="continues"> +<listitem><para>Click the plus sign next to StrutsHello to reveal the child nodes.</para></listitem> +<listitem><para>Click the plus sign next to WebContent under StrutsHello.</para></listitem> +<listitem><para>Click the plus sign next to WEB-INF under WebContent.</para></listitem> + <listitem><para>Then, double-click on the struts-config.xml node to display a diagram of the Struts application configuration file in the editing area.</para></listitem> + </orderedlist> +<para>At this point, its empty except for the background grid lines.</para> + </section> + + <section id="CreatingtheApplicationComponents"> + <?dbhtml filename="CreatingtheApplicationComponents.html"?> + <title>Creating the Application Components</title> +<para>Now, we will design the application by creating the individual components as placeholders +first. (We dont have to complete all of the details inside the components until afterwards.)</para> + <section id="CreatingJSPPagePlaceholders"> + <title>Creating JSP Page Placeholders</title> +<para>Next, lets create and place two JSP pages. We will not write any code for the files, but only +create them as placeholders so that we can create links to them in the diagram. We will write +the code a little bit later.</para> + <section id="CreatingthePagePlaceholders"> + <title>Creating the Page Placeholders</title> + <orderedlist continuation="continues"> +<listitem><para>Bring the Web Projects view to the front of the Package Explorer view by selecting the Web Projects tab next to that tab.</para></listitem> +<listitem><para>Right-click the StrutsHello/WEB-ROOT (WebContent) folder in the Web Projects view and select New/Folder... .</para></listitem> +<listitem><para>Enter pages for a folder name and click Finish.</para></listitem> + +<listitem><para>We will keep our presentation files in this folder.</para></listitem> + +<listitem><para>Right-click the pages folder and select New/File/JSP... .</para></listitem> + <listitem><para>16. For Name type in inputname (the JSP extension will be automatically added to the file), for Template select StrutsForm, and then click on the Finish button.</para></listitem> +<listitem><para>Right-click the pages folder again and select New/File/JSP... .</para></listitem> +<listitem><para>For Name type in greeting , for Template leave as Blank, and then click on the Finish button.</para></listitem> + </orderedlist> +<para>Just leave these files as is for now.</para> + </section> + <section id="PlacingthePagePlaceholders"> + <title>Placing the Page Placeholders</title> +<para>Lets now place the two pages just created on the diagram.</para> + <orderedlist continuation="continues"> +<listitem><para>Click on the struts-config.xml tab in the Editing area to bring the diagram to the front.</para></listitem> +<listitem><para>Click on the inputname.jsp page in the Web Projects view, drag it onto the diagram, and drop it.</para></listitem> +<listitem>Click on the greeting.jsp page in the Web Projects view, drag it onto the diagram, +and drop it to the right of the /pages/inputname.jsp icon with some extra space.</listitem> +</orderedlist> +<para>You should now have two JSP pages in the diagram.</para> + </section> + </section> + <section id="CreatinganActionMappings"> + <title>Creating an Action Mappings</title> +<para>Using a context menu on the diagram, we are next going to create an Action mapping.</para> + <orderedlist continuation="continues"> +<listitem><para>Right-click between the two icons and select Add/Action</para></listitem> +<listitem><para>Enter the following values:</para></listitem> + </orderedlist> + <table> + <tgroup cols="2"> + <row> + <entry>path</entry> + <entry>/greeting</entry> + </row> + <row> + <entry>name</entry> + <entry>GetNameForm</entry> + </row> + <row> + <entry>scope</entry> + <entry>request</entry> + </row> + <row> + <entry>type</entry> + <entry>sample.GreetingAction</entry> + </row> + <row> + <entry>validate</entry> + <entry>&lt;leave blank&gt;</entry> + </row> + </tgroup> + </table> +<para>(GetNameForm is the name for a form bean that we will create later.)</para> +<orderedlist continuation="continues"> + <listitem><para>Click Finish.</para></listitem> +</orderedlist> + +<para>The /greeting action should appear in two places, in the diagram and also under the action-mappings node under the struts-config.xml node in the Outline view. Also, note the +asterisk to the right of the name, struts-config.xml, in the Outline view showing that the file has been changed, but not saved to disk.</para> + </section> + <section id="CreatingaLink"> + <title>Creating a Link</title> +<para>Lets now create a link from the inputname.jsp page to the action.</para> + <orderedlist continuation="continues"> +<listitem><para>On the left-hand side of the diagram in the column of icons, click on this icon:</para></listitem> + <listitem><para>26. In the connect-the-components mode you are in now, click on the /pages/inputname.jsp icon in the diagram and then click on the /greeting action.</para></listitem> + </orderedlist> +<para>A link will be created from the page to the action.</para> + </section> + <section id="CreatingaForward"> + <title>Creating a Forward</title> +<para>Next, we are going to create a forward for the action.</para> + <orderedlist continuation="continues"> +<listitem><para>On the left-hand side of the diagram in the column of icons, click on this icon, again:</para></listitem> +<listitem><para>Click on the /greeting action icon in the diagram and then click on the /pages/greeting.jsp icon.</para></listitem> + +<listitem><para>Thats it. A link will be drawn from the actions new greeting forward to the greeting.jsp JSP page. Note that the forwards name will be set based on the name of the target JSP file +name. If you dont like it, you can easily change it.</para></listitem> + +<listitem><para>Select the Tree tab at the bottom of the editor window (between Diagram and Source).</para></listitem> +<listitem><para>Expand the struts-config.xml/action-mappings//greeting node and then select the greeting forward.</para></listitem> +<listitem><para>In the Properties Editor to the right, change the text to sayHello in the Name field.</para></listitem> +<listitem><para>Select the Diagram tab at the bottom of the editor window and see how the diagram is also updated to reflect the change.</para></listitem> + </orderedlist> + </section> + <section id="CreatingaGlobalForward"> + <title>Creating a Global Forward</title> +<para>One last component that we need to create in the diagram is a global forward.</para> + <orderedlist continuation="continues"> +<listitem><para>Somewhere in the top-left corner of diagram, right-click and select Add/Global Forward....</para></listitem> +<listitem><para>Enter getName in the Name field.</para></listitem> +<listitem><para>Select the Change... button for Path.</para></listitem> +<listitem><para>In the Edit Path window, switch to the Pages tab.</para></listitem> +<listitem><para>Expand the StrutsHello/WEB-ROOT (WebContent)/pages node and then select the inputname.jsp page.</para></listitem> +<listitem><para>Click Ok.</para></listitem> +<listitem><para>Leave the rest of the fields blank and click Ok.</para></listitem> + </orderedlist> +<para>A forward object now appears on the diagram and also in the global-forwards folder in the Outline view.</para> + <orderedlist continuation="continues"> + <listitem><para>Tidy up the diagram, by clicking and dragging around each icon, so that the diagram looks something like this:</para></listitem> + </orderedlist> + </section> + <section id="CreatingaFormBean"> + <title>Creating a Form Bean</title> +<para>One last thing that we need to do is to create a form bean.</para> + <orderedlist continuation="continues"> +<listitem><para>Switch to the Tree viewer in the editor for the struts-config.xml file, by selecting the Tree tab at the bottom of the editor window.</para></listitem> +<listitem><para>Right-click struts-config.xml/form-beans and select Create Form Bean.</para></listitem> +<listitem><para>Enter GetNameForm in the name field and sample.GetNameForm for type.</para></listitem> +<listitem><para>Click Finish.</para></listitem> +<listitem><para>To save your changes to struts-config.xml, select File/Save from the menu bar.</para></listitem> + </orderedlist> +<para>Note the disappearance of the asterisk next to the name, struts-config.xml.</para> +</section> +</section> + + <section id="GeneratingStubCoding"> + <?dbhtml filename="GeneratingStubCoding.html"?> + <title>Generating Stub Coding</title> + <para>We are done with designing the application through the diagram. Now we need to write + code for the action component. We also need to write an action class for the /greeting mapping + along with a FormBean. To aid in the coding phase, Exadel Studio can generate Java class + stubs for all of the components shown in the diagram.</para> + <orderedlist continuation="continues"> +<listitem><para>Switch back to the diagram, by selecting the Diagram tab at the bottom of the editor window.</para></listitem> +<listitem><para>Right-click a blank space in the diagram and select Generate Java Code.</para></listitem> +<listitem><para>Leave everything as is in the dialog box and click Generate .</para></listitem> +</orderedlist> +<para>You should see a screen that says:</para> +<para>Generated classes: 2</para> +<para>Actions: 1</para> +<para>Form beans: 1</para> + <orderedlist continuation="continues"> +<listitem><para>Click Finish.</para></listitem> + </orderedlist> +<para>The Java files will be generated in a JavaSource/sample folder that you can see in the Package + Explorer view under the StrutsHello node. One Action stub and one FormBean stub will have been generated.</para> + </section> + <section id="CodingtheVariousFiles"> + <?dbhtml filename="CodingtheVariousFiles.html"?> + <title>Coding the Various Files</title> +<para>We will now code both the Java stub classes just generated, the JSP files left in as placeholders + from previous steps, and a new start JSP page we will have to create.</para> + <section id="JavaStubClasses"> + <title>Java Stub Classes</title> + <orderedlist continuation="continues"> + <listitem><para>To finish the two Java classes, switch to the Package Explorer view and expand the JavaSource/sample folder.</para></listitem> + </orderedlist> + <section id="GetNameForm.java"> + <title>GetNameForm.java</title> + <orderedlist continuation="continues"> +<listitem><para>Double-click GetNameForm.java for editing.</para></listitem> + +<listitem><para>You are looking at a Java stub class that was generated by Exadel Studio. Now we are going to edit the file.</para></listitem> + +<listitem><para>Add the following attributes at the beginning of the class:</para></listitem> + </orderedlist> +<para>private String name = "";</para> +<para>private String greetName = "";</para> + <orderedlist continuation="continues"> +<listitem><para>Inside the reset method, delete the TO DO and throw lines and add:</para></listitem> +</orderedlist> +<para>this.name = "";</para> +<para>this.greetName = "";</para> + <orderedlist continuation="continues"> +<listitem><para>Inside the validate method, delete the TO DO and throw lines and add:</para></listitem> + </orderedlist> +<para>ActionErrors errors = new ActionErrors();</para> +<para>return errors;</para> + <orderedlist continuation="continues"> +<listitem><para>Right-click and select Source/Generate Getters and Setters... from the context menu.</para></listitem> +<listitem><para>In the dialog box, check the check boxes for name and greetName, select First method for Insertion point, and click on the OK button.</para></listitem> + </orderedlist> +<para>The final GetNameForm.java file should look like this:</para> +<programlisting role="JAVA"><![CDATA[ +package sample; +import javax.servlet.http.HttpServletRequest; +import org.apache.struts.action.ActionErrors; +import org.apache.struts.action.ActionMapping; +public class GetNameForm extends org.apache.struts.action.ActionForm { +private String name = ""; +private String greetName = ""; +public String getName() { +return name; +} +public void setName(String name) { +this.name = name; +} +public String getGreetName() { +return greetName; +} +public void setGreetName(String greetName) { +this.greetName = greetName; +} +public GetNameForm() { +} +public void reset(ActionMapping actionMapping, HttpServletRequest +request) { +this.name = ""; +this.greetName = ""; +} +public ActionErrors validate(ActionMapping actionMapping, +Exadel Studio: Getting Started Guide for Creating a Struts Application +page 7 of 11 +HttpServletRequest request) { +ActionErrors errors = new ActionErrors(); +return errors; +} +} +]]></programlisting> + +<orderedlist continuation="continues"> +<listitem><para>Save the file.</para></listitem> +</orderedlist> +</section> + <section id="GreetingAction.java"> + <title>GreetingAction.java</title> + <orderedlist continuation="continues"> +<listitem><para>Open GreetingAction.java for editing.</para></listitem> +<listitem><para>Inside the execute method, delete the TO DO and throw lines and add the following:</para></listitem> + </orderedlist> + + <programlisting role="JAVA"><![CDATA[ +String name = ((GetNameForm)form).getName(); +String greeting = "Hello, "+name+"!"; +((GetNameForm)form).setGreetName(greeting); +return mapping.findForward(FORWARD_sayHello); +The final version of GreetingAction.java should look like this: +package sample; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; +import org.apache.struts.action.ActionForm; +import org.apache.struts.action.ActionForward; +import org.apache.struts.action.ActionMapping; +public class GreetingAction extends org.apache.struts.action.Action { +// Global Forwards +public static final String GLOBAL_FORWARD_getName = "getName"; +// Local Forwards +public static final String FORWARD_sayHello = "sayHello"; +public GreetingAction() { +} +public ActionForward execute(ActionMapping mapping, ActionForm form, +HttpServletRequest request, HttpServletResponse response) throws +Exception { +String name = ((GetNameForm)form).getName(); +String greeting = "Hello, "+name+"!"; +((GetNameForm)form).setGreetName(greeting); +return mapping.findForward(FORWARD_sayHello); +} +} +]]></programlisting> + <orderedlist continuation="continues"> +<listitem><para>Save the file.</para></listitem> +<listitem><para>Close the editors for the two Java files.</para></listitem> + </orderedlist> +<para>The last thing left to do is to code the JSP files whose editors should still be open from having been created as placeholders.</para> + </section> + </section> + <section id="JSPPages"> + <title>JSP Pages</title> + <section id="inputname.jsp"> + <title>inputname.jsp</title> +<para>In this page, the user will enter any name and click the submit button. Then, the greeting action will be called through the form.</para> + <orderedlist continuation="continues"> +<listitem><para>Click on the inputname.jsp tab in the Editing area to bring its editor forward.</para></listitem> +<listitem><para>In the Web Projects view, expand StrutsHello/Configuration/default/strutsconfig.xml/action-mappings and select /greeting.</para></listitem> +<listitem><para>Drag it and drop it between the quotes for the action attribute to the html:form element in the Source pane of the editor.</para></listitem> +<listitem><para>Then type this text on a new line just below this line:</para></listitem> + +<listitem><para>Input name:</para></listitem> + +<listitem><para>Select the Visual pane of the editor.</para></listitem> +<listitem><para>Then, in the Exadel Palette, expand the Struts Form library, select text, and drag it onto the box.</para></listitem> +<listitem><para>In the Insert Tag dialog box, type in name for property and select Finish.</para></listitem> +<listitem><para>In the Struts Form library in the Exadel Palette, select submit, and drag it to right after the the text box in the Visual pane of the editor.</para></listitem> +<listitem><para>Right-click the submit button and select &lt;html:submit&gt; Attributes from the context menu.</para></listitem> +<listitem><para>In the Attributes dialog box, select the value field and type in Say Hello! for its value.</para></listitem> + </orderedlist> +<para>After tidying the page source, the Editor window for the file should look something like this:</para> + </section> + <section id="greeting.jsp"> + <title>greeting.jsp</title> +<para>Next, we will fill in the result page.</para> +<orderedlist continuation="continues"> +<listitem><para>Click on the greeting.jsp tab in the Editing area to bring its editor forward.</para></listitem> +<listitem><para>Type in the following code:</para></listitem> + </orderedlist> +<programlisting role="XML"><![CDATA[ +<html> +<head> +<title>Greeting</title> +</head> +<body> +<p> +</p> +</body> +</html> +]]></programlisting> + +<para>To complete editing of this file, we will use macros from the Exadel Palette. This palette is a view that should be available to the right of the editing area.</para> + <orderedlist continuation="continues"> +<listitem><para>Click on the Struts Common folder in the Exadel Palette to open it.</para></listitem> +<listitem><para>Position the cursor at the beginning of the greeting.jsp file in the Source pane and then click on bean taglib in the Exadel Palette.</para></listitem> +</orderedlist> +<para>This will insert the following line at the top of the file:</para> +<programlisting role="JAVA"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Click on the Struts Bean folder in the Exadel Palette to open it.</para></listitem> +<listitem><para>Position the cursor inside the p element.</para></listitem> +<listitem><para>Click on write in the Exadel Palette.</para></listitem> +<listitem><para>Type in GetNameForm for the name attribute and add a property attribute with greetName as its value.</para></listitem> + </orderedlist> +<para>The editor should should now look like this:</para> + </section> + <section id="index.jsp"> + <title>index.jsp</title> +<para>Finally, we will need to create and edit an index.jsp page. This page will use a Struts forward to simply redirect us to the getName global forward.</para> + <orderedlist continuation="continues"> +<listitem><para>In the Web Projects view, right-click on StrutsHello/WEB-ROOT(WebContent)</para> +<para>node and select New/File/JSP... .</para> +</listitem> +<listitem><para>Type index for Name and click on the Finish button.</para></listitem> +<listitem><para>On the Exadel Palette, select the Struts Common folder of macros by clicking on it in the palette.</para></listitem> +<listitem><para>Click on the logic taglib icon.</para></listitem> +<listitem><para>Press the Enter key in the editor to go to the next line.</para></listitem> +<listitem><para>Back on the palette, select the Struts Logic folder of macros.</para></listitem> +<listitem><para>Click on redirect.</para></listitem> +<listitem><para>Delete the ending tag, put a forward slash in front of the closing angle bracket, and type forward=getName in front of the slash.</para></listitem> + </orderedlist> +<para>The finished code for the page is shown below:</para> +<programlisting role="JAVA"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %> +<logic:redirect forward="getName"/> +]]></programlisting> + <orderedlist continuation="continues"> +<listitem><para>To save all the edits to files, select File/Save All from the menu bar.</para></listitem> + </orderedlist> + </section> + </section> + </section> + <section id="CompilingtheClasses"> + <?dbhtml filename="CompilingtheClasses.html"?> + <title>Compiling the Classes</title> + <para>Because this is the Eclipse environment, no explicit compilation step is required. By default, + Eclipse compiles as you go.</para> + </section> + <section id="RunningtheApplication"> + <?dbhtml filename="RunningtheApplication.html"?> + <title>Running the Application</title> + <para>Everything is now ready for running our applicationwithout having to leave Red Hat Developer Studio + by using the Tomcat engine that comes with the Red Hat Developer Studio plug-in. For controlling + Tomcat within Red Hat Developer Studio, the toolbar contains a panel.</para> + <orderedlist continuation="continues"> +<listitem>Start up Tomcat by clicking on the first icon from left in this panel. (If Tomcat is + already running, stop it by clicking on the third icon from the left and then start it + again. Remember, the Struts run-time requires restarting the servlet engine when + any changes have been made.)</listitem> +<listitem>After the messages in the Console tabbed view stop scrolling, Tomcat is available. + At this point, right-click on the getName global forward in the struts-config.xml + diagram view and select Run on Server.</listitem> + </orderedlist> +<para>The browser should appear with the application started.</para> + </section> +</chapter> \ No newline at end of file Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJSFwithHibernate.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJSFwithHibernate.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJSFwithHibernate.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,521 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter id="GettingStartedGuideforJSFwithHibernate" xreflabel="GettingStartedGuideforJSFwithHibernate"> + <?dbhtml filename="GettingStartedGuideforJSFwithHibernate.html"?> + <title>Getting Started Guide for JSF with Hibernate</title> +<para>In this guide, we will show you how to take a very simple ready-made JSF application and convert it to use a database with the help of Exadel Studio. After downloading, we will first</para> +<para>set up and run the application without persistence, and then with persistence.</para> +<para>The application itself is a simple JSF-based application that asks the user to enter a UserID. It tries to locate a record for the entered User ID (entered during the application session).</para> +<para>If the record is found, details are displayed. If the record is not found, you are asked to create this record. This application, of course, only runs as long as the Tomcat server is running. Once we stop the server all of the data is lost as all information is saved only in the application session context.</para> +<para>With the help of Exadel Studio, we will convert this application to use the lightweight hsqldb database (included with the downloaded project). We will use Exadel Studio special features for object-relational mapping for this conversion After the conversion, even if we restart the server, the data we entered will have been saved in a database and thus available to the application.</para> +<para>Before we start, we assume that you have Eclipse, and have installed Exadel Studio Pro with Tomcat server.</para> + +<section id="InstallingTheProject"> +<?dbhtml filename="InstallingTheProject.html"?> +<title>Installing the Project</title> +<para>We are first going to download and import this project (ormHibernate3-jsf) into Eclipse.</para> + +<orderedlist> +<listitem><para>Download: http://webdownload.exadel.com/dirdownloads/ormhib/examples/ormHibernate3-... +<listitem><para>Unzip this file into your Eclipse workspace folder.</para></listitem> +<listitem><para>Launch Eclipse.</para></listitem> +<listitem><para>In Eclipse, select File/Import/JSF Project.</para></listitem> +<listitem><para>Click Next.</para></listitem> +<listitem><para>Browse to where the project was unzipped.</para></listitem> +<listitem><para>Find the web.xml file inside the WebContent folder in the WEB-INF folder, select it, and Click Finish.</para></listitem> +</orderedlist> +<para>The ormHibernate3-jsf project should appear in the Package Explorer with a standard Web application +structure. As we mentioned before, this is a JSF application. To see the JSF configuration file, browse to + WebContent/WEB-INF/faces-config.xml.</para> +<para>In the JavaSource folder, you will find the following Java source files. We will briefly explain these + files and then run the application.</para> + <table> + <title>JavaSource Folder</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Class Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>demo/Address.java</entry> + <entry>holds the user address</entry> + </row> + <row> + <entry>demo/User.java</entry> + <entry>holds user information</entry> + </row> + <row> + <entry>demo/GetUserIdBean.java</entry> + <entry>holds user Id and determines navigation (JSF Backing Bean)</entry> + </row> + <row> + <entry>demo/UserFormBean.java</entry> + <entry>holds new user input (JSF Backing Bean)</entry> + </row> + <row> + <entry>demo.bundle/Messages.properties</entry> + <entry>holds label messages used in the application</entry> + </row> + </tbody> + </tgroup> + </table> +</section> + +<section id="RunningWithoutADatabase"> +<?dbhtml filename="RunningWithoutADatabase.html"?> +<title>Running Without a Database</title> + +<para>We are ready to run this project in a Web browser and see how it looks. We don&apos;t need to + compile these classes, because Eclipse did it for us when we imported the project.</para> + +<orderedlist continuation="continues"> +<listitem><para>Start Tomcat.</para></listitem> +<listitem><para>Click on the running-man-and-blue-butterfly icon from the toolbar.</para></listitem> +<listitem><para>Go ahead and play with the application.</para></listitem> +</orderedlist> +<para>Initially users don&apos;t exist, so entering any ID will prompt you to enter user details. Once you have saved a user, you can go back to the main page by clicking on the Back to Login Page link. If you then enter that user&apos;s id again, the application will locate and display the user&apos;s details.</para> + +</section> + +<section id="ConvertingforUseWithaDatabase"> +<?dbhtml filename="ConvertingforUseWithaDatabase.html"?><title>Converting for Use With a Database</title> +<para>Now we are ready to convert this application to use with a database with the help of ExadelStudio. To convert the application for use with a database, we need to set things up in three different places:</para> + + +<itemizedlist><listitem><para>The Application</para></listitem></itemizedlist> +<itemizedlist><listitem><para>The Database</para></listitem></itemizedlist> +<itemizedlist><listitem><para>The Application Server</para></listitem></itemizedlist> + +</section> + +<section id="SettingUpTheApplication"> +<?dbhtml filename="SettingUpTheApplication.html"?> +<title>Setting up the Application</title> +<para>Setting up the Application</para> +<para>Let&apos;s start by using Red Hat Developer Studio with the application project. First, we create +the object/relational mapping from our simple object model to a database schema after adding Hibernate +capabilities to our project.</para> +<orderedlist continuation="continues"> +<listitem><para>Right-click on ormHibernate3-jsf in the Package Explorer view and select Exadel</para></listitem> +<listitem><para>Studio/Add Hibernate Capability... from the context menu.</para></listitem> +<listitem><para>Click on Yes in the the dialog box with Add Hibernate Jars selected.</para></listitem> +<listitem><para>In the Configuration Wizard, click twice in the Value field for dialect and select org.hibernate.dialect.HSQLDialect from the pop-up menu.</para></listitem> +<listitem><para>Click Finish</para></listitem> +<listitem><para>Select Object to Schema for the Mapping Approach.</para></listitem> +</orderedlist> +<para>We are only interested in saving the User class in a database, so we are going to create a mapping for the User class to a database table.</para> +<orderedlist continuation="continues"> +<listitem><para>In the Persistent Classes Wizard dialog that appears next, click on the SelectClasses.</para></listitem> +<listitem><para>Leave all other values as they are in the next dialog box and click Finish.</para></listitem> +</orderedlist> +</section> + +<section id="EditTheHibernateConfiguration"> +<?dbhtml filename="EditTheHibernateConfiguration.html"?> +<title>Edit the Hibernate Configuration</title> +<para>Afterwards, the Hibernate configuration file, hibernate.cfg.xml, will appear in an editor window. +So, let&apos;s adjust this file first.</para> + +<orderedlist continuation="continues"> +<listitem><para>Replace these two lines:</para></listitem> +</orderedlist> + + +<programlisting role="XML"><![CDATA[<property +name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</ +property> +<property +name="hibernate.connection.url">jdbc:hsqldb:hsql:[hostname]</ +property> +]]></programlisting> + +<para>With this single line:</para> + +<programlisting role="XML"><![CDATA[ +<property name="hibernate.connection.datasource">java:comp/env/ +jdbc/kickstart</property> +]]></programlisting> +<para>(Make sure this is one line in the file and not two lines as displayed because of wordwrapping.)</para> +<para>Your file should now look like this:</para> + +<programlisting role="XML"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration +DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> +<hibernate-configuration> +<session-factory> +<property name="hibernate.connection.datasource">java:comp/env/jdbc/ +kickstart</property> +Exadel Studio 3.0 +page 4 of 10 +<property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</ +property> +<mapping resource="demo/User.hbm.xml"/> +</session-factory> +</hibernate-configuration> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Save the file.</para></listitem> +</orderedlist> +</section> + +<section id="EdittheMappingFile"> +<?dbhtml filename="EdittheMappingFile.html"?> +<title>Edit the Mapping File</title> +<para>Next, we need to make on slight change to the mapping file, User.hbm.xml.</para> + +<orderedlist continuation="continues"> +<listitem><para>In the ORM Explorer view, reveal the +ormHibernate3-jsf/JavaSource/hibernate.cfg.xml/demo/User -> user node, right-click it, and select +Open Mapping from the context menu.</para></listitem> +<listitem><para>In the editor that opens up for the mapping file, just change the class +attribute for generator to a value of assigned and you&apos;re done with this file.</para></listitem> +</orderedlist> + + +<para>Here is what the edited User.hbm.xml file should now look like:</para> + +<programlisting role="XML"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" +<para>"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"></para> +<hibernate-mapping package="demo"> +<class name="User" table="user" optimistic-lock="none"> +<id name="id" type="string" unsaved-value="null" column="id"> +<generator class="assigned"/> +</id> +<property name="firstName" type="string" column="first_name"/> +<property name="lastName" type="string" column="last_name"/> +<property name="email" type="string" column="email"/> +<component name="address" update="true" insert="true" class="demo.Address"> +<property name="city" type="string" column="address_city"/> +<property name="state" type="string" column="address_state"/> +<property name="street" type="string" column="address_street"/> +<property name="zip" type="string" column="address_zip"/> +</component> +</class> +</hibernate-mapping> +]]></programlisting> + + +<orderedlist continuation="continues"> +<listitem><para>Save the file.</para></listitem> +</orderedlist> +</section> +<section id="AddAGeneralClassForIncorporatingHibernate"> +<?dbhtml filename="AddAGeneralClassForIncorporatingHibernate.html"?> +<title>Add a General Class for Incorporating Hibernate</title> +<para>Next, we will need to create a special Java class for incorprating Hibernate into our application.</para> + +<orderedlist continuation="continues"> +<listitem><para>Switch to the Package Explorer view and create the class, +HibernateHelper.java, in JavaSource/demo with this content and save it.</para></listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[ +package demo; +import org.hibernate.HibernateException; +import org.hibernate.Session; +import org.hibernate.SessionFactory; +import org.hibernate.cfg.Configuration; +public class HibernateHelper { +/** +* Reference to SessionFactory. +*/ +private static SessionFactory sf; +public static final ThreadLocal session = new ThreadLocal(); +public static synchronized void init() { +if (sf != null) return; +System.out.println("Initializing Hibernate"); +try { +Configuration cfg = new Configuration().configure(); +sf = cfg.buildSessionFactory(); +} catch (Exception he) { +System.err.println("Unable to create session factory from +configuration"); +he.printStackTrace(); +throw new RuntimeException("Unable to create session factory from +configuration", he); +} +System.out.println("Hibernate initialized"); +} +/** +* Return the SessionFactory. +* @return The SessionFactory for this application session +*/ +public static SessionFactory sessionFactory() { +if (sf == null) init(); +return sf; +} +public static void destroy() { +if (sf != null) { +try { +sf.close(); +} catch (HibernateException he) { +he.printStackTrace(); +} +} +sf = null; +System.out.println("Hibernate resources released"); +} +/** +* Closes an hibernate {@link Session}, releasing its resources. +* @throws HibernateException if an hibernate error occurs +*/ +public static void closeSession() throws HibernateException { +Session s = (Session)session.get(); +session.set(null); +if (s != null) { +s.close(); +Exadel Studio Pro +page 6 of 9 +} +} +/** +* Returns an hibernate {@link Session} from the session factory. +* @return an hibernate {@link Session} +* @throws HibernateException if an error occurs +*/ +public static Session openSession() throws HibernateException { +if (sf == null) init(); +Session s = (Session)session.get(); +if (s == null) { +s = sf.openSession(); +session.set(s); +} +return (s); +} +} +]]></programlisting> +</section> + +<section id="EdittheTwoBeanClasses"> +<?dbhtml filename="EdittheTwoBeanClasses.html"?> +<title>Edit the Two Bean Classes</title> + +<para>We also need to modify the two bean classes in our application to &quot;Hibernate-ize&quot; them.</para> + +<orderedlist continuation="continues"> +<listitem><para>Modify the GetUserIdBean.java class in JavaSource/demo by adding these imports: + +</para></listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[import org.hibernate.Session; +import javax.faces.application.FacesMessage; +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Then, replace the action() method with this code and save.</para></listitem> + +</orderedlist> +<programlisting role="JAVA"><![CDATA[{ +public String action() +throws Exception +UserFormBean ufb; +User user; +String actionResult = "inputuser"; // new user by default +Map sessionMap = +FacesContext.getCurrentInstance().getExternalContext().getSessionMap(); +if (sessionMap != null) { +ufb = new UserFormBean(); +ufb.setId(id); +try { +Session hSession = HibernateHelper.openSession(); +user = (User)hSession.get(User.class, id); +HibernateHelper.closeSession(); +} catch (Exception e) { +FacesContext context = FacesContext.getCurrentInstance(); +context.addMessage(null, new +FacesMessage(FacesMessage.SEVERITY_ERROR,e.toString(), null)); +return "failed"; +} +if (user==null || !user.getId().equals(id)) { +user = new User(); +user.setId(id); +sessionMap.put("user", user); +} else { +// fill UserFormBean with user information +loadUser(ufb,user); +actionResult="greeting"; +} +sessionMap.put("UserFormBean", ufb); +} +return actionResult; +} +private void loadUser(UserFormBean userForm,User user) { +userForm.setId(user.getId()); +userForm.setFirstName(user.getFirstName()); +userForm.setLastName(user.getLastName()); +userForm.setEmail(user.getEmail()); +userForm.setStreet(user.getAddress().getStreet()); +userForm.setCity(user.getAddress().getCity()); +userForm.setState(user.getAddress().getState()); +userForm.setZip(user.getAddress().getZip()); +} +]]></programlisting> + +<orderedlist continuation="continues"> +<listitem><para>Modify the UserFormBean.java class in JavaSource/demo by adding these + imports:</para></listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[import org.hibernate.Session; +import org.hibernate.Transaction; +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Then, replace the save() method with this code and save the class.</para></listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[public String save() throws Exception { +Map sessionMap = +FacesContext.getCurrentInstance().getExternalContext().getSessionMap(); +if (sessionMap != null) { +UserFormBean ufb=(UserFormBean)sessionMap.get("UserFormBean"); +try { +Session hSession = HibernateHelper.openSession(); +Transaction tran = hSession.beginTransaction(); +User user = (User)hSession.get(User.class, id); +if (user == null) { +user = new User(); +user.setId(id); +hSession.save(user); +} +saveUser(ufb, user); +tran.commit(); +HibernateHelper.closeSession(); +} catch (Exception e) { +return "failed"; +} +} +return "greeting"; +} +]]></programlisting> + +</section> + +<section id="SettinguptheDatabase"> +<?dbhtml filename="SettinguptheDatabase.html"?> +<title>Setting up the Database</title> +<para>To set up the database end, we need to use Red Hat Developer Studio and our HSQL database engine to create a +database table corresponding to the class we are trying to persist and make the database available.</para> + +</section> +<section id="CreatingtheDatabaseTable"> +<?dbhtml filename="CreatingtheDatabaseTable.html"?> +<title>Creating the Database Table</title> +<para>Let&apos;s first create the script for our database table in Red Hat Developer Studio.</para> +<orderedlist continuation="continues"> +<listitem><para>In the ORM Explorer view, right-click on JavaSource/hibernate.cfg.xml and select "Generate DDL Wizard".</para></listitem> + +<listitem><para>Select HSQL as the Dialect and leave Location as is.</para></listitem> +<listitem><para>Click Finish.</para></listitem> +</orderedlist> +<para>A DDL file called schema.sql will be created in the root of the project and will be opened in an + editor window.</para> + </section> + <section id="MakingTheDatabaseAvailableForTheApplication"> + <?dbhtml filename="MakingTheDatabaseAvailableForTheApplication.html"?> +<title>Making the Database Available for the Application</title> +<para>The databse server, HSQLDB, is provided with the project. It&apos;s located in the ormHibernate3-jsf/hsqldb folder.</para> +<orderedlist continuation="continues"> +<listitem><para>Start the database server: .../ormHibernate3-jsf/hsqldb/bin/server.bat</para></listitem> +<listitem><para>In a separate window, start the admin tool: .../ormHibernate3-jsf/hsqldb/bin/dbadmin.bat</para></listitem> +</orderedlist> +<para>This will launch a small GUI application, HSQL Database Manager.</para> +<orderedlist continuation="continues"> +<listitem><para>Leave all values as they are, only change URL: to the following: jdbc:hsqldb:hsql://localhost</para></listitem> +<listitem><para>Click OK.</para></listitem> +<listitem><para>Select File/Open Script... from the menu bar of HSQL Database Manager.</para></listitem> +<listitem><para>Find and open the the DDL file we just created.</para></listitem> +<listitem><para>Click Execute back in the main screen of the Database Manager.</para></listitem> +<listitem><para>38. Select View/Refresh Tree from the menu bar.</para></listitem> +</orderedlist> +<para>The User database should now appear in the expand/collapse tree to the left.</para> +<orderedlist continuation="continues"> +<listitem><para>Select File/Exit from the menu bar.</para></listitem> +<listitem><para>Stop the database server: .../ormHibernate3-jsf/hsqldb/bin/shutdown.bat</para></listitem> +</orderedlist> +</section> + +<section id="SettinguptheApplicationServer"> +<?dbhtml filename="SettinguptheApplicationServer.html"?> +<title>Setting up the Application Server</title> + +<para>Finally, we need to set up the application server before we can run the database-enabled +application in a Web browser. To do this, we&apos;ll need to modify the application context in the- +Tomcat server.xml file.</para> +<orderedlist continuation="continues"> +<listitem><para>Stop the Tomcat server, if it&apos;s running.</para></listitem> +<listitem><para>Locate the server.xml file in the Package Explorer view under the Tomcat Server +node under Servers.</para></listitem> +<listitem><para>Double-click the file to open an editor on it.</para></listitem> +<listitem><para>Find the Context tag for your application in the file. It will have a path attribute +with a value of /ormHibernate3-jsf.</para></listitem> +</orderedlist> +<para>You&apos;ll need to convert this &quot;empty&quot; XML element into one with beginning and ending tags, +so we can insert the special resource tags for Tomcat to run this application with a database.</para> +<orderedlist continuation="continues"> +<listitem><para>Delete the closing slash at the end of the Context tag.</para></listitem> +<listitem><para>Insert a blank line after the tag and then start another line.</para></listitem> +<listitem><para>On this line, insert a closing tag:</para></listitem> +</orderedlist> +<programlisting role="JAVA"><![CDATA[</Context> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>On the blank line between the starting and ending tags, add the following resource definition coding.</para></listitem> +</orderedlist> +<programlisting role="XML"><![CDATA[<Resource name="jdbc/kickstart" scope="Shareable" +type="javax.sql.DataSource"/> +<ResourceParams name="jdbc/kickstart"> +<parameter> +<name>factory</name> +<value>org.apache.commons.dbcp.BasicDataSourceFactory</ +value> +</parameter> +<parameter> +<name>url</name> +<value>jdbc:hsqldb:hsql://localhost</value> +</parameter> +<parameter> +<name>driverClassName</name> +<value>org.hsqldb.jdbcDriver</value> +</parameter> +<parameter> +<name>username</name> +<value>sa</value> +</parameter> +<parameter> +<name>password</name> +<value></value> +</parameter> +<parameter> +<name>maxWait</name> +<value>3000</value> +</parameter> +<parameter> +<name>maxIdle</name> +<value>100</value> +</parameter> +<parameter> +<name>maxActive</name> +<value>10</value> +</parameter> +</ResourceParams> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Finally, copy .../ormHibernate3-jsf/hsqldb/lib/hsqldb.jar to your +Tomcat .../common/lib folder.</para></listitem> +</orderedlist> +</section> + +<section id="RunningOurNewApplication"> +<?dbhtml filename="RunningOurNewApplication.html"?> +<title>Running Our New Application</title> +<orderedlist continuation="continues"> +<listitem><para>Start the database server: .../ormHibernate3-jsf/hsqldb/bin/server.bat</para></listitem> +<listitem><para>Start the Tomcat server.</para></listitem> +<listitem><para>Run the application.</para></listitem> +</orderedlist> +<para>Play with the application. Restart Tomcat and the database server. If you run the application +again and enter a user that you already saved, the application should retrieve it from the database +and display its details.</para> +</section> +</chapter> Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJavaServerFaces.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJavaServerFaces.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedGuideforJavaServerFaces.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,1271 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter id="GettingStartedGuideforJavaServerFaces" xreflabel="GettingStartedGuideforJavaServerFaces"> + <?dbhtml filename="GettingStartedGuideforJavaServerFaces.html"?> + <title>Getting Started Guide for Java Server Faces</title> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>RHDS</keyword> + <keyword>Java</keyword> + <keyword>JSF Component</keyword> + </keywordset> + </chapterinfo> +<section id="Introduction"> +<?dbhtml filename="Introduction.html"?> +<title>Introduction</title> +<para>JavaServer Faces is a technology that helps to build a user interface based on the +components approach. Using UI Components as building blocks simplifies the development, +slashes the number of code lines, and allows reusing the same components from one project to +the next.</para> +<para>What are the components we are speaking about? The Sun reference implementation of JSF +provides just a few very common components for Web forms, primitive tags for page layout, and +&quot;dataTable&quot; as a way to show the data set. The open source implementations of JSF don&apos;t +provide much more. The commercial implementation of GUI Tools for JSF such as WebSphere +Application Developer and Java Studio Creator do come with significant additions to the set of +components that allows creating interfaces similar to that of Swing applications. However, +traditionally, the Web interface lacks all of the richness of thick-client analogs. A customer +might have an existing design that is not covered by the set of standard controls. Third-party +components vendors will try to create the most common components with a multitude of custom +parameters, but still these do not match the requirements for an individual Web application.</para> +<para>The JSF Specification in Section 1.2.2 mentions the Component Writer role along with Page +Writer and Application Developer roles. Writing a specific component set for a particular Web +application might be a good solution instead of trying to use existing ones that a customer might +not even accept.</para> +<para>Is it easy to write your own JSF UI component? Sun&apos;s J2EE tutorial provides a section +dedicated to this topic. This paragraph describes an example with Map components giving an +overview of almost all the features you might need in developing your own components. +However, the example itself seems too complicated to use it as a beginning &quot;kick start&quot; type of +application. It gives a good overview of the technology, but does not give enough details for the +specific steps you would need to go through to write your own components.</para> +<para>This tutorial is dedicated to closing this gap. It is written in a step-by-step manner where +each step is extremely easy to understand. The provided example does not cover all the aspects +of components development, but it is a very good start to understand the idea. Topics not covered +in this tutorial are set forth in the last section.</para> +</section> +<section id="BuildingInstructionsForThisTutorial"> +<?dbhtml filename="BuildingInstructionsForThisTutorial.html"?> +<title>Building Instructions for This Tutorial</title> +<para>The tutorial consists of seven separate steps for building up an example application. Each +step adds new code to the previous example. The tutorial includes code representing the result of +each step. If you are lost, you can compare these target results with your results. Also, you might +want to add some extra feature to the code to test how it works. If this messes things up, you can +just replace your code with the included code to go on to the next step.</para> +<para>The tutorial material is divided into seven folders with the names Step1, Step2, Step3, Step4, +Step5, Step6, and Step7. Each folder contains only one subfolder named &quot;ticker&quot;. This subfolder +contains a working example that represents the result up to that particular step. Additionally, a +folder named Step0 contains the skeleton for starting the JSF project.</para> +<para>For this tutorial, you can use any tools that allow you to work directly with source code. We +recommend you to use Red Hat Developer Studio. Developer Studio allows the running of JSF applications +without redeployment. This is extremely important when you play with the code by adding new +features to test how they work. At the same time, Developer Studio allows you to have full control over +the source code. We even recommend turning on the &quot;Use Source Tab as a default for multi-tab +editors&quot; option in the Preferences Editor (Red Hat->Editors section). You can always use the GUI +feature of Developer Studio later to slash the development time when you start to understand enough +how things works on the source code level. The provided example is fully adapted to work with +Red Hat Developer Studio.</para> +<para>Red Hat Developer Studio allows debugging Web applications in the same manner in which you can +debug a regular Java application within the Eclipse environment. This is an extremely important +feature for learning.</para> +<para>To start working with the tutorial example, copy the &quot;ticker&quot; folder to a new place on the +disk. If you use Red Hat Developer Studio, copy this folder to the Eclipse workspace folder (or wherever you +usually keep projects) and then import this project using the Eclipse File->Import menu. Leave +the server.xml registration option checked on the second screen of wizard. This allows you to +change and then run an application without any special redeployment.</para> +<para>Each ticker folder contains four subfolders:</para> +<itemizedlist> +<listitem><para>Ant</para></listitem> +<listitem><para>ExtLib</para></listitem> +<listitem><para>JavaSource</para></listitem> +<listitem><para>WebContent</para></listitem> +</itemizedlist> +<section id="AntFolder"> +<?dbhtml filename="AntFolder.html"?> +<title>Ant Folder</title> +<para>The ant folder contains the build.xml file that can be used to compile the example and +deploy it to a target servlet container to run. In order to use this script be sure that ant is in your +system path. The default Ant target is &quot;deploy&quot;, so if you launch Ant without parameters, it +create an additional folder named deploy and puts the deployable war file into it. If you want, +you can provide another folder as the target for deployment. Open the build.xml file for editing +and set the &quot;deploy-dir&quot; Ant property to the different target folder.</para> +</section> +<section id="ExtLibFolder"> +<?dbhtml filename="ExtLibFolder.html"?> +<title>ExtLib Folder</title> +<para>The ExtLib folder just contains the servlet.jar file that is required to be in the classpath to +have the code compiled. This jar file is added to the classpath only when you use the Ant script. +(This file is not used by Developer Studio). If you want, you can any replace it with you own library +that contains required classes for compilation. Replace the property with name &apos;servlet.path&apos; for +this purpose.</para> +</section> +<section id="JavaSourceFolder"> +<?dbhtml filename="JavaSourceFolder.html"?> +<title>JavaSource Folder</title> +<para>The JavaSource folder contains the java source files and resource bundle files.</para> +</section> +<section id="WebContentFolder"> +<?dbhtml filename="WebContentFolder.html"?> +<title>WebContent Folder</title> +<para>The WebContent folder contains the pre-deployment structure for a standard J2EE +application.</para> +</section> +<section id="RootFolder"> +<?dbhtml filename="RootFolder.html"?> +<title>Root Folder</title> +<para>Additionally, the root folder contains four files start with dot. Those files contain the +configuration for JSF Studio only.</para> +</section> +</section> +<section if="GeneralTipsForBuildingComponents"> +<?dbhtml filename="GeneralTipsForBuildingComponents.html"?> +<title>General Tips for Building Components</title> +<para> +<itemizedlist> +<listitem>Simulate a rendered result before implement it. Use any HTML editor with a +preview option to see how the HTML you are going to produce works buy itself. If +some HTML construction doesn&apos;t work for you, you save time seeing the problem +before you start to implement the component that produces the unsatisfactory HTML +code.</listitem> +<listitem>Localize the JavaScript functions. If the rendered code contains JavaScript, be sure +this JavaScript code doesn&apos;t collide with JavaScript coding in other components that +will work on the same page.</listitem> +<listitem>Test how your component works together with other JSF Components. Check the +situation where your components insert other components or are themselves inserted +as children for other components.</listitem> +<listitem>Check how the rendered code works in the different browser. Avoid browser-specific +tags or attributes.</listitem> +</itemizedlist> +</para> +</section> +<section id="Step1ComponentsSkeleton"> +<?dbhtml filename="Step1ComponentsSkeleton.html"?> +<title>Step 1: Components Skeleton</title> +<para>Before we start, let&apos;s see what we have at the beginning. The initial project taken from the +Step0 folder contains a short example that does nothing except open the bannerpage.jsp page +when the application starts. This JSP page will be used as a testing area for testing the rendered +component output.</para> +<para>After the final step we have got a scrollable area with the text inside. It will look like the +following picture:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<para>In the first step we create a component that will be rendered into the following code in the +resulting HTML page:</para> +<programlisting role="HTML"><![CDATA[<div>Hello JSF Component</div> +]]></programlisting> +<para>On the original JSF page we will have:</para> +<programlisting role="HTML"><![CDATA[<d:ticker> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +]]></programlisting> +<para>Let&apos;s start with creating the tag library definition file. Open the WEB-INF folder and create +a &quot;ticker.tld&quot; file that contains the following code:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" +"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> +<taglib> +<tlib-version>1.0</tlib-version> +<jsp-version>1.2</jsp-version> +<short-name>d</short-name> +<uri>http://jsftutorials.com/</uri> +<tag> +<name>ticker</name> +<tag-class>ticker.TickerTag</tag-class> +<body-content>JSP</body-content> +</tag> +</taglib> +]]></programlisting> +<para>We have declared the new tag with the name &quot;ticker&quot;and defined ticker.TickerTag as a tag +class. Open JavaSource folder; create a package &quot;ticker&quot; there and the class TickerTag there that +contains the following code:</para> +<programlisting role="JAVA"><![CDATA[package ticker; +import javax.faces.component.UIComponent; +import javax.faces.webapp.UIComponentTag; +public class TickerTag extends UIComponentTag{ +public void release() { +// the super class method should be called +super.release(); +} +protected void setProperties(UIComponent component) { +// the super class method should be called +super.setProperties(component); +} +public String getComponentType() { +return "ticker"; +} +public String getRendererType() { +// null means the component renders itself +return null; +} +} +]]></programlisting> +<para>The class TickerTag processes the <emphasis role="italic"><property>&quot;tag&quot;</property></emphasis> attribute. Such a class name has the suffix &quot;Tag&quot; by a +naming convention. The TickerTag class extends UIConponentTag and implements four +methods.</para> +<para>The getComponentType() method returns the symbolic name of the component type. We +will define the class for this type latter in the faces-config file.</para> +<para>The getRendererType() method returns the symbolic name of the renderer. If +getRendererType() returns null, it means that the renderer name is not defined and the +component will render it by itself.</para> +<para>The release() method releases any resources allocated during the execution of this tag +handler. We will use this method to reset the attribute values. The release() method should call +the release() method of the super class.</para> +<para>And the last (but not least) method, setProperties(UIComponent component), is used to pass +attributes taken from the JSP page to the renderer. You can use the JSF Expression Language in +the value for the tag attribute. This is also resolved by the setProperties method. We will return +back to this theme in step 4 of this tutorial.</para> +<para>Now let&apos;s define the component class for the component type declared above. Open WEBINF/ +faces-config.xml and put the declaration there. The faces-config.xml should contain the +following code:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" +"http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> +<faces-config> +<component> +<component-type>ticker</component-type> +<component-class>ticker.UITicker</component-class> +</component> +<lifecycle/> +<application> +<locale-config/> +</application> +<factory/> +</faces-config> +]]></programlisting> +<para>We have defined the ticker.UITicker class as a component class for the &quot;ticker&quot; type. By a +naming convention, such a class starts with the &quot;UI&quot; prefix. The component class provides a +rendering user interface, state saving and restoring, and processing of user input.</para> +<para>Create the tickerUITicker class with the following content:</para> +<programlisting role="JAVA"><![CDATA[package ticker; +import java.io.IOException; +import javax.faces.component.UIOutput; +import javax.faces.context.FacesContext; +import javax.faces.context.ResponseWriter; +public class UITicker extends UIOutput { +public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +} +public void encodeEnd(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.endElement("div"); +} +} +]]></programlisting> +<para>Because our custom component does not provide for any user input, we extend the class +from the UIOutput. The UITicker class implements two methods encodeBegin(FacesContext +context) and encodeEnd(FacesContext context). The first method encodes the opening tag; the +second one encodes the closing tag. However, if your tags do not contain a body, it is +recommended to encode everything using only the encodeEnd(FacesContext context) method.</para> +<para>Now let&apos;s create the page where our custom tag will be used. Open the bannerpage.jsp page +located inside the WebContent folder and add a taglib declaration and our tag with test output. +The page should look like:</para> +<programlisting role="XML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<html> +<head> +<title>Show Custom Component</title> +</head> +<body> +<f:view> +<d:ticker> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +</f:view> +</body> +</html> +]]></programlisting> +<para>There are two things important to mention here. The first thing concerns the URI attribute. +Many people think that this attribute must be a reference to an existing URL, but this is not quite +true. A URI is not the same as a URL. The target of this attribute is defining the unique string +that will distinguish this particular taglib from the others.</para> +<para>The second important thing is using <emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> <emphasis role="bold"><property>&lt;/f:verbatim&gt;</property></emphasis> around the plain text. When +the JSF Components tree is rendered, it contains only the JSF Components. So, any children in +the hierarchy must be JSF components. If you run the first example, there might not be any +difference, because <emphasis role="bold"><property>&lt;d:ticker&gt;</property></emphasis> is a root node of the JSF Component hierarchy. However, in case +you add <emphasis role="bold"><property>&lt;h:gridPanel&gt;</property></emphasis>, for example, around it, you will find that the plain text without +<emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> will be pushed out of the <emphasis role="bold"><property>&lt;div&gt;</property></emphasis><emphasis role="bold"><property>&lt;/div&gt;</property></emphasis> in the rendered page.</para> +<para>At this point, our first step has been finished. We can compile, deploy, and run the result +application. If you use Ant to do this job, run Ant so that the ticker.war file is copied to the +servlet container to run.</para> +<para>If you&apos;re using Red Hat Developer Studio, click the Start Tomcat Server button on the toolbar, and then +click the Run Web Application button. The default browser should be launched and show the +result of page rendering.</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<para>You can see the &quot;Hello JSF Component&quot; text in the browser window. Because <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> itself +does not provide any visual effect, you can recognize that the page is rendered as we expected +only if you look at the source of the result page. It should contain the &quot;<emphasis role="bold"><property>&lt;div&gt;</property></emphasis>Hello JSF +Component<emphasis role="bold"><property>&lt;/div&gt;</property></emphasis>&quot; text. If so, the first step is done. You have already written you first JSF +Component. Of course, it has very limited functionality, but we just laid the foundation. The +component will be improved in the next step.</para> +<para>Before we go any further, let&apos;s survey the relationships among the different JSF artifacts we +are using here. The following picture shows this relationship:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +</section> +<section id="Step2AddingSimpleAttributes"> +<?dbhtml filename="Step2AddingSimpleAttributes.html"?> +<title>Step 2: Adding Simple Attributes</title> +<para>This step is devoted to adding attributes to our custom tag. As we mentioned for the first +step, tag <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> does not provide any visible effect. So, in the second step, we will add attributes +that make more visible results. Commonly, visual JSF tags define the tag style directly with style +and styleClass attributes or indirectly by using the Cascading Style Sheet file.</para> +<para>Let&apos;s start with the style attribute. Add it to the JSP page. The JSP page will look like this:</para> +<programlisting role="HTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<html> +<head> +<title>Show Custom Component</title> +</head> +<body> +<f:view> +<d:ticker style="border:1px solid darkblue;width:100px"> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +</f:view> +</body> +</html> +]]></programlisting> +<para>Add the tag attribute to the ticker.tld file:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" +"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> +<taglib> +<tlib-version>1.0</tlib-version> +<jsp-version>1.2</jsp-version> +<short-name>d</short-name> +<uri>http://jsftutorials.com/</uri> +<tag> +<name>ticker</name> +<tag-class>ticker.TickerTag</tag-class> +<body-content>JSP</body-content> +<attribute> +<name>style</name> +</attribute> +</tag> +</taglib> +]]></programlisting> +<para>Add the following code marked with bold to the TickerTag class:</para> +<programlisting role="JAVA"><![CDATA[import javax.faces.component.UIComponent; +import javax.faces.webapp.UIComponentTag; +public class TickerTag extends UIComponentTag{ +String style; +public String getStyle() { +return style; +} +public void setStyle(String style) { +this.style = style; +public void release() { +// the super class method should be called +super.release(); +style = null ; +} +protected void setProperties(UIComponent component) { +// the super class method should be called +super.setProperties(component); +if(style != null) +component.getAttributes().put("style", style); +} +public String getComponentType() { +return "ticker"; +} +public String getRendererType() { +// null means the component renders itself +return null; +} +} +]]></programlisting> +<para>First, we have added a new property with the name &quot;style&quot; and provided the getter and setter +for it. Then, we reset the property in the release() method. Finally, we have set the new value for +the component property in the setProperties(UIComponent component) method. The last step is +important. If you forget to do so, you cannot get to the value in the component type class later +on.</para> +<para>Add the code marked with bold to the ticker.UITicker class:</para> +<programlisting role="JAVA"><![CDATA[import java.io.IOException; +import javax.faces.component.UIOutput; +import javax.faces.context.FacesContext; +import javax.faces.context.ResponseWriter; +public class UITicker extends UIOutput { +public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +String style = (String)getAttributes().get("style"); +if (style!=null) +writer.writeAttribute("style", style, null); +} +public void encodeEnd(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.endElement("div"); +} +} +]]></programlisting> +<para>In the first added line, we have taken the value of the style attribute, checked if it&apos;s set, and +then assigned the style attribute with the new value. Do not forget to check for null, otherwise +you will get a NullPointer Exception when a tag without this attribute set is rendered.</para> +<para>Now, we are done with the style attribute. If you use Red Hat Developer Studio just click the Run Web +Application button to get a result. If you are using an Ant script, run it, deploy the result war file +under the servlet container, then launch your browser and type the application URL.</para> +<para>The result page should see the box with dark blue border and the Hello JSF Component text +inside this box.</para> +<para>Adding the styleClass component is very similar to what we did for style. Here is a +bannerpage.jsp content:</para> +<programlisting role="HTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<html> +<head> +<title>Show Custom Component</title> +<style> +.banner { +border: 1px solid darkblue; +padding: 5px 5px 5px 5px; +} +</style> +</head> +<body> +<f:view> +<d:ticker styleClass="banner" style="width:100px"> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +</f:view> +</body> +</html> +]]></programlisting> +<para>This is the ticker.tld file content:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" +"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> +<taglib> +<tlib-version>1.0</tlib-version> +<jsp-version>1.2</jsp-version> +<short-name>d</short-name> +<uri>http://jsftutorials.com/</uri> +<tag> +<name>ticker</name> +<tag-class>ticker.TickerTag</tag-class> +<body-content>JSP</body-content> +<attribute> +<name>style</name> +</attribute> +<attribute> +<name>styleClass</name> +</attribute> +</tag> +</taglib> +]]></programlisting> +<para>This is the TickerTag.java class content:</para> +<programlisting role="JAVA"><![CDATA[import javax.faces.component.UIComponent; +import javax.faces.webapp.UIComponentTag; +public class TickerTag extends UIComponentTag{ +String style; +String styleClass; +public String getStyle() { +return style; +} +public void setStyle(String style) { +this.style = style; +} +public String getStyleClass() { +return styleClass; +} +public void setStyleClass(String styleClass) { +this.styleClass = styleClass; +} +public void release() { +// the super class method should be called +super.release(); +style = null ; +styleClass = null ; +} +protected void setProperties(UIComponent component) { +// the super class method should be called +super.setProperties(component); +if(style != null) +component.getAttributes().put("style", style); +if(styleClass != null) +component.getAttributes().put("styleClass", styleClass); +} +public String getComponentType() { +return "ticker"; +} +public String getRendererType() { +// null means the component renders itself +return null; +} +} +]]></programlisting> +<para>This is the UITicker.java file content:</para> +<programlisting role="JAVA"><![CDATA[import java.io.IOException; +import javax.faces.component.UIOutput; +import javax.faces.context.FacesContext; +import javax.faces.context.ResponseWriter; +public class UITicker extends UIOutput { +public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +String style = (String)getAttributes().get("style"); +if (style!=null) +writer.writeAttribute("style", style, null); +String styleClass = (String)getAttributes().get("styleClass"); +if (styleClass!=null) +writer.writeAttribute("class", styleClass, null); +} +public void encodeEnd(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.endElement("div"); +} +} +]]></programlisting> +<para>Now, step 2 is done. Run the resulting application. The browser window should show the +bordered box with the Hello JSF Component text inside. Unlike the previous run, you will see 5 +pixels of space between the text and the border.</para> +</section> +<section id="Step3AddingJSFSupportAttributes"> +<?dbhtml filename="Step3AddingJSFSupportAttributes.html"?> +<title>Step 3: Adding JSF Support Attributes</title> +<para>Looking at the source code of pages rendered by the JSF run-time you can see that most +components have an id. They have this attribute assigned even you don&apos;t explicitly define it for +the JSF tags.</para> +<para>Also, JSF has its own naming convention for the component id. While you might specify +something like id=&quot;myId&quot; for h:inputText, the rendered code will contain something like +id=&quot;_id0:myId&quot;. This is done to ensure the uniqueness of each element in the JSF Component +tree. It is especially important for components that process user input. Having the full control +over the rendered code you can assign any value for id, but we recommend you to follow the +rules of the game.</para> +<para>In step 3, we will assign a value for our component that will be the same value that JSF runtime +assigns for it.</para> +<para>Any attribute should be present in the tag library definition file. So, open our ticker.tld file +and add the following code snippet next to the other tag attributes:</para> +<programlisting role="XML"><![CDATA[<attribute> +<name>id</name> +</attribute> +]]></programlisting> +<para>Add the following code marked with bold in the encodeBegin method of the UITicker.java:</para> +<programlisting role="JAVA"><![CDATA[public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +writer.writeAttribute("id", getClientId(context), null); +String style = (String)getAttributes().get("style"); +if (style!=null) +writer.writeAttribute("style", style, null); +String styleClass = (String)getAttributes().get("styleClass"); +if (styleClass!=null) +writer.writeAttribute("class", styleClass, null); +} +]]></programlisting> +<para>When you run the application at this point, you can see that the id attribute of the <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tag +is assigned. Because the id attribute has no visual effect, you have to open the source of the +resulting page to see it.</para> +<para>Provide your id for the <emphasis role="bold"><property>&lt;d:ticker&gt;</property></emphasis> component and run the application again. Then, you will +see that the id you have for the rendered code is the same that you assign. This happens because +the <emphasis role="bold"><property>&lt;d:ticker&gt;</property></emphasis> is a root element of the component tree. If you add <emphasis role="bold"><property>&lt;h:form&gt;</property></emphasis> or <emphasis role="bold"><property>&lt;h:subview&gt;</property></emphasis> +around it, you can the that the same prefix is added to the value you assigned for id.</para> +<para>We are done with <emphasis role="italic"><property>&quot;id&quot;</property></emphasis> attribute. Now, let&apos;s use the <emphasis role="italic"><property>&quot;rendered&quot;</property></emphasis> attribute. This attribute can +be used with any JSF Component, because it is inherited from the UIComponent class, the top +level of the JSF Component hierarchy. The <emphasis role="italic"><property>&quot;rendered&quot;</property></emphasis> attribute itself is not passed through to the HTML code as a tag attribute, but, if it has been set to “false,” the tag with all of its children will +not be rendered at all.</para> +<para>It is pretty easy to add a <emphasis role="italic"><property>&quot;rendered&quot;</property></emphasis> attribute. Just add it into the ticker.tld and all is set.</para> +<programlisting role="XML"><![CDATA[<attribute> +<name>rendered</name> +</attribute> +]]></programlisting> +<para>Add rendered=&quot;false&quot; to the <emphasis role="bold"><property>&lt;d:ticker&gt;</property></emphasis> tag, run the application and see what happens. The +browser should show the empty page. When you assign the &quot;true&quot; value, the page will show the +box with a greeting again.</para> +<para>This is a good time to show why <emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> is important for this construction. Remove +<emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> around the Hello JSF Component text, write rendered=&quot;false&quot; and run the +application. You can see that the box disappears, but the greeting text is still there. Looking at +the resulting code, you can realize that the <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tag is stripped out.</para> +</section> +<section id="Step4AttributeBinding"> +<?dbhtml filename="Step4AttributeBinding.html"?> +<title>Step 4: Attribute Binding</title> +<para>Attribute <emphasis role="bold"><property>&lt;binding&gt;</property></emphasis> is one of the most powerful JSF features. You can take the value from a +bean property or resource bundle property rather than just hardcode it into your JSP file. In step +4, we add one new attribute with the name &quot;title&quot; whose value will be taken from the resource +bundle instead of defining it directly in the JSP file (that&apos;s also possible).</para> +<para>In order to separate the designed component and the code that test it, lets create an additional +package with the name &quot;demo&quot; within the JavaSource folder. In the &quot;demo&quot; package, create the +file with the name &quot;resources.properties&quot; with the following content:</para> +<programlisting role="XML"><![CDATA[banner_title=Creating JSF Components. Step-By-Step Tutorial. +]]></programlisting> +<para>Add the new attribute with the name &quot;title&quot; to the ticker.tld file next to the other attribute of +the &quot;ticker&quot; tag.</para> +<programlisting role="XML"><![CDATA[<attribute> +<name>title</name> +</attribute> +]]></programlisting> + +<para>Add the text marked with bold to the ticker.TickerTag.java file:</para> +<programlisting role="JAVA"><![CDATA[package ticker; +import javax.faces.component.UIComponent; +import javax.faces.el.ValueBinding; +import javax.faces.webapp.UIComponentTag; +public class TickerTag extends UIComponentTag{ +String style; +String styleClass; +String title; +public String getStyle() { +return style; +} +public void setStyle(String style) { +this.style = style; +} +public String getStyleClass() { +return styleClass; +} +public void setStyleClass(String styleClass) { +this.styleClass = styleClass; +} +public String getTitle() { +return title; +} +public void setTitle(String title) { +this.title = title; +} +public void release() { +// the super class method should be called +super.release(); +style = null ; +styleClass = null ; +title = null; +} +protected void setProperties(UIComponent component) { +// the super class method should be called +super.setProperties(component); +if(style != null) +component.getAttributes().put("style", style); +if(styleClass != null) +component.getAttributes().put("styleClass", styleClass); +if (title != null) { +if (isValueReference(title)) { +ValueBinding vb = +getFacesContext().getApplication(). +createValueBinding(title); +component.setValueBinding("title", vb); +} else { +component.getAttributes().put("title", title); +} +} +} +public String getComponentType() { +return "ticker"; +} +public String getRendererType() { +// null means the component renders itself +return null; +} +} +]]></programlisting> +<para>The most important part of the added code is inside the SetProperties method. We check +there to see if this value is referenced and if so we create the value binding. Otherwise, we just +pass the value taken from the JSP page.</para> +<para>The other code is similar to what we did previously. Add the code marked with bold to the +encodeBegin method of the ticker.UITicker.java file:</para> +<programlisting role="HTML"><![CDATA[public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +writer.writeAttribute("id", getClientId(context), null); +String style = (String)getAttributes().get("style"); +if (style!=null) +writer.writeAttribute("style", style, null); +String styleClass = (String)getAttributes().get("styleClass"); +if (styleClass!=null) +writer.writeAttribute("class", styleClass, null); +String title = (String)getAttributes().get("title"); +if (title!=null) +writer.writeAttribute("title", title, null); +} +]]></programlisting> +<para>Add the following code marked with bold to the bannerpage.jsp file:</para> +<programlisting role="JSP"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<f:loadBundle basename="demo.resources" var="bundle" /> +<html> +<head> +<title>Show Custom Component</title> +<style> +.banner { +border: 1px solid darkblue; +padding: 5px 5px 5px 5px; +} +</style> +</head> +<body> +<f:view> +<d:ticker id="banner" +styleClass="banner" +style="width:100px" +rendered="true" +title="#{bundle.banner_title}"> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +</f:view> +</body> +</html> +]]></programlisting> +<para>We have added here the reference to our bundle and taken the banner_title property as a <emphasis role="italic"><property>&quot;title&quot;</property></emphasis> +attribute for the <emphasis role="bold"><property>&lt;d:ticker&gt;</property></emphasis> tag.</para> +<para>Now, we are done with step 4 of our tutorial. Run the application and hold the mouse cursor +over the box. The tip message should appear. If you look at the source code on the rendered +page, you can see the <emphasis role="italic"><property>&quot;title&quot;</property></emphasis> attribute set to a value taken from the resource bundle property.</para> +</section> +<section id="Step5ComponentBinding"> +<?dbhtml filename="Step5ComponentBinding.html"?> +<title>Step 5: Component Binding</title> +<para>One more powerful feature of the JSF technology is component binding. Unlike value +binding, component binding allows controlling all of the aspects of a bound component and its +child hierarchy from a Java class that is usually called a &quot;backing bean.&quot;</para> +<para>In step 5, we will demonstrate how this mechanism works. We will add a form with two +buttons to our bannerpage.jsp page. One button will hide the box for our greeting message; the +other button will return it back to the page. We will also create a backing bean that will control +the form and the component located inside the form.</para> +<para>Actually, the binding mechanism is provided by the super class of our component. All we +have to do it to add a new attribute with the name &quot;binding&quot; to the ticker.tld file. All other stuff +added on this step has a testing purpose.</para> +<para>So, this is our ticker.tld file content:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" +"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> +<taglib> +<tlib-version>1.0</tlib-version> +<jsp-version>1.2</jsp-version> +<short-name>d</short-name> +<uri>http://jsftutorials.com/</uri> +<tag> +<name>ticker</name> +<tag-class>ticker.TickerTag</tag-class> +<body-content>JSP</body-content> +<attribute> +<name>style</name> +</attribute> +<attribute> +<name>styleClass</name> +</attribute> +<attribute> +<name>id</name> +</attribute> +<attribute> +<name>rendered</name> +</attribute> +<attribute> +<name>title</name> +</attribute> +<attribute> +<name>binding</name> +</attribute> +</tag> +</taglib> +]]></programlisting> +<para>Add the code marked with bold to the faces-config.xml file:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE faces-config +PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" +"http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> +<faces-config> +<component> +<component-type>ticker</component-type> +<component-class>ticker.UITicker</component-class> +</component> +<managed-bean> +<managed-bean-name>BannerPageBean</managed-bean-name> +<managed-bean-class>demo.BannerPageBean</managed-bean-class> +<managed-bean-scope>request</managed-bean-scope> +<managed-property> +<property-name>rendered</property-name> +<property-class>java.lang.Boolean</property-class> +<value>true</value> +</managed-property> +</managed-bean> +<lifecycle/> +<application> +<locale-config/> +</application> +<factory/> +</faces-config> +]]></programlisting> +<para>We have added the managed bean with name BannerPageBean that will play the role on +backing bean for our form. We also have defined the &quot;rendered&quot; property that is set to true by +default.</para> +<para>Create new file with the name BannerPageBean.java inside the &quot;demo&quot; package. Here is the +content of this file:</para> +<programlisting role="XML"><![CDATA[package demo; +import ticker.UITicker; +public class BannerPageBean { +Boolean rendered; +UITicker ticker; +public Boolean getRendered() { +return rendered; +} +public void setRendered(Boolean rendered) { +this.rendered = rendered; +} +public UITicker getTicker() { +return ticker; +} +public void setTicker(UITicker ticker) { +this.ticker = ticker; +} +public UITicker getTiker() { +return ticker; +} +public void setTiker(UITicker tiker) { +this.ticker = tiker; +} +public String TurnOn() { +ticker.setRendered(true); +return null; +} +public String TurnOff() { +ticker.setRendered(false); +return null; +} +} +]]></programlisting> +<para>The bean has two properties: rendered that has a Boolean type and ticker that has a type of +our UITicker class. The two last methods will be called when you click the buttons on the page. +Those methods call the setter of the &quot;rendered&quot; property of the ticker. Actually, you have full +control over the ticker component here and can change any attribute you need.</para> +<para>The bannerpage.jsp file should contain the following:</para> +<programlisting role="JSP"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<f:loadBundle basename="demo.resources" var="bundle" /> +<html> +<head> +<title>Show Custom Component</title> +<style> +.banner { +border: 1px solid darkblue; +padding: 5px 5px 5px 5px; +} +</style> +</head> +<body> +<f:view> +<h:form> +<h:commandButton value="Turn Off" action="#{BannerPageBean.TurnOff}"/> +<h:commandButton value="Turn On" action="#{BannerPageBean.TurnOn}"/> +<d:ticker id="banner" +styleClass="banner" +style="width:100px" +title="#{bundle.banner_title}" +binding="#{BannerPageBean.ticker}"> +<f:verbatim>Hello JSF Component</f:verbatim> +</d:ticker> +</h:form> +</f:view> +</body> +</html> +]]></programlisting> +<para>The <emphasis role="italic"><property>&quot;binding&quot;</property></emphasis> attribute of our component refers to the “ticker” property of the backing bean. +The buttons <emphasis role="italic"><property>&quot;action&quot;</property></emphasis> attribute calls the corresponding method.</para> +<para>We are done with step 5. When you launch your application you can see our fancy box and +two buttons above them. Click the &quot;Turn Off&quot; button and the box disappears, click the &quot;Turn +On&quot; button and the box appears again.</para> +</section> +<section id="Step6FinalVersion"> +<?dbhtml filename="Step6FinalVersion.html"?> +<title>Step 6: Final Version</title> +<para>In this step, we set up our component with the look and feel we mentioned in the first step. +Additionally, we assign a couple new attributes: <emphasis role="italic"><property>&quot;width&quot;</property></emphasis> and <emphasis role="italic"><property>&quot;height&quot;</property></emphasis>. It will be more convenient to +define the value directly rather then use the style attribute. If you define width and height in the +style and add width and height attributes for the custom tag at the same time, the attributes will +overwrite the values defined with the style.</para> +<para>Add <emphasis role="italic"><property>&quot;width&quot;</property></emphasis> and <emphasis role="italic"><property>&quot;heght&quot;</property></emphasis> attribute to the ticker.tld file. Here is the final version of it:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" +"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> +<taglib> +<tlib-version>1.0</tlib-version> +<jsp-version>1.2</jsp-version> +<short-name>d</short-name> +<uri>http://jsftutorials.com/</uri> +<tag> +<name>ticker</name> +<tag-class>ticker.TickerTag</tag-class> +<body-content>JSP</body-content> +<attribute> +<name>style</name> +</attribute> +<attribute> +<name>styleClass</name> +</attribute> +<attribute> +<name>id</name> +</attribute> +<attribute> +<name>rendered</name> +</attribute> +<attribute> +<name>title</name> +</attribute> +<attribute> +<name>binding</name> +</attribute> +<attribute> +<name>width</name> +</attribute> +<attribute> +<name>height</name> +</attribute> +</tag> +</taglib> +]]></programlisting> +<para>Add the code marked with bold to the TickerTag.java file:</para> +<programlisting role="JAVA"><![CDATA[package ticker; +import javax.faces.component.UIComponent; +import javax.faces.el.ValueBinding; +import javax.faces.webapp.UIComponentTag; +public class TickerTag extends UIComponentTag{ +String style; +String styleClass; +String title; +String width; +String height; +public String getHeight() { +return height; +} +public void setHeight(String height) { +this.height = height; +} +public String getWidth() { +return width; +} +public void setWidth(String width) { +this.width = width; +} +public String getStyle() { +return style; +} +public void setStyle(String style) { +this.style = style; +} +public String getStyleClass() { +return styleClass; +} +public void setStyleClass(String styleClass) { +this.styleClass = styleClass; +} +public String getTitle() { +return title; +} +public void setTitle(String title) { +this.title = title; +} +public void release() { +// the super class method should be called +super.release(); +style = null ; +styleClass = null ; +title = null; +height = null; +width = null; +} +protected void setProperties(UIComponent component) { +// the super class method should be called +super.setProperties(component); +if(style != null) +component.getAttributes().put("style", style); +if(styleClass != null) +component.getAttributes().put("styleClass", styleClass); +if(width != null) +component.getAttributes().put("width", width); +if(height != null) +component.getAttributes().put("height", height); +if (title != null) { +if (isValueReference(title)) { +ValueBinding vb =getFacesContext().getApplication(). +createValueBinding(title); +component.setValueBinding("title", vb); +} else { +component.getAttributes().put("title", title); +} +} +} +public String getComponentType() { +return "ticker"; +} +public String getRendererType() { +// null means the component renders itself +return null; +} +} +]]></programlisting> +<para>This is a final version of the UITicker.java file:</para> +<programlisting role="JAVA"><![CDATA[package ticker; +import java.io.IOException; +import javax.faces.component.UIOutput; +import javax.faces.context.FacesContext; +import javax.faces.context.ResponseWriter; +public class UITicker extends UIOutput { +public void encodeBegin(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.startElement("div", this); +writer.writeAttribute("id", getClientId(context), null); +String width = (String)getAttributes().get("width"); +String height = (String)getAttributes().get("height"); +String style = (String)getAttributes().get("style"); +style= (style!=null) ? style + ";" : ""; +if (width != null) style += "width:" + width + ";"; +if (height != null) style += "height:" + height+ ";"; +writer.writeAttribute("style", style, null); +String styleClass = (String)getAttributes().get("styleClass"); +if (styleClass!=null) +writer.writeAttribute("class", styleClass, null); +String title = (String)getAttributes().get("title"); +if (title!=null) +writer.writeAttribute("title", title, null); +} +public void encodeEnd(FacesContext context) throws IOException { +ResponseWriter writer = context.getResponseWriter(); +writer.endElement("div"); +}} +]]></programlisting> +<para>The HTML <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tag itself does not have the <emphasis role="italic"><property>&quot;width&quot;</property></emphasis> and <emphasis role="italic"><property>&quot;height&quot;</property></emphasis> attributes. So, we use a +little trick here. We add the width and height to the tail of the <emphasis role="italic"><property>&quot;style&quot;</property></emphasis> attribute. If <emphasis role="italic"><property>&quot;style&quot;</property></emphasis> attribute +does not exist we create it.</para> +<para>This is a final version of the bannerpage.jsp file:</para> +<programlisting role="JSP"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +<f:loadBundle basename="demo.resources" var="bundle" /> +<html> +<head> +<title>Show Custom Component</title> +<style> +.banner { +border: 1px solid darkblue; +padding: 5px 5px 5px 5px; +overflow: auto; +} +</style> +</head> +<body> +<f:view> +<h:form> +<h:commandButton value="Turn Off" action="#{BannerPageBean.TurnOff}"/> +<h:commandButton value="Turn On" action="#{BannerPageBean.TurnOn}"/> +<d:ticker id="banner" +width="300px" +height="200px" +styleClass="banner" +title="#{bundle.banner_title}" +binding="#{BannerPageBean.ticker}"> +<h:panelGrid columns="1"> +<h:outputText value="Introduction"/> +<h:outputText value="Building Instructions for This Tutorial"/> +<h:outputText value="General Tips for Building Components"/> +<h:outputText value="Step 1: Components Skeleton"/> +<h:outputText value="Step 2: Adding Simple Attributes"/> +<h:outputText value="Step 3: Adding JSF Support Attributes"/> +<h:outputText value="Step 4: Attribute Binding"/> +<h:outputText value="Step 5: Component Binding"/> +<h:outputText value="Step 6: Final Version"/> +<h:outputText value="Step 7: Creating a Deployable Jar File"/> +<h:outputText value="What Next?"/> +</h:panelGrid> +</d:ticker> +</h:form> +</f:view> +</body> +</html> +]]></programlisting> +<para>We have added the &quot;overflow: auto&quot; to the style class to make our text area scrollable, +replaced a style attribute with the two size attributes and, finally, replaced the text greeting +message with something new one. You can put any other code here if you want.</para> +<para>Run and test the application. It should show the scrollable text area with the dark blue border +around it. If you see this, you have successfully passed the tutorial. We have only one more question to answer: How to distribute what we have done? We will dedicate the last step to this +question.</para> +</section> +<section id="Step7CreatingADeployableJarFile"> +<?dbhtml filename="Step7CreatingADeployableJarFile.html"?> +<title>Step 7: Creating a Deployable Jar File</title> +<para>OK. We have created our own JSF component or, even have written a whole custom tag +library. How do we make it reusable? How do we distribute it?</para> +<para>Of course, you can copy your classes and TLD file to the new project and add records to the +faces-config.xml file. It will work. However, this would be inconvenient to do each time, +especially if your library contains several dozen tags with double that number of class files all +requiring filling in the faces-config.xml file with references to those classes. No, this is definitely +not a good way. We will choice another one.</para> +<para>We will gather all of the information inside just one jar file and this will be the only one file +we have to distribute.</para> +<para>To make a long story short, this is the structure of our taglib jar file:</para> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<para>The package &quot;ticker&quot; contains compiled classes for our ticker component. The top level +META-INF folder contains the TLD file. It also contains the faces-config.xml file where the +components, but nothing else are defined.</para> +<para>To separate the components configuration from other stuff in the configuration file, let&apos;s +split faces-config.xml into two files.</para> +<para>Create the WEB-INF/faces-config-demo.xml file with the following content:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" +"http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> +<faces-config> +<managed-bean> +<managed-bean-name>BannerPageBean</managed-bean-name> +<managed-bean-class>demo.BannerPageBean</managed-bean-class> +<managed-bean-scope>request</managed-bean-scope> +<managed-property> +<property-name>rendered</property-name> +<property-class>java.lang.Boolean</property-class> +<value/> +</managed-property> +</managed-bean> +<application> +<locale-config/> +</application> +<factory/> +<lifecycle/> +</faces-config> +]]></programlisting> +<para>Remove the information about the managed bean from the faces-config.xml file. The +resulting content of this file will then be the following:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" +"http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> +<faces-config> +<component> +<component-type>ticker</component-type> +<component-class>ticker.UITicker</component-class> +</component> +<application> +<locale-config/> +</application> +<factory/> +<lifecycle/> +</faces-config> +]]></programlisting> +<para>To have our demo application working, we have to add the information about the new +configuration file into the web.xml. This will be the content of this file:</para> +<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<web-app xmlns="http://java.sun.com/xml/ns/j2ee" +xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee web-app_2_4.xsd" version="2.4"> +<context-param> +<param-name>javax.faces.STATE_SAVING_METHOD</param-name> +<param-value>server</param-value> +</context-param> +<context-param> +<param-name>javax.faces.CONFIG_FILES</param-name> +<param-value>/WEB-INF/faces-config.xml,/WEB-INF/faces-config-demo.xml</param-value> +</context-param> +<listener> +<listener-class>com.sun.faces.config.ConfigureListener</listener-class> +</listener> +<servlet> +<servlet-name>Faces Servlet</servlet-name> +<servlet-class>javax.faces.webapp.FacesServlet</servlet-class> +<load-on-startup>1</load-on-startup> +</servlet> +<servlet-mapping> +<servlet-name>Faces Servlet</servlet-name> +<url-pattern>*.jsf</url-pattern> +</servlet-mapping> +</web-app> +]]></programlisting> +<para>To make assembling the resulting jar file archive easier, we need to add the following code +into the build.xml file:</para> +<programlisting role="XML"><![CDATA[<property name="taglib.distname" value="mylib.jar"/> +<property name="taglibdeploy.dir" value="deploy"/> +<target name="createtaglib" depends="compile" +description="Create deployable tag libraries file"> +<delete dir="${build.dir}"/> +<mkdir dir="${build.dir}"/> +<mkdir dir="${build.dir}/META-INF"/> +<copy todir="${build.dir}/ticker"> +<fileset dir="${webinf.dir}/classes/ticker"/> +</copy> +<copy file="${webinf.dir}/faces-config.xml" todir="${build.dir}/META-INF"/> +<copy file="${webinf.dir}/ticker.tld" todir="${build.dir}/META-INF"/> +<mkdir dir="${taglibdeploy.dir}"/> +<jar basedir="${build.dir}" jarfile="${taglibdeploy.dir}/${taglib.distname}"/> +</target> +]]></programlisting> +<para>In this file, the first property defines the name of the result archive. The second one defines +the folder where the archive will be placed. To use the new Ant target coding we added, go to the +Ant folder and run the script by typing from the command line:</para> +<programlisting role="XML"><![CDATA[ant createtaglib +]]></programlisting> +<para>To see how this works now, copy the mylib.jar file to the WEB-INF/lib folder of any JSF +project. Then insert your new custom tag on one of the JSP pages. Don&apos;t forget to insert at the +top of the page the definition:</para> +<programlisting role="XML"><![CDATA[<%@ taglib uri="http://jsftutorials.com/" prefix="d" %> +]]></programlisting> +<para>If you do everything right, the custom tag should work properly.</para> +</section> +<section id="WhatNext?"> +<?dbhtml filename="WhaNext.html"?> +<title>What Next?</title> +<para>In this tutorial we have created new JSF components all the way from scratch to a +deployable package. In this example, we have covered the major points you will need in order to +create any JSF component. However, our example does not show all of the aspects of JSF +component building. You now have just the basic knowledge. If writing JSF components is +going to be your job, you will need to learn more before you will become an expert in this area.</para> +<section id="AdditionalTopics"> +<?dbhtml filename="AdditionalTopics.html"?> +<title>Addititional Topics</title> +<para>Some of the aspects you will need to learn that were not covered in this tutorial are +mentioned below.</para> +<para>Processing user input. If your component accepts data entered or selected by the user, you +need to take care of encoding or decoding the date. Such a component might need to support +validators, value changed listener, data converters.</para> +<para>Working with Facets. Facets are similar to children, but they have names. It is up to the +component how to process them. For example, the gridPanel from the standard JSF library has +two facet elements for header and footer. It does not matter where the facet is located in the JSP +code, the renderer always puts the header at the top and footer at the bottom.</para> +<para>Custom rendering of the existing components. In our example, the getRendererType +method of the TickerTag returns null. This means that the component renders itself. If this +method returns any value, it makes it possible to overwrite the default rendering provided by the +UITicker class. For this purpose, you or anybody else can add a new renderer with the defined +name to the render-kit section of the faces configuration file. In the same way, you can +implement rendered for any standard JSF components. All of the render type names can be found +in the JSF specification.</para> +<para>Action components. You can extend your component from the UICommand class. This +allows you to write components similar to a command button or a link, but with advanced +behavior. For example, you can implement tabbed panels or drop-down menus.</para> +</section> +<section id="JSFResources"> +<?dbhtml filename="JSFResources.html"?> +<title>JSF Resources</title> +<para>Beyond this tutorial, there are many resources that will help you go further with JSF. There +are already a number of published books dedicated to JavaServer Faces. We recommend reading +chapter 9 of the Core JavaServer Faces book by David Geary and Cay Horstmann. It contains +very useful information regarding JSF component development.</para> +<para>There are also several other types of resources available. We support the jsftutorials.net Web +site where you can read other JSF tutorials. Also, if you or your company are interesting in +learning JSF technology, Red Hat, Inc. has introduced a new JSF Course. You can read +information about it on this CD. We are going to prepare several more courses that cover all +levels from beginner to expert. The first course for beginners will be completed in the near +future. For more information visit our corporate Web site at www.jboss.org</para> +</section> +</section> + +</chapter> \ No newline at end of file Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedStrutsValidationExamples.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedStrutsValidationExamples.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedStrutsValidationExamples.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,240 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter id="GettingStartedStrutsValidationExamples" xreflabel="GettingStartedStrutsValidationExamples"> + <?dbhtml filename="GettingStartedStrutsValidationExamples.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Struts</keyword> + <keyword>Struts Validation</keyword> + </keywordset> + </chapterinfo> +<title>Getting Started Struts Validation Examples</title> + +<para>Validation of input is an important part of any Web application. All Apache Jakarta frameworks, +including Struts, can use a common Jakarta Validation Framework for streamlining this aspect of Web +application development. The Validation Framework allows the developer to define validation rules and then + apply these rules on the client-side or the server-side.</para> + +<para>Red Hat Developer Studio makes using the Validation Framework in Struts even easier through a specialized editor + for the XML files that control validation in a project. In this document, we&apos;ll show you how this all + works by creating some simple client-side validation and server-side validation examples.</para> + +<section id="StartingPoint"> +<?dbhtml filename="StartingPoint.html"?> +<title>Starting Point</title> +<para>The example assumes that you have already created our sample StrutsHello application from the +Getting Started Guide for Creating a Struts Application. You should have the Red Hat Developer Studio perspective + open on this StrutsHello project.</para> +</section> + +<section id="DefiningTheValidationRule"> +<?dbhtml filename="DefiningTheValidationRule.html"?> +<title>Defining the Validation Rule</title> +<para>In these steps you will set up the validation that can be used for either client-side or +serverside validation. You need to enable validation as part of the project, define an error message, +and tie it into the appropriate part of the application.</para> + +<orderedlist> +<listitem><para>Right-click the plug-ins node under the StrutsHello/Configuration/default/ +struts-config.xml node in the Web Projects view and select Create Special Plugin/Validators from the context + menu.</para></listitem> +<listitem><para>Further down in the Web Projects view, right-click on the +StrutsHello/ResourceBundles node and select New/Properties File... from the context menu.</para></listitem> +<listitem><para>In the dialog box, click on the Browse... button next to the Folder field, expand the +JavaSource folder in this next dialog box, select the sample subfolder, and click on the OK button.</para></listitem> +<listitem><para>Back in the first dialog box, type in applResources for the Name field and +click on the Finish button.</para></listitem> +<listitem><para>Right-click the newly created file and select Add/Default Error Messages + from the context menu.</para></listitem> + +<listitem><para>Drag up the sample.applResources icon until you can drop it on the resources folder under struts-config.xml.</para></listitem> +<listitem><para>Select File/Save All from the menu bar.</para></listitem> +<listitem><para>Select validation.xml under the StrutsHello/Validation node and double-click it to open it with the Exadel Studio Validation Editor.</para></listitem> +<listitem><para>Expand the form-beans node under the StrutsHello/Configuration/default/ struts-config.xml node. Then, drag the form bean GetNameForm and drop it onto formset (default) in the Validation Editor.</para></listitem> +<listitem><para>In the Validation Editor, expand the formset node, right-click GetNameForm, and select Add Field... from the context menu.</para></listitem> +<listitem><para>Enter name for Property in the dialog box.</para></listitem> +<listitem><para>In the properties for the name field to the right of the &quot;tree&quot; for the validation.xml file, click on the Change... button next to the Depends entry field.</para></listitem> +<listitem><para>In the displayed double list, select required from the left list and then click Add->.</para></listitem> +<listitem><para>Click Ok.</para></listitem> +<listitem><para>Right-click name and select Add Arg... from the context menu.</para></listitem> +<listitem><para>In the Add Arg dialog box, click on the Change... button next to the Key field.</para></listitem> +<listitem><para>In the Key dialog box that appears now, click on the Add button.</para></listitem> +<listitem><para>Enter name.required in the Name field, and enter A person&apos;s name in the Value field.</para></listitem> +<listitem><para>Click Finish, then Ok, and then Ok again.</para></listitem> +<listitem><para>Select File/Save All from the menu bar.</para></listitem> +</orderedlist> +</section> + +<section id="Client-SideValidation"> +<?dbhtml filename="Client-SideValidation.html"?> +<title>Client-Side Validation</title> +<para>Client-side validation uses a scripting language (like JavaScript) running in the client browser</para> +<para>to actually do the validation. In a Struts application using the Validation Framework, however,</para> +<para>you don&apos;t actually have to do any of the script coding. The Validation Framework handles this.</para> +<para>To see how this works in our application, you&apos;ll just need to make a couple of modifications to one of the JSP files.</para> +<orderedlist continuation="continues"> +<listitem><para>Double-click inputname.jsp under StrutsHello/WEB-ROOT (WebContent)/ pages to open it for editing.</para></listitem> +<listitem><para>Find the tag near the top and hit Return to make a new line under it.</para></listitem> +<listitem><para>In the Red Hat Palette view to the right, open the HTML folder and click on the javascript tag.</para></listitem> + +<listitem><para>Back in the editor, just in front of the closing slash for this inserted tag, hit Ctrlspace and select formName from the prompting menu.</para></listitem> +<listitem><para>Over in the Web Projects view, select GetNameForm under the StrutsHello/Configuration/ default/struts-config.xml/form-beans node, drag it, and drop it between the quotes in the editor.</para></listitem> +<listitem><para>Modify the &gt;html:form&lt; tag by inserting this attribute:</para></listitem> +</orderedlist> +<para>onsubmit=&quot;return validateGetNameForm(this)&quot;</para> +<para>The file should now look like this:</para> +<programlisting role="HTML"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %> +<html:html> +<head> +<title>Input name</title> +<html:javascript formName="GetNameForm"/> +</head> +<body> +<html:form action="/greeting.do" onsubmit="return +<para>validateGetNameForm(this)"></para> +<table border="0" cellspacing="0" cellpadding="0"> +<tr> +<td><b>Input name:</b></td> +</tr> +<tr> +<td> +<html:text property="name" /> +<html:submit value=" Say Hello! " /> +</td> +</tr> +</table> +</html:form> +</body> +</html:html> +]]></programlisting> +<orderedlist continuation="continues"> +<listitem><para>Select File/Save from the menu bar.</para></listitem> +<listitem><para>28. Start Tomcat by clicking on its icon (a right-pointing arrow) in the toolbar.</para></listitem> +<listitem><para>29. Click on the Run icon in the toolbar.</para></listitem> +</orderedlist> +<figure> +<title></title> +<mediaobject> + <imageobject> + <imagedata fileref="img/"/> + </imageobject> +</mediaobject> +</figure> +<itemizedlist><listitem><para>30. In the browser window, click on the Say Hello! button without having entered any name in the form.</para></listitem></itemizedlist> +<para>A JavaScript error message should be displayed in an alert box.</para> +</section> +<section id="Server-SideValidation"> +<?dbhtml filename="Server-SideValidation.html"?> +<title>Server-Side Validation</title> +<para>Server-side validation does the validation inside the application on the server. In a Struts +application using the Validation Framework, you still don&apos;t have to do any of the actual validation +coding. The Validation Framework handles this. You will, though, have to make a few changes to the JSP +file you modified for client-side validation along with a change to an action and a few changes to the + form bean class.</para> +</section> + +<section id="EditingTheJSPFile"> +<?dbhtml filename="EditingTheJSPFile.html"?> +<title>Editing the JSP File</title> +<orderedlist continuation="continues"> +<listitem><para>Reopen inputname.jsp for editing.</para></listitem> +<listitem><para>Delete the onsubmit attribute in the &gt;html:form&lt; element that you put in for client-side validation.</para></listitem> + +<listitem><para>Add an &gt;html:errors/&gt; tag after the &gt;/html:form&gt; tag.</para></listitem> +</orderedlist> +<para>The JSP file should now look like this:</para> + +<programlisting role="HTML"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %> +<html:html> +<head> +<title>Input name</title> +<html:javascript formName="GetNameForm"/> +</head> +<body> +<html:form action="/greeting.do"> +<table border="0" cellspacing="0" cellpadding="0"> +<tr> +<td><b>Input name:</b></td> +</tr> +<tr> +<td> +<html:text property="name" /> +<html:submit value=" Say Hello! " /> +</td> +</tr> +</table> +</html:form> +<html:errors /> +</body> +</html:html> +]]></programlisting> + +</section> + +<section id="EditingTheAction"> +<?dbhtml filename="EditingTheAction.html"?> +<title>Editing the Action</title> +<orderedlist continuation="continues"> +<listitem><para>In the Web Projects view, expand the node under the StrutsHello/Configuration/ default/struts-config.xml/action-mappings node, right-click the /greeting action, and then select Properties... from the context menu.</para></listitem> + +<listitem><para>In the Edit Properties window, insert the cursor into the value column for the input property and click on the ... button.</para></listitem> + +<listitem><para>In the dialog box, make sure the Pages tab is selected, select StrutsHello/WEBROOT( WebContent)/pages/ inputname.jsp, click the Ok button, and then click on the Close button.</para></listitem> +</orderedlist> +</section> +<section id="EditingTheFormBean"> +<?dbhtml filename="EditingTheFormBean.html"?> + +<title>Editing the Form Bean</title> +<orderedlist continuation="continues"> +<listitem><para>Right-click the /greeting action again and select Open Form-bean Source to open the GetNameForm.java file for editing.</para></listitem> +<listitem><para>Change the class that it extends to from: org.apache.struts.action.ActionForm to: org.apache.struts.validator.ValidatorForm</para></listitem> +<listitem><para>Comment out out the validate method.</para></listitem> +</orderedlist> +<para>The file should now look like this:</para> +<programlisting role="JAVA"><![CDATA[ +package sample; +import javax.servlet.http.HttpServletRequest; +import org.apache.struts.action.ActionErrors; +import org.apache.struts.action.ActionMapping; +public class GetNameForm extends +org.apache.struts.validator.ValidatorForm { +private String name = ""; +/** +* @return Returns the name. +*/ +public String getName() { +return name; +} +/** +* @param name The name to set. +*/ +public void setName(String name) { +this.name = name; +} +public GetNameForm () { +} +public void reset(ActionMapping actionMapping, HttpServletRequest +request) { +this.name = ""; +} +// public ActionErrors validate(ActionMapping actionMapping, +HttpServletRequest request) { +// ActionErrors errors = new ActionErrors(); +// return errors; +// } +} +]]></programlisting> + + +<para>Select File/Save All from the menu bar.</para> +<orderedlist continuation="continues"> +<listitem><para>Reload the application into Tomcat by clicking on the Change Time Stamp icon (a finger pointing with a little star) in the toolbar.</para></listitem> +<listitem><para>Run the application.</para></listitem> +<listitem><para>In the browser window, click on the Say Hello! button without having entered any name in the form.</para></listitem> +</orderedlist> +<para>The error message should appear in a refreshed version of the form.</para> +</section> +</chapter> \ No newline at end of file Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="GettingStartedWithRHDS" xreflabel="GettingStartedWithRHDS"> + <?dbhtml filename="GettingStartedWithRHDS.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>Tomcat</keyword> + </keywordset> + </chapterinfo> + <title>Getting Started with Red Hat Developer Studio</title> + <section id="TechnicalRequirements"> + <?dbhtml filename="TechnicalRequirements.html"?> +<title>Technical Requirements</title> + <section id="Java"> + <title>Java</title> + <para>Before installing Red Hat Developer Studio, make sure you have one of the following versions of Java + installed:</para> + <itemizedlist> + <listitem><para>JDK 1.4.2 or higher</para></listitem> + </itemizedlist> + <para>It must be the full JDK, not just the JRE (Java Runtime Environment). For more information about + target operating environments and compatible Java versions, refer to the JBoss web site. Please note + that the Eclipse documentation states that you only need a Java Runtime Environment for Eclipse, but usage of Red Hat Developer Studio requires a full JDK in order to compile Java classes and JSP pages.</para> + </section> + <section id="OperatingSystems"> + <?dbhtml filename="OperatingSystems.html"?> + <title>Operating Systems</title> + <itemizedlist> + <listitem><para>Windows</para></listitem> + <listitem><para>Linux</para></listitem> + </itemizedlist> + </section> + </section> + <section id="Installing"> + <?dbhtml filename="Installing.html"?> +<title>Installing</title> + <section id="Inst from down ver"> + <title>Installing from the downloaded version</title> + <itemizedlist> + <listitem> + <para>Download the appropriate installation file for your platform from www.exadel.com/web/portal/download.</para> + </listitem> + <listitem> + <para>Run install.jar and follow the instructions presented by the installation wizard.</para> + </listitem> + </itemizedlist> + + <figure> + <title>Red Hat Developer Studio Installation Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/install.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>After installation process you will have all required platforms to run Red Hat Developer Studio:</para> + <itemizedlist> + <listitem> + <para>Eclipse 3.2.2</para> + </listitem> + <listitem> + <para>JBoss Application Server</para> + </listitem> + </itemizedlist> + + <para>Red Hat Developer Studio comes with the following plug-ins:</para> + <itemizedlist> + <listitem><para>WTP runtime 1.5</para></listitem> + <listitem><para>GEF runtime 3.2</para></listitem> + <listitem><para>JEM runtime 1.2</para></listitem> + <listitem><para>EMF and SDO runtime 2.2</para></listitem> + <listitem><para>XSD runtime 2.2</para></listitem> + <listitem>Hibernate-tools-3.1.0 beta5 (without WTP, EMF, GEF, and other non-Hibernate plug-ins from + Hibernate-tools-3.1.0 beta5)</listitem> + <listitem><para>QuickImage 0.2.0</para></listitem> + <listitem><para>Spring IDE 1.3.2</para></listitem> + <listitem><para>Sun Glassfish 0.3</para></listitem> + </itemizedlist> + + </section> + <section id="InstallingthroughTheUpdateSite"> + <?dbhtml filename="InstallingthroughTheUpdateSite.html"?> + <title>Installing through the update Site</title> + TBD + </section> + + + </section> + <section id="RunningForTheFirstTime"> + <?dbhtml filename="RunningForTheFirstTime.html"?> + <title>Running for the First Time</title> + <itemizedlist> + <listitem><para> Launch Eclipse</para></listitem> + <listitem><para> Select Window/Open Perspective.../Other...</para></listitem> + <listitem><para> Select Red Hat Developer Studio from the perspective list</para></listitem> + </itemizedlist> + <para>We recommend starting Eclipse with VM arguments to make more memory (heap) available for large-scale projects. Open the file &lt;eclipse&gt;\eclipse.ini and set the following:</para> + <para>eclipse -clean -vmargs -Xms512m -Xmx512m -XX:MaxPermSize=128m</para> + <para>This setting will allow the Java heap to grow to 512MB.</para> + </section> + <section id="Upgrading"> + <?dbhtml filename="Upgrading.html"?> + <title>Upgrading</title> + <para>To upgrade, just uninstall your current version and install the new version.</para> + + <itemizedlist> + <listitem><para> Make sure Eclipse is not running.</para> +<para>Uninstall your current version of Exadel Studio. You can do one of the following:</para> +</listitem> +<listitem><para>Run the Red Hat Developer Studio uninstaller</para></listitem> + <listitem><para>Delete the file {EclipseHome}/links/com.exadel.studio.link</para> +<para>Either method will uninstall Exadel Studio.</para> +</listitem> +<listitem>Start Eclipse: + <para>eclipse -clean</para></listitem> + </itemizedlist> + + <itemizedlist> + <listitem><para>Close Eclipse</para></listitem> + <listitem><para>Install the new version of Red Hat Developer Studio.</para></listitem> + <listitem>After installation, start Eclipse with the -clean option: + <para>eclipse -clean</para></listitem> + </itemizedlist> + + <para>This step is very important as it will clear the Eclipse cache of the old uninstalled plug-in.</para> + <note> + <title>Note:</title> + <para>It is recommended to uninstall Red Hat Developer along with Eclipse and install Red Hat Developer + Studio into a new clean Eclipse</para> + </note> + </section> + <section id="Uninstalling"> + <?dbhtml filename="Uninstalling.html"?> + <title>Uninstalling</title> + + <para> Make sure Eclipse is not running.</para> + <para> Uninstall your current version of Red Hat Developer Studio. You can do one of the following:</para> + <itemizedlist> + <listitem><para>Run the Red Hat Developer Studio uninstaller</para></listitem> + <listitem><para>Delete the file {EclipseHome}/links/com.exadel.studio.link</para> +<para>Either method will uninstall Red Hat Developer Studio.</para> +</listitem> +</itemizedlist> + <itemizedlist> + <listitem><para>Start Eclipse with the -clean option:</para> +<para>eclipse -clean</para> +</listitem> +</itemizedlist> + <para>This step is very important as it will clear the Eclipse cache of the uninstalled plug-in.</para> + </section> + <section id="Subscription"> + <?dbhtml filename="Subscription.html"?> + <title>Subscription</title> + TBD + </section> + <section id="Support"> + <?dbhtml filename="Support.html"?> + <title>Support</title> + <para>If you have comments or questions, you can send them to + <ulink url="mailto:support@exadel.com">support@exadel.com</ulink> or + <ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... Hat Developer Studio Forum</ulink>.</para> + <para>When writing to support, please include the following information:</para> + <itemizedlist> + <listitem><para>Eclipse version</para></listitem> + <listitem><para> Red Hat Developer Studio version</para></listitem> + <listitem><para>Exact error message</para></listitem> + <listitem><para>Exact steps you took to get the error</para></listitem> + </itemizedlist> + </section> + +</chapter> + Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml.bak =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml.bak (rev 0) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GettingStartedWithRHDS.xml.bak 2007-05-03 11:03:01 UTC (rev 1992) @@ -0,0 +1,176 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="GettingStartedWithRHDS" xreflabel="GettingStartedWithRHDS"> + <?dbhtml filename="GettingStartedWithRHDS.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>Tomcat</keyword> + </keywordset> + </chapterinfo> + <title>Getting Started with Red Hat Developer Studio</title> + <section id="TechnicalRequirements"> + <?dbhtml filename="TechnicalRequirements.html"?> +<title>Technical Requirements</title> + <section id="Java"> + <title>Java</title> + <para>Before installing Red Hat Developer Studio, make sure you have one of the following versions of Java + installed:</para> + <itemizedlist> + <listitem><para>JDK 1.4.2 or higher</para></listitem> + </itemizedlist> + <para>It must be the full JDK, not just the JRE (Java Runtime Environment). For more information about + target operating environments and compatible Java versions please refer to the JBoss web site. Please note + that the Eclipse documentation states that you only need a Java Runtime Environment for Eclipse, but to + use Red Hat Developer Studio requires a full JDK in order to compile Java classes and JSP pages.</para> + </section> + <section id="OperatingSystems"> + <?dbhtml filename="OperatingSystems.html"?> + <title>Operating Systems</title> + <itemizedlist> + <listitem><para>Windows</para></listitem> + <listitem><para>Linux</para></listitem> + </itemizedlist> + </section> + </section> + <section id="Installing"> + <?dbhtml filename="Installing.html"?> +<title>Installing</title> + <section id="Inst from down ver"> + <title>Installing from the downloaded version</title> + <itemizedlist> + <listitem> + <para>Download the appropriate installation file for your platform from www.exadel.com/web/portal/download.</para> + </listitem> + <listitem> + <para>Run install.jar and follow the instructions presented by the installation wizard.</para> + </listitem> + </itemizedlist> + + <figure> + <title>Red Hat Developer Studio Installation Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/install.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>After installation process you will have all required platforms to run Red Hat Developer Studio:</para> + <itemizedlist> + <listitem> + <para>Eclipse 3.2.2</para> + </listitem> + <listitem> + <para>JBoss Application Server</para> + </listitem> + </itemizedlist> + + <para>Red Hat Developer Studio comes with the following plug-ins:</para> + <itemizedlist> + <listitem><para>WTP runtime 1.5</para></listitem> + <listitem><para>GEF runtime 3.2</para></listitem> + <listitem><para>JEM runtime 1.2</para></listitem> + <listitem><para>EMF and SDO runtime 2.2</para></listitem> + <listitem><para>XSD runtime 2.2</para></listitem> + <listitem>Hibernate-tools-3.1.0 beta5 (without WTP, EMF, GEF, and other non-Hibernate plug-ins from + Hibernate-tools-3.1.0 beta5)</listitem> + <listitem><para>QuickImage 0.2.0</para></listitem> + <listitem><para>Spring IDE 1.3.2</para></listitem> + <listitem><para>Sun Glassfish 0.3</para></listitem> + </itemizedlist> + + </section> + <section id="InstallingthroughTheUpdateSite"> + <?dbhtml filename="InstallingthroughTheUpdateSite.html"?> + <title>Installing through the update Site</title> + TBD + </section> + + + </section> + <section id="RunningForTheFirstTime"> + <?dbhtml filename="RunningForTheFirstTime.html"?> + <title>Running for the First Time</title> + <itemizedlist> + <listitem><para> Launch Eclipse</para></listitem> + <listitem><para> Select Window/Open Perspective.../Other...</para></listitem> + <listitem><para> Select Red Hat Developer Studio from the perspective list</para></listitem> + </itemizedlist> + <para>We recommend starting Eclipse with VM arguments to make more memory (heap) available for large-scale projects. Open the file &lt;eclipse&gt;\eclipse.ini and set the following:</para> + <para>eclipse -clean -vmargs -Xms512m -Xmx512m -XX:MaxPermSize=128m</para> + <para>This setting will allow the Java heap to grow to 512MB.</para> + </section> + <section id="Upgrading"> + <?dbhtml filename="Upgrading.html"?> + <title>Upgrading</title> + <para>To upgrade, just uninstall your current version and install the new version.</para> + + <itemizedlist> + <listitem><para> Make sure Eclipse is not running.</para> +<para>Uninstall your current version of Exadel Studio. You can do one of the following:</para> +</listitem> +<listitem><para>Run the Red Hat Developer Studio uninstaller</para></listitem> + <listitem><para>Delete the file {EclipseHome}/links/com.exadel.studio.link</para> +<para>Either method will uninstall Exadel Studio.</para> +</listitem> +<listitem>Start Eclipse: + <para>eclipse -clean</para></listitem> + </itemizedlist> + + <itemizedlist> + <listitem><para>Close Eclipse</para></listitem> + <listitem><para>Install the new version of Red Hat Developer Studio.</para></listitem> + <listitem>After installation, start Eclipse with the -clean option: + <para>eclipse -clean</para></listitem> + </itemizedlist> + + <para>This step is very important as it will clear the Eclipse cache of the old uninstalled plug-in.</para> + <note> + <title>Note:</title> + <para>It is recommended to uninstall Red Hat Developer along with Eclipse and install Red Hat Developer + Studio into a new clean Eclipse</para> + </note> + </section> + <section id="Uninstalling"> + <?dbhtml filename="Uninstalling.html"?> + <title>Uninstalling</title> + + <para> Make sure Eclipse is not running.</para> + <para> Uninstall your current version of Red Hat Developer Studio. You can do one of the following:</para> + <itemizedlist> + <listitem><para>Run the Red Hat Developer Studio uninstaller</para></listitem> + <listitem><para>Delete the file {EclipseHome}/links/com.exadel.studio.link</para> +<para>Either method will uninstall Red Hat Developer Studio.</para> +</listitem> +</itemizedlist> + <itemizedlist> + <listitem><para>Start Eclipse with the -clean option:</para> +<para>eclipse -clean</para> +</listitem> +</itemizedlist> + <para>This step is very important as it will clear the Eclipse cache of the uninstalled plug-in.</para> + </section> + <section id="Subscription"> + <?dbhtml filename="Subscription.html"?> + <title>Subscription</title> + TBD + </section> + <section id="Support"> + <?dbhtml filename="Support.html"?> + <title>Support</title> + <para>If you have comments or questions, you can send them to + <ulink url="mailto:support@exadel.com">support@exadel.com</ulink> or + <ulink url="">Red Hat Developer Studio Forum</ulink>.</para> + <para>When writing to support, please include the following information:</para> + <itemizedlist> + <listitem><para>Eclipse version</para></listitem> + <listitem><para> Red Hat Developer Studio version</para></listitem> + <listitem><para>Exact error message</para></listitem> + <listitem><para>Exact steps you took to get the error</para></listitem> + </itemizedlist> + </section> + +</chapter> +