Appendix A. Seam starter set

This appendix explores the set of libraries and tools you need to develop with Seam. Seam consists of just a handful of JAR files, listed in section A.2.1. Once these libraries are added to your application’s classpath, they open the door to a wealth of integrations and a consistent programming model. To get started with Seam, you can create a new project using seam-gen (see chapter 2), adopt an example application from the Seam distribution, or add the Seam libraries to an existing project by mining the JAR files from the Seam distribution or registering the Seam modules as Maven 2 or Ivy dependencies.

Given that Seam is often described as an “integration framework,” you’d expect it to rely on a wide variety of external libraries. While that’s true, it’s nothing to get worried about. Both the Seam distribution and the Maven 2 configuration provided by Seam include compatible libraries that are verified to work with a given Seam version. Thus, Seam truly lives up to its title as an integration framework, both at the API and distribution levels.

Before swinging away, you need to check the prerequisites for using Seam and the seam-gen tool, which extend beyond just extracting the Seam distribution on your hard drive.

A.1. Stepping through the prerequisites

Chapter 2 makes the recommendation of using seam-gen as your first step into Seam. Thus, the prerequisites presented in this section are geared toward using seam-gen to create and deploy the database-oriented application that accompanies this book. Let’s have a look at what software is needed to follow along with the tutorial in chapter 2:

• Java SE (JDK) (5.0 or greater) from Sun, IBM, BEA, Apple, or RedHat (IcedTea)
• JBoss Application Server (4.2 or greater)
• JBoss Seam (2.0 or greater)
• A database and JDBC driver (the book source code uses the H2 database)
• Seam in Action source code (needed for the database schema and seed data)

While you can get by using the seam-gen tool with the software listed here, you may find the following optional dependencies valuable as well:

• Apache Ant (1.7.0 or greater)
• Alternate application server (GlassFish Application Server V2 or greater)

I’ll step through each of these prerequisites in turn. Any time you see a reference to /home/twoputt, replace it with the location of your software development directory. The folders under this directory referenced in this appendix are consistent with the book’s source code and are described further in the introduction. Don’t get too worked up over the JBoss AS requirement. It just happens to be the application server supported by seam-gen out of the box. Any Java EE application server can stand in its place. Java 5 is required, which hopefully will not turn you off Seam if you’re still using Java 1.4 or lower. I begin with the reasoning behind the Java 5 requirement.

A.1.1. Java 5 compliance

A Java 5–compliant JDK (Java SE Development Kit) is required to develop Seam applications, and the applications must be run under a Java 5–compliant JVM (Java virtual machine). It’s also strongly recommended that applications be deployed to a Java EE 5–compliant application server. This recommendation becomes a requirement if you want to take advantage of Seam’s EJB 3 integration.

The dependency on Java SE 5 and Java EE 5 accounts for a large part of Seam’s success and works to your advantage. Instead of having to tiptoe around the enhancements that came with the release of Java 5, as some other frameworks do, Seam embraces annotations and generics to eliminate unnecessary XML configuration and ugly casting. Seam is sending the message to the industry that it’s time to move on. The productivity gains afforded by using a Java 5–compliant language are too valuable to put off any longer. Although it may be possible to use a tool like Retrotranslator^[1] to port a Seam application to a J2SE 1.4 JVM, it still doesn’t eliminate the requirement of using a Java 5–compliant JDK for development, nor does it get you any closer to using EJB 3.

