[jbosstools-commits] JBoss Tools SVN: r22411 - in trunk/documentation/guides/GettingStartedGuide/en-US: images/first_seam and 1 other directory.

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">... 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., &quot;workshop&quot;) 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>&quot;worskhop&quot; 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>&quot;workshop&quot; 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&apos;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&apos;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&apos;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., &quot;myAction&quot;). 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 - &quot;myAction&quot; 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>&quot;workshop-test&quot; 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 &quot;myAction!&quot; button in the visual part of editor and select - <property>&lt;h:commandButton&gt; 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 - >&quot;admin&quot;</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>&quot;admin&quot;</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 &lt;pages&gt; 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>&quot;admin&quot;</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>&quot;CUSTOMERS&quot; 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>&quot;Result1&quot;</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>&quot;workshop&quot; 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_... - >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&apos;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 &quot;workshop&quot; 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 &quot;Hibernate Dynamic SQL Preview&quot; 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 &quot;Hibernate Query Result&quot; tab. There is a - &quot;Properties&quot; 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 &quot;workshop&quot; 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">... 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., &quot;workshop&quot;) 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>&quot;worskhop&quot; 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>&quot;workshop&quot; 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&apos;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&apos;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&apos;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., &quot;myAction&quot;). 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 + &quot;myAction&quot; 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>&quot;workshop-test&quot; 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 &quot;myAction!&quot; button in the visual part of editor and select + <property>&lt;h:commandButton&gt; 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 + >&quot;admin&quot;</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>&quot;admin&quot;</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 &lt;pages&gt; 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>&quot;admin&quot;</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>&quot;CUSTOMERS&quot; 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>&quot;Result1&quot;</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>&quot;workshop&quot; 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_... + >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&apos;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 &quot;workshop&quot; 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 &quot;Hibernate Dynamic SQL Preview&quot; 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 &quot;Hibernate Query Result&quot; tab. There is a + &quot;Properties&quot; 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 &quot;workshop&quot; 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)