[jbosstools-commits] JBoss Tools SVN: r22411 - in trunk/documentation/guides/GettingStartedGuide/en-US: images/first_seam and 1 other directory.
jbosstools-commits at lists.jboss.org
jbosstools-commits at lists.jboss.org
Fri May 28 09:59:48 EDT 2010
Author: smukhina
Date: 2010-05-28 09:59:47 -0400 (Fri, 28 May 2010)
New Revision: 22411
Modified:
trunk/documentation/guides/GettingStartedGuide/en-US/first_seam.xml
trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam13.png
trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam3.png
trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam5.png
trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam8.png
Log:
nomsg
Modified: trunk/documentation/guides/GettingStartedGuide/en-US/first_seam.xml
===================================================================
--- trunk/documentation/guides/GettingStartedGuide/en-US/first_seam.xml 2010-05-28 13:11:43 UTC (rev 22410)
+++ trunk/documentation/guides/GettingStartedGuide/en-US/first_seam.xml 2010-05-28 13:59:47 UTC (rev 22411)
@@ -1,820 +1,828 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="first_seam" xreflabel="first_seam">
- <?dbhtml filename="first_seam.html"?>
- <chapterinfo>
- <keywordset>
- <keyword>JBoss Developer Studio</keyword>
- <keyword>Seam</keyword>
- <keyword>JBoss</keyword>
- </keywordset>
- </chapterinfo>
- <title>Write Your First Project with JBoss Developer Studio</title>
- <para>This chapter is a set of hands-on labs. You get step-by-step information about how the JBoss
- Developer Studio can be used during the development process.</para>
- <section id="create_seam_application">
- <title>Create a Seam Application</title>
- <para>In this section you get to know how to create a Seam project in JBDS, how to start the
- server and what a structure your project has after creating.</para>
- <section id="start_dev_db">
- <title>Start Development Database</title>
- <para>Before opening the JBoss Developer studio you need to download and start <ulink
- url="http://docs.jboss.org/tools/resources/GSG_database.zip">Workshop Database</ulink>
- .</para>
- <para>To start the database just run <property>./runDBServer.sh</property> or <property
- >runDBServer.bat</property> from the database directory.</para>
- <para>The end result should be a console window that looks like:</para>
- <figure>
- <title>Starting DataBase</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam1.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="create_deploy_seam">
- <title>Create and deploy Seam Web Project</title>
- <para>Minimize the terminal window and run the <property>JBoss Developer Studio</property>
- from Applications Menu or from the desktop icon.</para>
- <para>First of all you get the Workspace Launcher. Change the default workspace location if
- it's needed. Click on <property>Ok</property>. </para>
- <figure>
- <title>Workspace Launcher Dialog</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam2.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>After startup, you see the welcome page. You could read how to work with welcome pages
- in <link linkend="Welcome">previous</link> chapter. Now select <property>Create
- New...</property> icon and then press on <property>Create Seam Project</property>
- link.</para>
- <para>The <property>New Seam Project wizard</property> is started. You need to enter a name
- (e.g., "workshop") and a location directory for your new project. The wizard has
- an option for selecting the actual Server (and not just WTP runtime) that will be used for
- the project. This allows the wizard to correctly identify where the needed datasource and
- driver libraries need to go.</para>
- <figure>
- <title>New Seam Project Wizard</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam3.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>All settings are already specified here, you can just modify the Configuration. Click on
- the <emphasis>
- <property>Modify...</property>
- </emphasis> button to configure your custom facets pattern:</para>
- <figure id="ProjectFacetsSpecifyingScreen">
- <title>Project Facets Specifying</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam4.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>On the whole the dialog allows to select the "features" you want to use in your project.
- Doing this <property>JBoss Developer Studio</property> setups the appropriate tooling for
- your project. Since JBoss Seam integrates all popular Java EE frameworks, you can select any
- combination of technologies from the list. Here, for the default configuration, Dynamic Web
- Module, Java, JavaServer Faces (JSF), and Seam Facet are already selected for a typical
- database-driven web application. The default project facets should suffice.</para>
- <para>In the <property>Project Facets</property> form you can also bring up server runtimes
- panel by clicking <property> Runtimes</property> tab on the right corner. This panel shows
- available server runtimes.</para>
- <figure>
- <title>Runtimes Selecting</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam5.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Click on <emphasis>
- <property>Ok</property>
- </emphasis> and then <emphasis>
- <property>Next</property>
- </emphasis> to proceed further.</para>
- <para>A dynamic web application contains both web pages and <property>Java</property> code.
- The next wizard will ask you where you want to store Java files.</para>
- <figure>
- <title>Java Build Path</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam5a.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Following page provides you <property>Web Module Settings</property> .You can just leave
- the default values or choose another folder.</para>
- <figure>
- <title>Web Module Settings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam6.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>On the next form, you will be able to select where those library JARs come from. The
- easiest is just to select the JARs provided by the JBoss AS runtime associated with this
- project. That is why it is important to chose the right JBoss AS 4.2 runtime in the project
- setup window.</para>
- <itemizedlist>
- <listitem>
- <para>Select <emphasis>
- <property>Library Provided by Target Runtime</property>
- </emphasis> as <property>Type</property> of <property>JSF Implementation
- Library</property>. We will use the JSF implementation that comes with JBoss
- server.</para>
- </listitem>
- <listitem>
- <para>Click <emphasis>
- <property>Next</property>
- </emphasis></para>
- </listitem>
- </itemizedlist>
- <figure>
- <title>JSF Capabilities Adding</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam7.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Next wizard step needs more settings that previous. Let's start with <property
- >General</property> section.</para>
- <para>Leave the default Seam runtime and check a WAR deployment.</para>
- <figure>
- <title>Seam Facet Setting</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam8.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Next <property>Database</property> section is a little tricky. The <property>Connection
- Profile</property> needs to be edited so that the new project works properly with the
- external HSQLDB server. By default the project wizard tries to use the JBoss embedded
- HSQLDB, but the tutorial uses an external database to replicate a more real world
- development scenario. Click on <property>Edit</property> to modify the Connection
- Profile.</para>
- <figure>
- <title>DataBase Setting</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam8_1.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Select <property>HSQLDB Profile Properties</property>. Make sure the Database location
- is set to <emphasis>
- <property>hsql://localhost:1701</property>
- </emphasis></para>
- <figure>
- <title>JDBC Connection Properties</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam9.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Try click on <property>Test Connection</property> button. It probably won’t work. This
- happens if the hsql jdbc driver is not exactly the same. This can be worked around by
- modifying the HSQLDB database driver settings. To modify the settings, click the Edit Driver Definition Driver(
- <inlinemediaobject><imageobject>
- <imagedata fileref="images/first_seam/first_seam9_1.png"/>
- </imageobject>
- </inlinemediaobject>) .</para>
- <para>The proper Driver JAR File should be listed under <property>Jar List</property>. Select
- the hsqldb.jar file found in the jbdevstudio/jboss-eap/jboss-as/common/lib/ directory and
- click <property>Ok</property>.</para>
- <figure>
- <title>Driver Details</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam10.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Now, the <property>Test Connection</property> should succeed. After testing the
- connection, click <emphasis><property>Ok</property></emphasis>.</para>
- <figure>
- <title>Connection Testing</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam12.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>You can leave the <property>Code Generation</property> section as is. It refers to Java
- packages in which the generated code will be placed.</para>
- <figure>
- <title>Code Generation Setting</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam13.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Click on <property>Finish</property> button. Now, there should be a new Seam project
- called “workshop” listed in Package Explorer view.</para>
- <figure>
- <title>"worskhop" Project in the Package Explorer</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam14.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="start_JBossAS">
- <title>Start JBoss Application Server</title>
- <para>The complete information on how to manage JBoss AS from JBoss Developer Studio you can
- read in a <link linkend="manage">corresponding chapter</link>.</para>
- <para>Now you just need to start the server by clicking on the Start the server icon (
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam15.png"/>
- </imageobject>
- </inlinemediaobject> ) in the <property>Servers</property>.</para>
- <para>Then run the project by selecting the project and use <emphasis><property>Run As... >
- Run on Server</property>.</emphasis></para>
- <note>
- <title>Note:</title>
- <para>If the project does not show up, then you can use a normal browser and use <emphasis>
- <property>http://localhost:8080/workshop/home.seam</property>
- </emphasis> as the url.</para>
- </note>
- <para>Your project looks like this:</para>
- <figure>
- <title>"workshop" Project Started</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam16.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="workshop_code_overview">
- <title>Workshop Project Code Overview</title>
- <para>Now let's examine the project and its structure. Go back to the Package Explorer view in
- JBoss Developer Studio.</para>
- <para>It seems like it's not much for project but this shell application contains a login
- screen with default login logic, a menu template that can be further modified, and other
- layout templates.</para>
- <para>It's important to note that the business logic will reside in the <emphasis>
- <property>src/hot</property>
- </emphasis> folder, by default. And, the package naming conventions that were used in
- <property>New Seam project wizard</property> could have been changed to something
- different from <emphasis>
- <property>org.domain.workshop.session</property>. </emphasis> Also, notice that there is a
- default <property>Authenticator. java</property> file. This is where custom security logic
- can be added. Seam has a nice declarative security model that we will explore in a bit more
- detail later on. The <emphasis>
- <property>src/main</property>
- </emphasis> folder is a model directory. It stores the project's JPA entity
- beans.</para>
- <figure>
- <title>Project Structure</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam17.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The view tier of the application is also important. Seam uses facelets and there is a
- built-in facelets GUI editor that has some nice WYSIWYG and component drag/drop
- functionality. Try this out by opening <property>home.xhtml</property> from <property
- >WebContent</property> folder.</para>
- <figure>
- <title>Facelets GUI Editor</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam18.png" scale="85"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Notice that the templates reside in the <emphasis>
- <property>WebContent/layout</property>
- </emphasis> folder. There is a stylesheet in the <emphasis>
- <property>WebContent/stylesheet</property>
- </emphasis> folder. There is also a login and default error page. The Facelet editor will be
- explored in more detail later in the lab.</para>
- <para>The project already has a datasource that was created per the Seam project wizard
- database settings. And, obviously all of the Seam specific configuration files and JAR
- dependencies are included and placed in the proper locations. On last noteworthy line item
- is related to the build script. There isn’t a build script because the Eclipse WTP(Web Tools
- Project) plugin is used to publish web application changes. As you can see, JBoss Developer
- Studio is removing a great deal of complexity from the enterprise Java project
- setup/deployment process. The end result is a developer that is writing code, not spending
- days/weeks trying to figure out how to get a decent development environment and project
- build process.</para>
- </section>
- </section>
- <section id="seam_action_dev">
- <title>Seam Action Development</title>
- <para>Now, it’s time to write some code. The good news is that JBoss Developer Studio can also
- help out in this respect. In this section, we will create a new Seam Action POJO and facelet
- with some custom business logic and some GUI changes.</para>
- <section id="create_seam_action">
- <title>Create a New Seam Action</title>
- <para>Go to main menu bar and click on <emphasis>
- <property>File > New > New Seam Action</property>
- </emphasis> to start the New Seam Action wizard.</para>
- <para>Specify a <property>Seam component name</property> (e.g., "myAction"). The
- other properties will be auto-completed for you so there is no need to change them. Click on
- <property>Finish</property>.</para>
- <figure>
- <title>New Seam Action Wizard</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam19.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Now, open the <property>MyAction.java</property> file and replace the
- "myAction" method with this logic:</para>
- <programlisting><![CDATA[public void myAction() {
-Calendar cal = Calendar.getInstance();
-log.info("myAction.myAction() action called");
-facesMessages.add("MyAction Executed on:" + cal.getTime());
-}]]></programlisting>
- <para>You also need to import the <property>java.util.Calendar</property> class by clicking
- <emphasis><property>CTRL + Shift + O</property>.</emphasis></para>
- </section>
- <section id="test_seam_action">
- <title>Test Seam Action</title>
- <para>The new action can be tested by browsing the workshop-test project. JBoss Developer
- Studio has already created a TestNG test case for you.</para>
- <figure>
- <title>"workshop-test" Project</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam20.png" scale="85"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The test case simulates a Seam component/method execution for the <property
- >MyAction.myAction()</property> logic.</para>
- <para>To run the test case, right click on <property>MyActionTest.xml</property> and click
- <emphasis>
- <property>Run As > TestNG Suite</property>
- </emphasis> or use the <property>Run As...</property> toolbar shortcut as shown
- below.</para>
- <figure>
- <title>TestNG Running</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam21.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>With any luck, the test case will pass. Look at the TestNG view.</para>
- <figure>
- <title>TestNG Results</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam22.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Now, it’s safe to test the new Seam Action in a web browser. The fastest way to do that
- is to right click on <property>myAction.xhtml</property> and use <emphasis>
- <property>Run As... > Run On Server</property>
- </emphasis> which will show the appropriate url in the browser. Alternatively you can
- manually enter <emphasis>
- <property>http://localhost:8080/workshop/myAction.seam</property>
- </emphasis> into a browser.</para>
- <figure>
- <title>Seam Action in a Web Browser</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam23.png" scale="90"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="modify_seam_action">
- <title>Modify Seam Action User Interface</title>
- <para>Browse to <emphasis>
- <property>http://localhost:8080/workshop/myAction.seam</property>
- </emphasis> and click on <property>myAction</property>. This executes the “myAction” method.
- This looks pretty good, but we could make this page look a little better.</para>
- <para>Open <emphasis>
- <property>WebContent/myAction.xhtml</property>
- </emphasis> in JBoss Developer Studio to use the nice facelets editor.</para>
- <figure>
- <title>Open Seam Action with Editor </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam24.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Right click on the "myAction!" button in the visual part of editor and select
- <property><h:commandButton> Attributes</property>.</para>
- <figure>
- <title>Seam Action Editing</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam25.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Change the <property>value</property> of the button to something different. If desired,
- you can change any other text on the page. Then, type <emphasis>
- <property>CTRL + S</property>
- </emphasis> to save the facelet.</para>
- <figure>
- <title>Attributes Dialog</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam26.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Refresh <emphasis>
- <property>http://localhost:8080/workshop/myAction.seam</property>
- </emphasis> and now you should see your changes.</para>
- <para>Notice that you did not have to publish the application. JBoss Developer Studio
- auto-published it for you.</para>
- <figure>
- <title>Seam Action Is Modified</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam27.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- </section>
- <section id="declarative_security">
- <title>Declarative Security</title>
- <para>In this section you will see how it’s easy to secure the facelets and facelet components
- in Seam. Let’s go ahead and secure the action button, then we will secure the entire
- page.</para>
- <section id="edit_login">
- <title>Edit Login Authentication Logic</title>
- <para>There is a class called <property>Authenticator.java</property>. The login page will
- execute the <property>Authenticator.authenticate()</property> method by default, so we’ll
- start by adding some custom login logic.</para>
- <para>Open <property>Authenticator.java</property> in JBoss Developer Studio and replace the
- <property>authenticate()</property> method with this code:</para>
- <programlisting><![CDATA[public boolean authenticate()
-{
- if ("admin".equals(credentials.getUsername()))
- {
- identity.addRole("admin");
- return true;
- }
- return false;
-}]]></programlisting>
- </section>
- <section id="secure_seam_page">
- <title>Secure Seam Page Component</title>
- <para>Open <property>myAction.xhtml</property> and add a new secured command button:</para>
- <programlisting><![CDATA[<h:commandButton id="myActionSecured"
-value="Secured Action Button"
-action="#{myAction.myAction}"
-rendered="#{s:hasRole('admin')}"/>]]></programlisting>
- <para>Refresh <emphasis>
- <property>http://localhost:8080/workshop/myAction.seam</property>
- </emphasis> If you are not logged in you will only see one button. If you are logged in,
- there will be two buttons.</para>
- <figure>
- <title>One Button on a Page</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam28.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The secured button is not visible because the user isn’t logged in as <property
- >"admin"</property>.</para>
- <figure>
- <title>Secured Button is Visible</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam29.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The user is logged in as <property>"admin"</property>. Securing components is
- easy but securing pages is pretty simple as well. </para>
- <para>Open <emphasis>
- <property>WebContent/WEB-INF/pages.xml</property>
- </emphasis>. Then add this markup directly underneath the <pages> element:</para>
- <programlisting><![CDATA[<page view-id="/myAction.xhtml" login-required="true"/>]]></programlisting>
- <para>Refresh <emphasis>
- <property>http://localhost:8080/workshop/myAction.seam</property>
- </emphasis> If you are not logged in you will get bounced back to the login page.</para>
- <figure>
- <title>Login Page</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam30.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Thus, if you enter login credentials for the <property>"admin"</property>
- user, you will be re-directed to the secured page and secured component. If you enter
- different login credentials, page access will be granted, but the secured component will not
- be displayed.</para>
- <para>Congratulations! You have secured your new action both at the facelet component and page
- level. You also added custom authentication logic to the login action.</para>
- </section>
- </section>
- <section id="browsing_workshop_db">
- <title>Browsing Workshop Database</title>
- <para>In this section you get to know how to use the workshop database that was started at the
- beginning of the lab.</para>
- <section id="database_connectivity">
- <title>Database Connectivity Setup</title>
- <para>The workshop data can be browsed inside of JBoss Developer Studio.</para>
- <para>To open the Data Source Explorer, click on <emphasis><property>Window > Open Perspective
- > Other > Database Development</property>.</emphasis></para>
- <para>In the Data Source Explorer, expand a <property>Databases</property> node and select a
- <property>Default</property> database. Right click on it, select <property
- >Connect</property> from the context menu.</para>
- <figure>
- <title>Data Source Explorer</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam31.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="browsing_workshop_db2">
- <title>Browse Workshop Database</title>
- <para>Then in the current view, drill down to the <property>CUSTOMERS</property> table.</para>
- <figure>
- <title>"CUSTOMERS" Table</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam32.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Right click on <property>CUSTOMERS</property>, select <emphasis>
- <property>Data > Sample Contents</property>
- </emphasis> to view the data in the table.</para>
- <para>There should be a SQL Results view on the workbench, but it could be hidden. Click on
- the <property>"Result1"</property> tab in the right side and you should see the
- data in the CUSTOMERS table.</para>
- <figure>
- <title>SQL Results View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam33.png" scale="92"/>
- </imageobject>
- </mediaobject>
- </figure>
- <note>
- <title>Note:</title>
- <para>If you can’t find the SQL Results view tab, click on <emphasis><property>Window > Show
- View > Other > SQL Development > SQL Results</property>.</emphasis></para>
- </note>
- <para>Congratulations! You just connected to the workshop database and queried the content
- using Database Explorer tools.</para>
- </section>
- </section>
- <section id="db_programming">
- <title>Database Programming</title>
- <para>Now, it’s time to reverse engineer the workshop database into a fully functioning Seam
- CRUD(Create Read Update Delete) application.</para>
- <section id="reverse_engineer_crud">
- <title>Reverse Engineer CRUD from a Running Database</title>
- <para>In <property>JBoss Developer Studio</property>, switch to <property>Seam
- perspective</property>, and then right-click the project and select <emphasis><property
- >New > Seam Generate Entities</property>.</emphasis></para>
- <para>"workshop" project in the <property>Seam Generate Entities wizard</property>
- will be selected automatically. There is no need to change something more, click <emphasis>
- <property>Next</property>
- </emphasis> to proceed further.</para>
- <figure>
- <title>Generate Seam Entities</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam34.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>On the next page use the <emphasis>
- <property>Include</property>
- </emphasis> button to include all the tables from the database and click <emphasis>
- <property>Finish</property>.</emphasis></para>
- <figure>
- <title>Selecting Tables</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam34a.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>After running the Generate Entities action, you will see new <emphasis>
- <property>org.domain.workshop.entity</property>
- </emphasis> classes. These classes represent insert/update/delete/query logic.</para>
- <figure>
- <title>org.domain.workshop.entity Classes</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam35.png" scale="90"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>There are also <emphasis>
- <property>org.domain.workshop.entity</property>
- </emphasis> package that contains the JPA classes. These are the entity beans that are
- mapped to database tables.Note,that you can use Seam refactoring tools with Seam components.
- Read more about it in <ulink
- url="http://download.jboss.org/jbosstools/nightly-docs/en/seam/html_single/index.html#seam_refactoring"
- >Seam refactoring tools chapter</ulink> of Seam Dev Tools Reference Guide.</para>
- <para>Last, but not least, there are facelets for all of the CRUD screens. The best way to get
- a feel for the generated code is to open a browser and play around with the application. Go
- to <emphasis>
- <property>http://localhost:8080/workshop</property>
- </emphasis> and insert/update/delete/query a few records. There is quite a bit of AJAX in
- this application, but which we will explore further later on in the lab. For now, take note
- of the page tabs, required field logic and data table sorting in the list pages. </para>
- <figure>
- <title>CustomersList.xhtml in the Editor</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam36.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Congratulations! You now have a fully functioning CRUD application that is already AJAX
- enabled.</para>
- </section>
- <section id="use_hibernate_tools">
- <title>Use Hibernate Tools to Query Data via JPA</title>
- <para>Now, it's time to write some JPA queries using the Hibernate perspective in
- <property>JBoss Developer Studio</property>.</para>
- <para>In the upper right corner of the workbench there is a small icon (see the figure below),
- click on it and choose <property>Hibernate</property>.</para>
- <figure>
- <title>Hibernate Perspective</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam37.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Look at the Hibernate Configurations view. In the "workshop" project, drill
- down on the <property>Session Factory</property> and notice that the JPA entities/attributes
- are listed in a nice tree view.</para>
- <figure>
- <title>Hibernate Configurations View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam38.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Right click on the <property>Session Factory</property> and select <property>HQL
- Editor</property>. This will open a JPA query scratch pad window.</para>
- <para>Write your query and click on the "Hibernate Dynamic SQL Preview" tab. You
- should see the SQL that will be executed if this JPA query is run.</para>
- <figure>
- <title>JPA Query Editor</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam39.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Run the query by clicking on the green run icon.</para>
- <para>The results are listed in the "Hibernate Query Result" tab. There is a
- "Properties" tab in the workbench that can be used to see a specific JPA result.
- These results represent the JPA objects because our query did not specify column
- names.</para>
- <figure>
- <title>Hibernate Query Result View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam40.png" scale="80"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The query can be refined, and take note that there is nice code completion in the JPA
- query editor.</para>
- <figure>
- <title>Code Completion</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam41.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>A refined query will return results that are more ResultSet oriented. Notice the join
- logic that JPA supports.</para>
- <figure>
- <title>The Hibernate Query Result</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam42.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>There was no need to specify an <property>Employees</property> table in the <property
- >from</property> part of the JPA query because JPA supports reference traversal via Java
- class attribute references. Not only are JPA and HQL queries fully supported, but Criteria
- based queries can also be written in the Criteria Editor. You should spend some time
- tinkering with different queries and possibly Criteria based queries, even though the
- instructions are not provided in this lab.</para>
- <figure>
- <title>Criteria Editor</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam43.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="use_hibernate_to_vizualize">
- <title>Use Hibernate Tools to visualize the Data Model</title>
- <para>Now, it’s time to view the data model for the workshop database.</para>
- <para>In the Hibernate Configurations view, select "workshop" project and expand the
- <property>Configuration</property> node. Select the <property>Customers</property> entity,
- right click on it, choose <property>Open Mapping Diagram</property>.</para>
- <figure>
- <title>Mapping Diagram Opening</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam44.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>You see a Diagram tab for the CUSTOMERS table and any tables that have FK references.
- This is a handy way to view the data model and JPA mappings. Now, you’ve got access to
- something that the Erwin Data Modeler can’t do.</para>
- <figure>
- <title>Diagram Tab</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam45.png" scale="80"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- </section>
- <section id="rich_components">
- <title>Rich Components</title>
- <para>This lab will conclude with one last AJAX twist. In this section we add a RichFaces
- <property>inputNumberSlider</property> to the Order Details edit screen.</para>
- <section id="add_richfaces">
- <title>Add a Richfaces component to the CRUD Application</title>
- <para>Switch to Seam perspective, open <emphasis>
- <property>WebContent/OrderdetailsEdit.xhtml</property>
- </emphasis> in JBoss Developer Studio.</para>
- <para>Change the form field values using the visual editor. Seam has generated the form field
- names that match the database column names. This is not ideal for business users.</para>
- <figure>
- <title>Form Fields Editing</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam46.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Also, replace the QTY Ordered input field with a <property>inputNumberSlider</property>.
- You can use the JBoss Developer Studio palette or right click on the form and insert the
- RichFaces component.</para>
- <figure>
- <title>Insert RichFaces Component from Context Menu</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam47.png" scale="85"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>One the last option is to use the source view and manually copy the inputNumberSlider
- markup listed below:</para>
- <programlisting><![CDATA[<rich:inputNumberSlider id="quantityOrdered" required="true"
- value="#{orderdetailsHome.instance.quantityordered}"/>]]></programlisting>
- <figure>
- <title>Manually coping Source Code</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam48.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The end result is an edit page that has better form labels and a new RichFaces
- control.</para>
- <figure>
- <title>The Result Page</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/first_seam/first_seam49.png" scale="85"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>Congratulations! You have completed the JBoss Developer Studio lab.</para>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="first_seam" xreflabel="first_seam">
+ <?dbhtml filename="first_seam.html"?>
+ <chapterinfo>
+ <keywordset>
+ <keyword>JBoss Developer Studio</keyword>
+ <keyword>Seam</keyword>
+ <keyword>JBoss</keyword>
+ </keywordset>
+ </chapterinfo>
+ <title>Write Your First Project with JBoss Developer Studio</title>
+ <para>This chapter is a set of hands-on labs. You get step-by-step information about how the JBoss
+ Developer Studio can be used during the development process.</para>
+ <section id="create_seam_application">
+ <title>Create a Seam Application</title>
+ <para>In this section you get to know how to create a Seam project in JBDS, how to start the
+ server and what a structure your project has after creating.</para>
+ <section id="start_dev_db">
+ <title>Start Development Database</title>
+ <para>Before opening the JBoss Developer studio you need to download and start <ulink
+ url="http://docs.jboss.org/tools/resources/GSG_database.zip">Workshop Database</ulink>
+ .</para>
+ <para>To start the database just run <property>./runDBServer.sh</property> or <property
+ >runDBServer.bat</property> from the database directory.</para>
+ <para>The end result should be a console window that looks like:</para>
+ <figure>
+ <title>Starting DataBase</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam1.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="create_deploy_seam">
+ <title>Create and deploy Seam Web Project</title>
+ <para>Minimize the terminal window and run the <property>JBoss Developer Studio</property>
+ from Applications Menu or from the desktop icon.</para>
+ <para>First of all you get the Workspace Launcher. Change the default workspace location if
+ it's needed. Click on <property>Ok</property>. </para>
+ <figure>
+ <title>Workspace Launcher Dialog</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam2.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>After startup, you see the welcome page. You could read how to work with welcome pages
+ in <link linkend="Welcome">previous</link> chapter. Now select <property>Create
+ New...</property> icon and then press on <property>Create Seam Project</property>
+ link.</para>
+ <para>The <property>New Seam Project wizard</property> is started. You need to enter a name
+ (e.g., "workshop") and a location directory for your new project. The wizard has
+ an option for selecting the actual Server (and not just WTP runtime) that will be used for
+ the project. This allows the wizard to correctly identify where the needed datasource and
+ driver libraries need to go.</para>
+ <figure>
+ <title>New Seam Project Wizard</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam3.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>All settings are already specified here, you can just modify the Configuration. Click on
+ the <emphasis>
+ <property>Modify...</property>
+ </emphasis> button to configure your custom facets pattern:</para>
+ <figure id="ProjectFacetsSpecifyingScreen">
+ <title>Project Facets Specifying</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam4.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>On the whole the dialog allows to select the "features" you want to use in your project.
+ Doing this <property>JBoss Developer Studio</property> setups the appropriate tooling for
+ your project. Since JBoss Seam integrates all popular Java EE frameworks, you can select any
+ combination of technologies from the list. Here, for the default configuration, Dynamic Web
+ Module, Java, JavaServer Faces (JSF), and Seam Facet are already selected for a typical
+ database-driven web application. The default project facets should suffice.</para>
+ <para>In the <property>Project Facets</property> form you can also bring up server runtimes
+ panel by clicking <property> Runtimes</property> tab on the right corner. This panel shows
+ available server runtimes.</para>
+ <figure>
+ <title>Runtimes Selecting</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam5.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Click on <emphasis>
+ <property>Ok</property>
+ </emphasis> and then <emphasis>
+ <property>Next</property>
+ </emphasis> to proceed further.</para>
+ <para>A dynamic web application contains both web pages and <property>Java</property> code.
+ The next wizard will ask you where you want to store Java files.</para>
+ <figure>
+ <title>Java Build Path</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam5a.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Following page provides you <property>Web Module Settings</property> .You can just leave
+ the default values or choose another folder.</para>
+ <figure>
+ <title>Web Module Settings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam6.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>On the next form, you will be able to select where those library JARs come from. The
+ easiest is just to select the JARs provided by the JBoss AS runtime associated with this
+ project. That is why it is important to chose the right JBoss AS 4.2 runtime in the project
+ setup window.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Select <emphasis>
+ <property>Library Provided by Target Runtime</property>
+ </emphasis> as <property>Type</property> of <property>JSF Implementation
+ Library</property>. We will use the JSF implementation that comes with JBoss
+ server.</para>
+ </listitem>
+ <listitem>
+ <para>Click <emphasis>
+ <property>Next</property>
+ </emphasis></para>
+ </listitem>
+ </itemizedlist>
+ <figure>
+ <title>JSF Capabilities Adding</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam7.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Next wizard step needs more settings that previous. Let's start with <property
+ >General</property> section.</para>
+ <para>Leave the default Seam runtime and check a WAR deployment.</para>
+ <figure>
+ <title>Seam Facet Setting</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam8.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Next <property>Database</property> section is a little tricky. The <property>Connection
+ Profile</property> needs to be edited so that the new project works properly with the
+ external HSQLDB server. By default the project wizard tries to use the JBoss embedded
+ HSQLDB, but the tutorial uses an external database to replicate a more real world
+ development scenario. Click on <property>Edit</property> to modify the Connection
+ Profile.</para>
+ <figure>
+ <title>DataBase Setting</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam8_1.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Select <property>HSQLDB Profile Properties</property>. Make sure the Database location
+ is set to <emphasis>
+ <property>hsql://localhost:1701</property>
+ </emphasis></para>
+ <figure>
+ <title>JDBC Connection Properties</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam9.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Try click on <property>Test Connection</property> button. It probably won’t work. This
+ happens if the hsql jdbc driver is not exactly the same. This can be worked around by
+ modifying the HSQLDB database driver settings. To modify the settings, click the Edit Driver Definition Driver(
+ <inlinemediaobject><imageobject>
+ <imagedata fileref="images/first_seam/first_seam9_1.png"/>
+ </imageobject>
+ </inlinemediaobject>) .</para>
+ <para>The proper Driver JAR File should be listed under <property>Jar List</property>. Select
+ the hsqldb.jar file found in the jbdevstudio/jboss-eap/jboss-as/common/lib/ directory and
+ click <property>Ok</property>.</para>
+ <figure>
+ <title>Driver Details</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam10.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Now, the <property>Test Connection</property> should succeed. After testing the
+ connection, click <emphasis><property>Ok</property></emphasis>.</para>
+ <figure>
+ <title>Connection Testing</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam12.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>You can leave the <property>Code Generation</property> section as is. It refers to Java
+ packages in which the generated code will be placed.</para>
+
+ <figure>
+ <title>Code Generation Setting</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam13.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <tip>
+ <title>Tip:</title>
+ <para>If you want to name your web project "MyProject-war" note that the Test project name should not be "MyProject-war-test",
+ it should be "MyProject-test".</para>
+ </tip>
+
+ <para>Click on <property>Finish</property> button. Now, there should be a new Seam project
+ called “workshop” listed in Package Explorer view.</para>
+ <figure>
+ <title>"worskhop" Project in the Package Explorer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam14.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="start_JBossAS">
+ <title>Start JBoss Application Server</title>
+ <para>The complete information on how to manage JBoss AS from JBoss Developer Studio you can
+ read in a <link linkend="manage">corresponding chapter</link>.</para>
+ <para>Now you just need to start the server by clicking on the Start the server icon (
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam15.png"/>
+ </imageobject>
+ </inlinemediaobject> ) in the <property>Servers</property>.</para>
+ <para>Then run the project by selecting the project and use <emphasis><property>Run As... >
+ Run on Server</property>.</emphasis></para>
+ <note>
+ <title>Note:</title>
+ <para>If the project does not show up, then you can use a normal browser and use <emphasis>
+ <property>http://localhost:8080/workshop/home.seam</property>
+ </emphasis> as the url.</para>
+ </note>
+ <para>Your project looks like this:</para>
+ <figure>
+ <title>"workshop" Project Started</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam16.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="workshop_code_overview">
+ <title>Workshop Project Code Overview</title>
+ <para>Now let's examine the project and its structure. Go back to the Package Explorer view in
+ JBoss Developer Studio.</para>
+ <para>It seems like it's not much for project but this shell application contains a login
+ screen with default login logic, a menu template that can be further modified, and other
+ layout templates.</para>
+ <para>It's important to note that the business logic will reside in the <emphasis>
+ <property>src/hot</property>
+ </emphasis> folder, by default. And, the package naming conventions that were used in
+ <property>New Seam project wizard</property> could have been changed to something
+ different from <emphasis>
+ <property>org.domain.workshop.session</property>. </emphasis> Also, notice that there is a
+ default <property>Authenticator. java</property> file. This is where custom security logic
+ can be added. Seam has a nice declarative security model that we will explore in a bit more
+ detail later on. The <emphasis>
+ <property>src/main</property>
+ </emphasis> folder is a model directory. It stores the project's JPA entity
+ beans.</para>
+ <figure>
+ <title>Project Structure</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam17.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The view tier of the application is also important. Seam uses facelets and there is a
+ built-in facelets GUI editor that has some nice WYSIWYG and component drag/drop
+ functionality. Try this out by opening <property>home.xhtml</property> from <property
+ >WebContent</property> folder.</para>
+ <figure>
+ <title>Facelets GUI Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam18.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Notice that the templates reside in the <emphasis>
+ <property>WebContent/layout</property>
+ </emphasis> folder. There is a stylesheet in the <emphasis>
+ <property>WebContent/stylesheet</property>
+ </emphasis> folder. There is also a login and default error page. The Facelet editor will be
+ explored in more detail later in the lab.</para>
+ <para>The project already has a datasource that was created per the Seam project wizard
+ database settings. And, obviously all of the Seam specific configuration files and JAR
+ dependencies are included and placed in the proper locations. On last noteworthy line item
+ is related to the build script. There isn’t a build script because the Eclipse WTP(Web Tools
+ Project) plugin is used to publish web application changes. As you can see, JBoss Developer
+ Studio is removing a great deal of complexity from the enterprise Java project
+ setup/deployment process. The end result is a developer that is writing code, not spending
+ days/weeks trying to figure out how to get a decent development environment and project
+ build process.</para>
+ </section>
+ </section>
+ <section id="seam_action_dev">
+ <title>Seam Action Development</title>
+ <para>Now, it’s time to write some code. The good news is that JBoss Developer Studio can also
+ help out in this respect. In this section, we will create a new Seam Action POJO and facelet
+ with some custom business logic and some GUI changes.</para>
+ <section id="create_seam_action">
+ <title>Create a New Seam Action</title>
+ <para>Go to main menu bar and click on <emphasis>
+ <property>File > New > New Seam Action</property>
+ </emphasis> to start the New Seam Action wizard.</para>
+ <para>Specify a <property>Seam component name</property> (e.g., "myAction"). The
+ other properties will be auto-completed for you so there is no need to change them. Click on
+ <property>Finish</property>.</para>
+ <figure>
+ <title>New Seam Action Wizard</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam19.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Now, open the <property>MyAction.java</property> file and replace the
+ "myAction" method with this logic:</para>
+ <programlisting><![CDATA[public void myAction() {
+Calendar cal = Calendar.getInstance();
+log.info("myAction.myAction() action called");
+facesMessages.add("MyAction Executed on:" + cal.getTime());
+}]]></programlisting>
+ <para>You also need to import the <property>java.util.Calendar</property> class by clicking
+ <emphasis><property>CTRL + Shift + O</property>.</emphasis></para>
+ </section>
+ <section id="test_seam_action">
+ <title>Test Seam Action</title>
+ <para>The new action can be tested by browsing the workshop-test project. JBoss Developer
+ Studio has already created a TestNG test case for you.</para>
+ <figure>
+ <title>"workshop-test" Project</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam20.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The test case simulates a Seam component/method execution for the <property
+ >MyAction.myAction()</property> logic.</para>
+ <para>To run the test case, right click on <property>MyActionTest.xml</property> and click
+ <emphasis>
+ <property>Run As > TestNG Suite</property>
+ </emphasis> or use the <property>Run As...</property> toolbar shortcut as shown
+ below.</para>
+ <figure>
+ <title>TestNG Running</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam21.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>With any luck, the test case will pass. Look at the TestNG view.</para>
+ <figure>
+ <title>TestNG Results</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam22.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Now, it’s safe to test the new Seam Action in a web browser. The fastest way to do that
+ is to right click on <property>myAction.xhtml</property> and use <emphasis>
+ <property>Run As... > Run On Server</property>
+ </emphasis> which will show the appropriate url in the browser. Alternatively you can
+ manually enter <emphasis>
+ <property>http://localhost:8080/workshop/myAction.seam</property>
+ </emphasis> into a browser.</para>
+ <figure>
+ <title>Seam Action in a Web Browser</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam23.png" scale="90"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="modify_seam_action">
+ <title>Modify Seam Action User Interface</title>
+ <para>Browse to <emphasis>
+ <property>http://localhost:8080/workshop/myAction.seam</property>
+ </emphasis> and click on <property>myAction</property>. This executes the “myAction” method.
+ This looks pretty good, but we could make this page look a little better.</para>
+ <para>Open <emphasis>
+ <property>WebContent/myAction.xhtml</property>
+ </emphasis> in JBoss Developer Studio to use the nice facelets editor.</para>
+ <figure>
+ <title>Open Seam Action with Editor </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam24.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Right click on the "myAction!" button in the visual part of editor and select
+ <property><h:commandButton> Attributes</property>.</para>
+ <figure>
+ <title>Seam Action Editing</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam25.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Change the <property>value</property> of the button to something different. If desired,
+ you can change any other text on the page. Then, type <emphasis>
+ <property>CTRL + S</property>
+ </emphasis> to save the facelet.</para>
+ <figure>
+ <title>Attributes Dialog</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam26.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Refresh <emphasis>
+ <property>http://localhost:8080/workshop/myAction.seam</property>
+ </emphasis> and now you should see your changes.</para>
+ <para>Notice that you did not have to publish the application. JBoss Developer Studio
+ auto-published it for you.</para>
+ <figure>
+ <title>Seam Action Is Modified</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam27.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ <section id="declarative_security">
+ <title>Declarative Security</title>
+ <para>In this section you will see how it’s easy to secure the facelets and facelet components
+ in Seam. Let’s go ahead and secure the action button, then we will secure the entire
+ page.</para>
+ <section id="edit_login">
+ <title>Edit Login Authentication Logic</title>
+ <para>There is a class called <property>Authenticator.java</property>. The login page will
+ execute the <property>Authenticator.authenticate()</property> method by default, so we’ll
+ start by adding some custom login logic.</para>
+ <para>Open <property>Authenticator.java</property> in JBoss Developer Studio and replace the
+ <property>authenticate()</property> method with this code:</para>
+ <programlisting><![CDATA[public boolean authenticate()
+{
+ if ("admin".equals(credentials.getUsername()))
+ {
+ identity.addRole("admin");
+ return true;
+ }
+ return false;
+}]]></programlisting>
+ </section>
+ <section id="secure_seam_page">
+ <title>Secure Seam Page Component</title>
+ <para>Open <property>myAction.xhtml</property> and add a new secured command button:</para>
+ <programlisting><![CDATA[<h:commandButton id="myActionSecured"
+value="Secured Action Button"
+action="#{myAction.myAction}"
+rendered="#{s:hasRole('admin')}"/>]]></programlisting>
+ <para>Refresh <emphasis>
+ <property>http://localhost:8080/workshop/myAction.seam</property>
+ </emphasis> If you are not logged in you will only see one button. If you are logged in,
+ there will be two buttons.</para>
+ <figure>
+ <title>One Button on a Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam28.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The secured button is not visible because the user isn’t logged in as <property
+ >"admin"</property>.</para>
+ <figure>
+ <title>Secured Button is Visible</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam29.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The user is logged in as <property>"admin"</property>. Securing components is
+ easy but securing pages is pretty simple as well. </para>
+ <para>Open <emphasis>
+ <property>WebContent/WEB-INF/pages.xml</property>
+ </emphasis>. Then add this markup directly underneath the <pages> element:</para>
+ <programlisting><![CDATA[<page view-id="/myAction.xhtml" login-required="true"/>]]></programlisting>
+ <para>Refresh <emphasis>
+ <property>http://localhost:8080/workshop/myAction.seam</property>
+ </emphasis> If you are not logged in you will get bounced back to the login page.</para>
+ <figure>
+ <title>Login Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam30.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Thus, if you enter login credentials for the <property>"admin"</property>
+ user, you will be re-directed to the secured page and secured component. If you enter
+ different login credentials, page access will be granted, but the secured component will not
+ be displayed.</para>
+ <para>Congratulations! You have secured your new action both at the facelet component and page
+ level. You also added custom authentication logic to the login action.</para>
+ </section>
+ </section>
+ <section id="browsing_workshop_db">
+ <title>Browsing Workshop Database</title>
+ <para>In this section you get to know how to use the workshop database that was started at the
+ beginning of the lab.</para>
+ <section id="database_connectivity">
+ <title>Database Connectivity Setup</title>
+ <para>The workshop data can be browsed inside of JBoss Developer Studio.</para>
+ <para>To open the Data Source Explorer, click on <emphasis><property>Window > Open Perspective
+ > Other > Database Development</property>.</emphasis></para>
+ <para>In the Data Source Explorer, expand a <property>Databases</property> node and select a
+ <property>Default</property> database. Right click on it, select <property
+ >Connect</property> from the context menu.</para>
+ <figure>
+ <title>Data Source Explorer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam31.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="browsing_workshop_db2">
+ <title>Browse Workshop Database</title>
+ <para>Then in the current view, drill down to the <property>CUSTOMERS</property> table.</para>
+ <figure>
+ <title>"CUSTOMERS" Table</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam32.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Right click on <property>CUSTOMERS</property>, select <emphasis>
+ <property>Data > Sample Contents</property>
+ </emphasis> to view the data in the table.</para>
+ <para>There should be a SQL Results view on the workbench, but it could be hidden. Click on
+ the <property>"Result1"</property> tab in the right side and you should see the
+ data in the CUSTOMERS table.</para>
+ <figure>
+ <title>SQL Results View</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam33.png" scale="92"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <title>Note:</title>
+ <para>If you can’t find the SQL Results view tab, click on <emphasis><property>Window > Show
+ View > Other > SQL Development > SQL Results</property>.</emphasis></para>
+ </note>
+ <para>Congratulations! You just connected to the workshop database and queried the content
+ using Database Explorer tools.</para>
+ </section>
+ </section>
+ <section id="db_programming">
+ <title>Database Programming</title>
+ <para>Now, it’s time to reverse engineer the workshop database into a fully functioning Seam
+ CRUD(Create Read Update Delete) application.</para>
+ <section id="reverse_engineer_crud">
+ <title>Reverse Engineer CRUD from a Running Database</title>
+ <para>In <property>JBoss Developer Studio</property>, switch to <property>Seam
+ perspective</property>, and then right-click the project and select <emphasis><property
+ >New > Seam Generate Entities</property>.</emphasis></para>
+ <para>"workshop" project in the <property>Seam Generate Entities wizard</property>
+ will be selected automatically. There is no need to change something more, click <emphasis>
+ <property>Next</property>
+ </emphasis> to proceed further.</para>
+ <figure>
+ <title>Generate Seam Entities</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam34.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>On the next page use the <emphasis>
+ <property>Include</property>
+ </emphasis> button to include all the tables from the database and click <emphasis>
+ <property>Finish</property>.</emphasis></para>
+ <figure>
+ <title>Selecting Tables</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam34a.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>After running the Generate Entities action, you will see new <emphasis>
+ <property>org.domain.workshop.entity</property>
+ </emphasis> classes. These classes represent insert/update/delete/query logic.</para>
+ <figure>
+ <title>org.domain.workshop.entity Classes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam35.png" scale="90"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>There are also <emphasis>
+ <property>org.domain.workshop.entity</property>
+ </emphasis> package that contains the JPA classes. These are the entity beans that are
+ mapped to database tables.Note,that you can use Seam refactoring tools with Seam components.
+ Read more about it in <ulink
+ url="http://download.jboss.org/jbosstools/nightly-docs/en/seam/html_single/index.html#seam_refactoring"
+ >Seam refactoring tools chapter</ulink> of Seam Dev Tools Reference Guide.</para>
+ <para>Last, but not least, there are facelets for all of the CRUD screens. The best way to get
+ a feel for the generated code is to open a browser and play around with the application. Go
+ to <emphasis>
+ <property>http://localhost:8080/workshop</property>
+ </emphasis> and insert/update/delete/query a few records. There is quite a bit of AJAX in
+ this application, but which we will explore further later on in the lab. For now, take note
+ of the page tabs, required field logic and data table sorting in the list pages. </para>
+ <figure>
+ <title>CustomersList.xhtml in the Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam36.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Congratulations! You now have a fully functioning CRUD application that is already AJAX
+ enabled.</para>
+ </section>
+ <section id="use_hibernate_tools">
+ <title>Use Hibernate Tools to Query Data via JPA</title>
+ <para>Now, it's time to write some JPA queries using the Hibernate perspective in
+ <property>JBoss Developer Studio</property>.</para>
+ <para>In the upper right corner of the workbench there is a small icon (see the figure below),
+ click on it and choose <property>Hibernate</property>.</para>
+ <figure>
+ <title>Hibernate Perspective</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam37.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Look at the Hibernate Configurations view. In the "workshop" project, drill
+ down on the <property>Session Factory</property> and notice that the JPA entities/attributes
+ are listed in a nice tree view.</para>
+ <figure>
+ <title>Hibernate Configurations View</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam38.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Right click on the <property>Session Factory</property> and select <property>HQL
+ Editor</property>. This will open a JPA query scratch pad window.</para>
+ <para>Write your query and click on the "Hibernate Dynamic SQL Preview" tab. You
+ should see the SQL that will be executed if this JPA query is run.</para>
+ <figure>
+ <title>JPA Query Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam39.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Run the query by clicking on the green run icon.</para>
+ <para>The results are listed in the "Hibernate Query Result" tab. There is a
+ "Properties" tab in the workbench that can be used to see a specific JPA result.
+ These results represent the JPA objects because our query did not specify column
+ names.</para>
+ <figure>
+ <title>Hibernate Query Result View</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam40.png" scale="80"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The query can be refined, and take note that there is nice code completion in the JPA
+ query editor.</para>
+ <figure>
+ <title>Code Completion</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam41.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>A refined query will return results that are more ResultSet oriented. Notice the join
+ logic that JPA supports.</para>
+ <figure>
+ <title>The Hibernate Query Result</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam42.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>There was no need to specify an <property>Employees</property> table in the <property
+ >from</property> part of the JPA query because JPA supports reference traversal via Java
+ class attribute references. Not only are JPA and HQL queries fully supported, but Criteria
+ based queries can also be written in the Criteria Editor. You should spend some time
+ tinkering with different queries and possibly Criteria based queries, even though the
+ instructions are not provided in this lab.</para>
+ <figure>
+ <title>Criteria Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam43.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="use_hibernate_to_vizualize">
+ <title>Use Hibernate Tools to visualize the Data Model</title>
+ <para>Now, it’s time to view the data model for the workshop database.</para>
+ <para>In the Hibernate Configurations view, select "workshop" project and expand the
+ <property>Configuration</property> node. Select the <property>Customers</property> entity,
+ right click on it, choose <property>Open Mapping Diagram</property>.</para>
+ <figure>
+ <title>Mapping Diagram Opening</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam44.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>You see a Diagram tab for the CUSTOMERS table and any tables that have FK references.
+ This is a handy way to view the data model and JPA mappings. Now, you’ve got access to
+ something that the Erwin Data Modeler can’t do.</para>
+ <figure>
+ <title>Diagram Tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam45.png" scale="80"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ <section id="rich_components">
+ <title>Rich Components</title>
+ <para>This lab will conclude with one last AJAX twist. In this section we add a RichFaces
+ <property>inputNumberSlider</property> to the Order Details edit screen.</para>
+ <section id="add_richfaces">
+ <title>Add a Richfaces component to the CRUD Application</title>
+ <para>Switch to Seam perspective, open <emphasis>
+ <property>WebContent/OrderdetailsEdit.xhtml</property>
+ </emphasis> in JBoss Developer Studio.</para>
+ <para>Change the form field values using the visual editor. Seam has generated the form field
+ names that match the database column names. This is not ideal for business users.</para>
+ <figure>
+ <title>Form Fields Editing</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam46.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Also, replace the QTY Ordered input field with a <property>inputNumberSlider</property>.
+ You can use the JBoss Developer Studio palette or right click on the form and insert the
+ RichFaces component.</para>
+ <figure>
+ <title>Insert RichFaces Component from Context Menu</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam47.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>One the last option is to use the source view and manually copy the inputNumberSlider
+ markup listed below:</para>
+ <programlisting><![CDATA[<rich:inputNumberSlider id="quantityOrdered" required="true"
+ value="#{orderdetailsHome.instance.quantityordered}"/>]]></programlisting>
+ <figure>
+ <title>Manually coping Source Code</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam48.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The end result is an edit page that has better form labels and a new RichFaces
+ control.</para>
+ <figure>
+ <title>The Result Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/first_seam/first_seam49.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Congratulations! You have completed the JBoss Developer Studio lab.</para>
+ </section>
+ </section>
+</chapter>
\ No newline at end of file
Modified: trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam13.png
===================================================================
(Binary files differ)
Modified: trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam3.png
===================================================================
(Binary files differ)
Modified: trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam5.png
===================================================================
(Binary files differ)
Modified: trunk/documentation/guides/GettingStartedGuide/en-US/images/first_seam/first_seam8.png
===================================================================
(Binary files differ)
More information about the jbosstools-commits
mailing list