¹ Retrotranslator (http://retrotranslator.sourceforge.net/) is a Java bytecode transformer that translates Java classes compiled with JDK 5.0 into classes that can be run on JVM 1.4.

If you haven’t yet moved to JDK 5 (or better), you’ll need to download it from the vendor of your choice. I recommend using Sun’s JDK 6 since, in my gut-feeling tests, it’s the fastest JVM for development. Once you’ve downloaded the Java distribution, you need to add the java binary to your PATH environment variable. It’s also good practice to set the JAVA_HOME environment variable to point to the extracted Java distribution, as some tools rely on it. Here are the shell commands (for Linux and Mac OS X) for setting these variables:

  export JAVA_HOME=/home/twoputt/opt/jdk1.6.0_03
  export PATH=$JAVA_HOME/bin:$PATH

If you’re using Debian/Ubuntu Linux, it’s even easier. You simply type sudo apt-get install sun-java6-jdk and the Sun Java distribution is downloaded from the multiverse apt repository and configured for you. This channel is available since Java has finally been released under a distributable license.^[2] Other Linux distributions offer similar packages. Mac OS X 10.5 (Leopard) is distributed with Java 5 and it’s already available in the default PATH. If you’re on Windows, I strongly recommend using Cygwin or a VMWare image of Linux.

² For information on the announcement regarding the release of the full Java stack on Debian/Ubuntu, see http://www.linuxplanet.com/linuxplanet/newss/6380/1/.

Your next stop is the JBoss labs, where you’ll pick up the JBoss Application Server (JBoss AS). Following that, I discuss two alternate servers: GlassFish and Tomcat.

A.1.2. Java EE 5 application servers

Seam is designed to make the standard Java EE 5 services more accessible, not to reinvent them. Throughout this book, I emphasize why deploying to a Java EE 5 application server is a “Good Thing.” You may be inclined to assume that Tomcat, JBoss AS without EJB 3, and integration tests are left out in the cold. This is not the case. Seam applications just fit more naturally in a Java EE 5 environment. Rest assured that the Embedded JBoss runtime can be added to the classpath of a non–Java EE environment to “enlighten” it with Java EE 5 capabilities. It’s also possible to configure a Seam application to run in a Java SE environment, independent of any Java EE 5 features. For instance, you can use resource-local transactions and an application-managed persistence manager as alternatives. But to get going quickly, you’ll find that using JBoss AS is the most convenient option.

JBoss Application Server

You can download the JBoss Application Server (AS) from its project page in the JBoss labs: http://labs.jboss.org/jbossas. You’ll be directed to the SourceForge.net site, where you can download the zip file. The recommended version of JBoss AS to use with Seam 2.0.x is 4.2.2.GA.^[3] After the download completes, extract the archive into the opt folder in your home directory. The location of the extracted archive is referenced as the placeholder ${jboss.home} in chapter 2. Chapter 2 also provides instructions on how to start JBoss AS. Recall that you must run the application server using a Java 5–compliant JVM. If you plan on accessing the server from another computer, you need to add the -b 0.0.0.0 argument to the run command. This tells the server to accept connections from all IP addresses. The default is to only allow local connections.

³ The versions used by JBoss may seem confusing at first glance, many ending in “GA.” This abbreviation stands for General Availability, a fancy way of saying that it is the final release. A product is labeled as GA when all the outstanding bugs have been resolved in the candidate release version that preceded it.

The 4.2.x series of JBoss AS is a partial implementation of Java EE 5, with support for EJB 3, allowing you to take advantage of all of Seam’s features. I encourage you to move to JBoss AS 5 when it’s finalized to get all the Java EE 5 features. The benefit of using a Java EE 5 environment is discussed in the remainder of this section.

 

 

Alternate application servers

If you’re developing an off-the-shelf application, it’s important to test it on alternate application servers to ensure portability. Covering the interoperability of Seam applications among different application servers here would duplicate the focused effort done by the Seam development team and logged in the Seam reference documentation. Although theoretically Seam can run on any Java EE application server, the officially tested platforms are JBoss AS 4.2, IBM WebSphere 6.1, WebLogic 10, GlassFish version 2, Oracle OC4J 11g, and Tomcat 5 and 6. I want to contrast two of the options, GlassFish and Tomcat, to help you put the choice of where to deploy a Seam application in perspective.

GlassFish

One of the application servers to which I am partial is GlassFish,^[4] the open source Java EE 5–compliant server sponsored by Sun Microsystems. It’s the reference implementation for Java EE–compliant servers and passes the Java EE 5 Technology Compatibility Kit (TCK) 100 percent, unlike JBoss 4.2. It also sports an attractive and intuitive administration console, making it user-friendly and easy to adopt.

⁴ You can download GlassFish from the GlassFish Community site: https://glassfish.dev.java.net/. Look for the direct download links on the right side of the page. The recommended version of GlassFish is V2 or greater.

I put strong emphasis on the word compliant in the last paragraph. What’s so great about compliance? It’s about the rule of least surprise. If every application server had its own set of guidelines, then moving your application from one server to another would require a lot of reconfiguring in the best-case scenario. If the services provided by a server behave differently or don’t line up, the changes might even be more drastic, perhaps requiring you to modify your code. Any work spent making such changes provides zero value to your application and is pure overhead from a monetary standpoint, definitely something you want to avoid. That brings us to Tomcat, which is many miles from being compliant.

Tomcat

Once upon a time, the industry flocked to Tomcat while fleeing a bad relationship with J2EE application servers. Developers wrote them off because they were expensive, slow, and heavyweight, and led to vendor lock-in. Tomcat represented the grassroots movement and let developers feel more free. Today, Tomcat is the most widely used “application server.”^[5]

⁵http://www.infoq.com/news/2007/12/tomcat-favorite-container

The main problem with Tomcat is that it isn’t a Java EE–compliant application server—it’s a servlet container. Although it made sense to cut corners at the time when J2EE servers had grown fat and expensive, times have changed. The Java EE 5 application servers have escaped their legacy and are now fast and cheap (GlassFish, for instance, is open source and starts in under a second). Furthermore, application servers adhere to a stack of successful and progressive specifications and offer all the services that you need to support transactional applications right out of the box. In my opinion, Java EE application servers offer a much better development experience than a servlet container like Tomcat.

You can even argue that Tomcat is now the culprit of vendor lock-in. It requires you to bend your application over backward to get it to work in this nonstandard environment, whereas all other application servers can theoretically share applications with little effort. That’s why the preferred solution for deploying an application that uses EJB 3 or JTA to Tomcat is to make Tomcat act like a Java EE 5 application server rather than forcing the application to fit Tomcat’s expectations. In this scenario, Seam 2.0 relies on Embedded JBoss to be configured directly in the Tomcat container (a change from packaging the Embedded EJB 3 runtime in the application, the strategy used in Seam 1.2). You can find instructions for setting up Embedded JBoss on Tomcat in the Seam reference documentation.

It’s certainly possible to deploy Seam applications to a vanilla Tomcat installation. However, you have to either change the application so that it doesn’t rely on container-provided services such as JCA and JTA, or you need to register these services using Tomcat’s proprietary configuration descriptors. Either way, EJB 3 gets tossed out the window. Are you starting to see why I claim that servlet containers are more proprietary, and more of a hassle, than a Java EE–complaint application server? My advice is to rethink why you are considering Tomcat.

A.1.3. Absent (JavaServer) Faces

As you know, Seam uses JavaServer Faces (JSF) as the preferred user interface (UI) framework. Thus, you may be wondering why JSF isn’t listed as a dependency. Once again, Seam applications are intended to be deployed to a Java EE 5–compliant application server and since JSF 1.2 is a part of Java EE 5, it’s already available. If you aren’t using a standard Java EE 5 environment, you need to download JSF and package it with your application. You should grab a JSF 1.2–compliant implementation, which is required by Seam’s JSF support.

Seam developers recommend the Sun implementation of JSF (Mojarra) over Apache MyFaces. The reason for this preference is that Sun’s implementation has succeeded in keeping up with the latest JSF specification and because it too is an open source project. Both JBoss AS and GlassFish now bundle the Sun implementation in their respective application servers. Despite this move, I’m sure this is not the last we’ll hear of this debate.

With your deployment environment ready, it’s finally time to grab Seam and the example source code so that you are ready to go through the tutorial in chapter 2.

A.2. Downloading the Seam distribution

You can download the latest version of the Seam 2.0 distribution from the Seam project page in the JBoss labs: http://labs.jboss.org/jbossseam. Feel free to upgrade as new versions become available, but know that this book’s source code is developed for Seam 2.0.3.GA. Extract the Seam distribution archive into the opt folder in your home directory. The location of the extracted archive is referred to as the Seam distribution directory throughout this book.

 

 

A.2.1. Seam’s modules

Seam 2.0 consists of seven JAR files, each representing one Seam module. Table A.1 lists the artifact ID of each module and its purpose. The JAR files, whose names are derived by appending .jar to the artifact ID, are found in the lib folder of the Seam distribution.

Table A.1. A listing of Seam’s modules and their purposes

Artifact ID	Purpose
jboss-seam	Provides the Seam container, Seam annotations, bijection, extended JSF life cycle, CRUD framework, security, jBPM integration, Drools integration, web services, page flows, asynchronous support, conversations, extended EL, managed transactions and persistence, and the integration test framework
jboss-seam-remoting	Supports invoking Seam components using Ajax requests and allows JavaScript to listen for messages on JMS queues and topics
jboss-seam-ui	Includes the Seam JSF components, file upload capability, graphics generation, Facelet integration, and conversation controls
jboss-seam-debug	Activates the hot deployment classloader and provides a Seam debug page and developer-oriented error page
jboss-seam-ioc	Provides integration with Spring and other IoC containers
jboss-seam-pdf	Has support for generating PDF files using Facelet templates and a document storage mechanism for pushing binary files
jboss-seam-mail	Provides email integration and supports creating emails from Facelet templates

Take note that the presence of the Seam debug module on the classpath activates hot deployment of components and the Seam development pages. I recommend that you remove this module from the classpath when deploying to production.

A.2.2. A wealth of documentation and examples

Second to this book (sorry, I’m biased), the best resource you have for using Seam is the Seam reference documentation, which weighs in at 500-plus pages. We always want documentation to be better, but my feeling is that the Seam developers have done a great job of documenting Seam, especially in the area of application server interoperability. In fact, there are several places in this book where I point you to the reference documentation because, for certain topics, it will always provide the most updated information.

The reference documentation can be found in both HTML and PDF format on the Seam project page. To ensure that you always have the resources you need, keep the PDF of the Seam documentation and the eBook of Seam in Action on your hard drive at all times. If you’ve exhausted these resources and are still looking for more information, consult the Seam in Action link feed, http://del.icio.us/seaminaction.

The Seam distribution includes a plethora of example applications. Although this book has its own example application, the examples in the Seam distribution give you additional exposure to how Seam is used. They also exercise many different deployment environments. To deploy an example, you must specify the location of the target application server in the build.properties file at the root of the Seam distribution using either the jboss.home or tomcat.home property. I encourage you to explore the example applications early on because they’ll give you context when you read about the features of Seam in this book.

A.2.3. Finding seam-gen amid the noise

The seam-gen tool is easily lost within the busy root folder of the Seam distribution. The tool consists of two parts: the seam-gen script and the template folder. Unless you’re planning to customize seam-gen, you’re likely only interested in the seam-gen script. On Unix (or Cygwin), the script is named seam, and on Windows it’s named seam.bat.

To use seam-gen, you must navigate to the root of the Seam distribution directory. Before you can run the seam-gen script on Unix, you have to make it executable. To do that, execute chmod 755 seam (or chmod +x seam). When you run the seam script in Unix, you always prefix the shell command with a dot followed by a forward slash, ./seam, to let the shell know that the script is in the current directory. To run the script on Windows, you simply type seam. Following the script name, you enter the seam-gen command to execute.

You are now ready to begin using seam-gen. The next section covers a couple more resources that are useful for running the example application in this book.

A.3. seam-gen and the Open 18 example application

The example application used in this book is titled Open 18. It’s a golf directory and community site. It begins its life as a seam-gen CRUD application and is customized throughout the book. Several additional applications are also provided.

A.3.1. The source code

This book’s source code can be downloaded or checked out from the SVN repository of the Google Code project: http://code.google.com/p/seaminaction. The source code is organized in stages so that you can pick up with the application anywhere in the book by using the result from the previous chapter. However, you should also be able to get there without using the source code. You can find more information on the project page about how the source code is organized and how to build the staged projects. You can also find instructions on how to modify a seam-gen project so that it can be deployed to GlassFish.

Chapter 2 walks you through creating the initial application by reverse-engineering an H2 database, which you’ll need to set up to follow along with the tutorial. Instructions for building the database are provided in the download. Note that all of the example applications for the book use the H2 database for persistent storage.

A.3.2. H2 database

The seam-gen tool specializes in setting up database-oriented applications. Thus, in chapter 2, you feed it an H2 database to get started. H2 is a SQL database written entirely in Java. It’s much faster than other low-end databases for reasons cited on the H2 project website. H2 is the successor of the HSQL Database Engine (HSQLDB), both developed by Thomas Mueller.

The example application leverages H2’s embedded mode, which allows the database to be bootstrapped directly from the file system. One major limitation of using embedded mode is that the database files can only be accessed by one JVM at a time. To avoid locking errors, you may want to consider using client-server mode, which allows several processes to connect to it over TCP/IP (or SSL/TLS over TCP/IP for improved security). Another option to circumvent locking problems is to add the flag FILE_LOCK=no to the JDBC URL, which disables H2’s file locking. Beware that if you disable locking, you risk corruption of the database if writes occur from more than one client. For more information about client-server mode and the H2 database in general, visit the H2 project website: http://h2database.com.

The H2 JAR file is bundled with the source code. You can also download it from the H2 project website. The tutorial in chapter 2 assumes that it resides in the lib folder in your home directory. seam-gen takes it from there and installs it into the JBoss AS domain.

A.3.3. Apache Ant, turning the wheels of seam-gen

As chapter 2 explains, the workhorse behind seam-gen is Apache Ant. While you don’t need Ant to run seam-gen, you need Ant to execute the build in a project that seam-gen creates.

You can download Ant from the Apache Ant project site: http://ant.apache.org. The recommended version is 1.7.0. Extract the Ant distribution into the opt folder in your home directory. You’ll also need to add the ant binary to your PATH environment variable:

  export PATH=/home/twoputt/opt/apache-ant-1.7.0/bin:$PATH

Once again, if you’re using Debian/Ubuntu Linux, you can simply type sudo apt-get install ant to have Ant installed and configured for you automatically. Mac OS X 10.5 (Leopard) is distributed with Ant 1.7 and it’s already available in the default PATH.

A.3.4. RichFaces or ICEfaces—take your pick

The seam-gen tool offers a choice of using either RichFaces or ICEfaces to build the user interface. Both libraries, covered in depth in chapter 12, are extensions to JSF that provide Ajax-based interactivity, an elegant look and feel, and rich UI components. By using either one, you eliminate a lot of custom CSS, graphics, and JavaScript that would otherwise have to be developed and maintained as part of your application. This abstraction and shift of responsibility is the whole value proposition of JSF components.

So how do you configure one or the other? That’s the good news. If you use seam-gen to create your project, you just need to answer “y” or “n” in response to the question “Do you want to use ICEfaces instead of RichFaces?” when you run seam setup. The appropriate JAR files and configurations are then used. If you’re using ICEfaces, you can optionally provide a local directory as an override.

A.4. Managing libraries in a seam-gen project

Both the structure and build of a seam-gen project are rather eclectic. On the one hand, this is justifiable because it’s optimized for the most efficient turnaround during development. On the other hand, it’s atypical build requires some explanation of how libraries are managed.

In a seam-gen project, libraries are stored in the lib folder at the root of the project. All libraries in this folder are included on the compile classpath. Which libraries are selected to be packaged with the deployment archive is controlled by the deployed-jars.list file at the root of WAR projects (split up as deployed-jars-war.list and deployed-jars-ear.list files in EAR projects). Each entry in this file, one per line, corresponds to the name of a JAR file in the lib folder to be packaged. You can use an asterisk character (*) for wildcard matching.

To add a new JAR file to the project, you first add it to the lib folder. To have it packaged, you append it to the deployed JARs file. That still leaves the IDEs in the dark. You need to point the IDE at the JAR file and tell it to add the JAR to the classpath. In Eclipse, right-click on the JAR file in the Project Navigator and select Build Path > Add to Build Path. In NetBeans, select Project Properties and add the library to each classpath in the Java Source Classpath panel (NetBeans differentiates between src/model, src/action, and src/test).

If this configuration isn’t appealing, you can add Seam to a standard Maven 2 project.

A.5. Adding Seam as a Maven 2 dependency

If you’re only interested in the bare minimum of what you need to use Seam, or you want to add Seam to an existing build, pulling the artifacts from the JBoss Maven 2 repository is your best bet. But using the Maven 2 artifacts doesn’t mean you have to use Maven 2 as the build tool. Other tools, such as Ant, can also take advantage of the artifacts in the Maven 2 repository. You can point Ant at the Maven 2 repository using either the Maven 2 Ant tasks or Ivy. This section introduces the Seam artifacts in the JBoss Maven 2 repository by showing you how to add them to a Maven 2 build.

A Maven 2 dependency follows the convention groupId:artifactId:version. The Seam artifacts are classified under the org.jboss.seam group ID. The artifact IDs were listed in table A.1. If you always want to use the recommended library versions with Seam, declare the Seam root artifact as the parent in your project’s pom.xml as follows:

  <parent>
    <groupId>org.jboss.seam</groupId>
    <artifactId>root</artifactId>
    <version>2.0.3.GA</version>
  </parent>

Using the Seam root Maven 2 POM precludes the need to declare the JBoss repository or any versions of Seam artifacts and their respective transitive dependencies in your pom.xml. The only version that must be specified is the one in the <parent> stanza to indicate which version of Seam you want to use (adjust the version as needed). Once the parent POM is configured, you can add a Seam module inside the <dependencies> node as follows:

  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jboss-seam</artifactId>
  </dependency>

You can also add other artifacts declared in the parent dependency management without specifying versions. For instance, if you want to add the Drools libraries (which are marked as optional dependencies), use these declarations:

   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-core</artifactId>
   </dependency>
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-compiler</artifactId>
   </dependency>

Since Seam is designed to work with a Java EE 5 environment, any artifact that’s provided by a Java EE 5–compliant application server is marked as provided. Provided artifacts include the Servlet API, JSF, and the unified EL. If you need these to be included in the archive, you can declare them as compile-time dependencies. Here, JSF is included:

  <dependency>
    <groupId>javax.faces</groupId>
    <artifactId>jsf-api</artifactId>
    <scope>compile</scope>
  </dependency>
  <dependency>
    <groupId>javax.faces</groupId>
    <artifactId>jsf-impl</artifactId>
    <scope>compile</scope>
  </dependency>

As is typical with Maven 2 builds, you’ll likely need to spend time getting all the dependencies configured just right (though the root POM helps out a lot). Consult the resources regarding the use of Maven 2 with Seam listed in the Seam in Action link feed mentioned earlier. If you’re interested in exactly which libraries are required for each Seam module or integration, consult the last chapter of the Seam reference documentation.