<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id="gettingstartedwithjbosstools">
   <title>Getting started with Seam, using JBoss Tools</title>

   <para>
      JBoss Tools is a collection of Eclipse plugins. JBoss Tools a project
      creation wizard for Seam, Content Assist for the Unified Expression
      Language (EL) in both facelets and Java code, a graphical editor for jPDL,
      a graphical editor for Seam configuration files, support for running Seam
      integration tests from within Eclipse, and much more.
   </para>

   <para>
      In short, if you are an Eclipse user, then you'll want JBoss Tools!
   </para>

   <para>
      JBoss Tools, as with seam-gen, works best with JBoss AS, but it's possible
      with a few tweaks to get your app running on other application servers.
      The changes are much like those described for seam-gen later in this
      reference manual.
   </para>

   <section>
      <title>Before you start</title>

      <para>
         Make sure you have JBoss EAP 4.3 FP01 and JBDS installed.
      </para>

   </section>

   <section>
      <title>Setting up a new Seam project</title>

      <para>
         Start up Eclipse and select the <emphasis>Seam</emphasis> perspective.
      </para>

      <para>
         Go to <emphasis>File</emphasis> -> <emphasis>New</emphasis> ->
          <emphasis>Seam Web Project</emphasis>.
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_web_project_0.png"
               align="center" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_web_project_0.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         First, enter a name for your new project. For this tutorial, we're
         going to use
         <literal>helloworld</literal>
         .
      </para>


      <para>
         Now, we need to tell JBoss Tools about JBoss AS. This is a two stage
         process, first we need to define a runtime, make sure you select JBoss
         AS 4.2:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_server_runtime_1.png"
               align="center" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_server_runtime_1.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         Enter a name for the runtime, and locate it on your hard drive:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_server_runtime_2.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_server_runtime_2.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         Next, we need to define a server JBoss Tools can deploy the project to.
         Make sure to again select JBoss AS 4.2, and also the runtime you just
         defined:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_server_1.png" align="center"
                />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_server_1.png" align="center" />
         </imageobject>
      </mediaobject>

      <para>
         On the next screen give the server a name, and hit 
         <emphasis>Finish</emphasis>:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_server_2.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_server_2.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         Make sure the runtime and server you just created are selected, select
         <emphasis>Dynamic Web Project with Seam 2.0 (technology preview)</emphasis>
         and hit <emphasis>Next</emphasis>:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_web_project_1.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_web_project_1.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         The next 3 screens allow you to further customize your new project, but
         for us the defaults are fine. So just hit <emphasis>Next</emphasis> 
         until you reach the final screen.
      </para>
      
      <para>
         The first step here is to tell JBoss Tools about the Seam download you
         want to use. <emphasis>Add</emphasis> a new 
         <emphasis>Seam Runtime</emphasis> - make sure to give it a name, and
         select <emphasis>2.0</emphasis> as the version:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_seam_runtime.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_seam_runtime.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         The most important choice you need to make is between EAR deployment
         and WAR deployment of your project. EAR projects support EJB 3.0 and
         require Java EE 5. WAR projects do not support EJB 3.0, but may be
         deployed to a J2EE environment. The packaging of a WAR is also simpler
         to understand. If you installed an EJB3-ready application server like
         JBoss, choose <emphasis>EAR</emphasis>. Otherwise, choose
         <emphasis>WAR</emphasis>.  We'll assume that you've chosen a WAR 
         deployment for the rest of the tutorial, but you can follow exactly the
         same steps for a EAR deployment.
      </para>
      
      <para>
         Next, select your database type. We'll assume you have MySQL installed,
         with an existing schema. You'll need to tell JBoss Tools about
         the database, select <emphasis>MySQL</emphasis> as the database, and
         create a new connection profile. Select <emphasis>Generic JDBC 
         Connection</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_1.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_1.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Give it a name:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_2.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_2.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         JBoss Tools doesn't come with drivers for any databases, so you need to
         tell JBoss Tools where the MySQL JDBC driver is. Tell it about the
         driver by clicking <emphasis>...</emphasis>.
      </para>
      
      <para>
         Locate MySQL 5, and hit <emphasis>Add...</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_3.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_3.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Choose the <emphasis>MySQL JDBC Driver</emphasis> template:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_4.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_4.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Locate the jar on your computer by choosing <emphasis>Edit 
         Jar/Zip</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_5.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_5.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Review the username and password used to connect, and if correct, hit
         <emphasis>Ok</emphasis>.
      </para>
      
      <para>
         Finally, choose the newly created driver:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_connection_profile_6.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_connection_profile_6.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         If you are working with an existing data model, make sure you tell
         JBoss Tools that the tables already exist in the database.
      </para>
      
      <para>
         Review the username and password used to connect, test the connection
         using the <emphasis>Test Connection</emphasis> button, and if it works,
         hit <emphasis>Finish</emphasis>:
      </para>
      
      <para>
         Finally, review the package names for your generated beans, and if you
         are happy, click <emphasis>Finish</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_web_project_2.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_web_project_2.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         JBoss has sophisticated support for hot re-deployment of WARs and EARs.
         Unfortunately, due to bugs in the JVM, repeated redeployment of an
         EAR—which is common during development—eventually causes the JVM to run
         out of perm gen space. For this reason, we recommend running JBoss in a
         JVM with a large perm gen space at development time. We suggest the 
         following values:
      </para>

      <programlisting>
         -Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512
      </programlisting>

      <para>
         If you don't have so much memory available, the following is our
         minimum recommendation:
      </para>

      <programlisting>
         -Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256
      </programlisting>

      <para>
         Locate the server in the <emphasis>JBoss Server View</emphasis>, right
         click on the server and select <emphasis>Edit Launch 
         Configuration</emphasis>: 
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/server_properties_0.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/server_properties_0.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Then, alter the VM arguements:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/server_properties.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/server_properties.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         If you don't want to bother with this stuff now, you don't have to—come
         back to it later, when you get your first
         <literal>OutOfMemoryException</literal>.
      </para>

      <para>
         To start JBoss, and deploy the project, just right click on the server
         you created, and click <emphasis>Start</emphasis>, (or 
         <emphasis>Debug</emphasis> to start in debug mode):
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/start_server.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/start_server.png"
               align="center" />
         </imageobject>
      </mediaobject>

      <para>
         Don't get scared by the XML configuration documents that were generated
         into the project directory. They are mostly standard Java EE stuff, the
         stuff you need to create once and then never look at again, and they
         are 90% the same between all Seam projects.
      </para>

   </section>

   <section>
      <title>Creating a new action</title>

      <para>
         If you're used to traditional action-style web frameworks, you're
         probably wondering how you can create a simple web page with a
         stateless action method in Java.
      </para>
      
      <para>
         First, select <emphasis>New</emphasis> -> <emphasis>Seam Action</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_action_0.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_action_0.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Now, enter the name of the Seam component. JBoss Tools selects sensible
         defaults for other fields:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_action_1.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_action_1.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Finally, hit <emphasis>Finish</emphasis>.
      </para>

      <para>
         Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal>
         and click the button. You can see the code behind this action by
         looking in the project <literal>src</literal> directory. Put a 
         breakpoint in the <literal>ping()</literal> method, and click the 
         button again.
      </para>

      <para>
         Finally, open the <literal>helloworld-test</literal> project, locate
         <literal>PingTest</literal> class, right click on it, and choose
         <emphasis>Run As</emphasis> -> <emphasis>TestNG Test</emphasis>:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/run_test.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/run_test.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
   </section>

   <section>
      <title>Creating a form with an action</title>

      <para>
         The first step is to create a form. Select <emphasis>New</emphasis> -> 
         <emphasis>Seam Form</emphasis>:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_form_0.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_form_0.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Now, enter the name of the Seam component. JBoss Tools selects sensible
         defaults for other fields:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/new_form_1.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/new_form_1.png"
               align="center" />
         </imageobject>
      </mediaobject>
 
      <para>
         Go to <literal>http://localhost:8080/helloworld/hello.seam</literal>. 
         Then take a look at the generated code. Run the test. Try adding some
         new fields to the form and Seam component (note, you don't need to 
         restart the app server each time you change the code in 
         <literal>src/action</literal> as Seam hot reloads the component for 
         you <xref linkend="gettingstartedwithjbosstools.hotdeployment" />).
      </para>
   </section>

   <section>
      <title>Generating an application from an existing database</title>

      <para>
         Manually create some tables in your database. (If you need to switch to
         a different database, create a new project, and select the correct
         database). Then, select <emphasis>New</emphasis> -> 
         <emphasis>Seam Generate Entities</emphasis>:
      </para>

      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/generate_entities_0.png"
               align="center" scalefit="1" />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/generate_entities_0.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         JBoss Tools gives you the option to either reverse engineer
         entities, components and views from a database schema or to reverse
         engineer components and views from existing JPA entities. We're going
         to do <emphasis>Reverse engieneer from database</emphasis>.
      </para>
     
      <para>
         Restart the deployment:
      </para>
      
      <mediaobject>
         <imageobject role="fo">
            <imagedata fileref="images/restart_deployment.png"
               align="center"  />
         </imageobject>
         <imageobject role="html">
            <imagedata fileref="images/restart_deployment.png"
               align="center" />
         </imageobject>
      </mediaobject>
      
      <para>
         Then go to <literal>http://localhost:8080/helloworld</literal>. You can
         browse the database, edit existing objects, and create new objects. If 
         you look at the generated code, you'll probably be amazed how simple it
         is! Seam was designed so that data access code is easy to write by 
         hand, even for people who don't want to cheat by using reverse
         engineering.
      </para>
   </section>

   <section id="gettingstartedwithjbosstools.hotdeployment">
      <title>Seam and incremental hot deployment with JBoss Tools</title>

      <para>
         JBoss Tools supports incremental hot deployment of:
      </para>

      <itemizedlist>
         <listitem>
            <para>any facelets page</para>
         </listitem>

         <listitem>
            <para>
               any <literal>pages.xml</literal> file
            </para>
         </listitem>
      </itemizedlist>
      
      <para>
         out of the box.
      </para>

      <para>
         But if we want to change any Java code, we still need to do a full
         restart of the application by doing a 
         <emphasis>Full Publish</emphasis>.
      </para>

      <para>
         But if you really want a fast edit/compile/test cycle, Seam supports
         incremental redeployment of JavaBean components. To make use of this
         functionality, you must deploy the JavaBean components into the
         <literal>WEB-INF/dev</literal> directory, so that they will be loaded 
         by a special Seam classloader, instead of by the WAR or EAR 
         classloader.
      </para>

      <para>You need to be aware of the following limitations:</para>

      <itemizedlist>
         <listitem>
            <para>
               the components must be JavaBean components, they cannot be EJB3
               beans (we are working on fixing this limitation)
            </para>
         </listitem>

         <listitem>
            <para>
               entities can never be hot-deloyed
            </para>
         </listitem>

         <listitem>
            <para>
               components deployed via <literal>components.xml</literal> may not
               be hot-deployed
            </para>
         </listitem>

         <listitem>
            <para>
               the hot-deployable components will not be visible to any classes
               deployed outside of <literal>WEB-INF/dev</literal>
            </para>
         </listitem>

         <listitem>
            <para>
               Seam debug mode must be enabled and 
               <literal>jboss-seam-debug.jar</literal> must be in
               <literal>WEB-INF/lib</literal>
            </para>
         </listitem>

         <listitem>
            <para>
               You must have the Seam filter installed in web.xml
            </para>
         </listitem>

         <listitem>
            <para>
               You may see errors if the system is placed under any load and
               debug is enabled.
            </para>
         </listitem>

      </itemizedlist>

      <para>
         If you create a WAR project using JBoss Tools, incremental hot deployment
         is available out of the box for classes in the 
         <literal>src/action</literal> source directory. However, JBoss Tools 
         does not support incremental hot deployment for EAR projects.
      </para>
   </section>      

</chapter>
