Getting started with Seam, using JBoss Tools

Getting started with Seam, using JBoss Tools

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.

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

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.

3.1. Before you start

Make sure you have JDK 5, JBoss AS 4.2, Eclipse 3.3, the JBoss Tools plugins (at least Seam Tools, the Visual Page Editor, jBPM Tools and JBoss AS Tools) and the TestNG plugin for Eclipse correctly installed before starting.

TODO - detail where the update sites are.

3.2. Setting up a new Seam project

Start up Eclipse and select the Seam perspective.

Go to File -> New -> Seam Web Project.

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

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:

Enter a name for the runtime, and locate it on your hard drive:

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:

On the next screen give the server a name, and hit Finish:

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

The next 3 screens allow you to further customize your new project, but for us the defaults are fine. So just hit <empahsis>Next</empahsis> until you reach the final screen.

The first step here is to tell JBoss Tools about the Seam download you want to use. Add a new Seam Runtime - make sure to give it a name, and select 2.0 as the version:

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 EAR. Otherwise, choose WAR. 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.

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 MySQL as the database, and create a new connection profile. Select Generic JDBC Connection:

Give it a name:

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 ....

Locate MySQL 5, and hit Add...:

Choose the MySQL JDBC Driver template:

Locate the jar on your computer by choosing Edit Jar/Zip:

Review the username and password used to connect, and if correct, hit Ok.

Finally, choose the newly created driver:

If you are working with an existing data model, make sure you tell JBoss Tools that the tables already exist in the database.

Review the username and password used to connect, test the connection using the Test Connection button, and if it works, hit Finish:

Finally, review the package names for your generated beans, and if you are happy, click Finish:

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:

         -Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512
      

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

         -Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256
      

Locate the server in the JBoss Server View, right click on the server and select Edit Launch Configuration:

Then, alter the VM arguements:

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 OutOfMemoryException.

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

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.

3.3. Creating a new action

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.

First, select New -> Seam Action:

Now, enter the name of the Seam component. JBoss Tools selects sensible defaults for other fields:

Finally, hit Finish.

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

Finally, open the helloworld-test project, locate PingTest class, right click on it, and choose Run As -> TestNG Test:

3.4. Creating a form with an action

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

Now, enter the name of the Seam component. JBoss Tools selects sensible defaults for other fields:

Go to http://localhost:8080/helloworld/hello.seam. 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 src/action as Seam hot reloads the component for you Section 3.6, “Seam and incremental hot deployment with JBoss Tools”).

3.5. Generating an application from an existing database

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 New -> Seam Generate Entities:

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 Reverse engieneer from database.

Restart the deployment:

Then go to http://localhost:8080/helloworld. 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.

3.6. Seam and incremental hot deployment with JBoss Tools

JBoss Tools supports incremental hot deployment of:

• any facelets page

• any pages.xml file

out of the box.

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

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 WEB-INF/dev directory, so that they will be loaded by a special Seam classloader, instead of by the WAR or EAR classloader.

You need to be aware of the following limitations:

• the components must be JavaBean components, they cannot be EJB3 beans (we are working on fixing this limitation)

• entities can never be hot-deloyed

• components deployed via components.xml may not be hot-deployed

• the hot-deployable components will not be visible to any classes deployed outside of WEB-INF/dev

• Seam debug mode must be enabled and jboss-seam-debug.jar must be in WEB-INF/lib

• You must have the Seam filter installed in web.xml

• You may see errors if the system is placed under any load and debug is enabled.

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