MyEclipse: getting started with SEAM

By: Jean-Michel Pargny
Revision: September 21, 2006
KARWELL SAS
Paris
pdf version

These notes describe the process for building and deploying a simple Seam application (seam registration) to the JBoss server using MyEclipse 5.0 GA.

You will need a compatible version of the server:

Seam requires the Java project compiler compatibility to be set for Java 5 or greater.

The Enterprise application

Overall projet configuration

The seam-registration example will be built as a standard MyEclipse Enterprise Application.

Step 1 – Create the Application

Create a new MyEclipse Enterprise Application J2EE 1.4 project named jboss-seam-registration.ear.

Step 2 – Add Seam

This is done simply by importing the jboss-seam.jar directly under the root of the ear project. This jar can be found under the root directory of the Seam distribution.

Since MyEclipse cannot be aware of this surreptitious addition, you need to add it to the application.xml descriptor manually. Alternatively, you can simply import a valid application.xml from the examples/registration/resources/META-INF directory of Seam into the META-INF directory of the project.

Also, to load Seam properly, JBoss needs an additional jboss-app.xml which you can create yourself or import together with application.xml.

Here is the final application.xml:

<application>
   <display-name>Seam Registration</display-name>
   <module>
      <web>
         <web-uri>jboss-seam-registration.war</web-uri>
         <context-root>/seam-registration</context-root>
      </web>
   </module>
   <module>
      <ejb>jboss-seam-registration.jar</ejb>
   </module>
   <module>
       <java>jboss-seam.jar</java>
   </module>
</application>

Here is the jboss-app.xml

<jboss-app>
   <loader-repository>
   seam.jboss.org:loader=seam-registration
   </loader-repository>
</jboss-app>

and here is the application as is appears in the Project Explorer at this stage:


fig.1 The initial Enterprise Application

The EJB module

One of the tricky parts consists in deciding which libraries are needed for each of the EJB and WEB modules. An easy solution would be to add en masse all jars found in the seam distribution to both. We will try to be a bit more discriminate.

Step 1 - add the libraries

This project is dependant on ejb3, Seam, Hibernate validators and the JSF API. Add the following jars: jboss-ejb3-all.jar, jboss-seam.jar, hibernate3-all.jar and myfaces-api-1.1.3.jar to your build path to satisfy this requirement. They can all be found under the root and lib directories of your seam distribution.

Step 2 – compile the source code

You can now create the java classes or copy them form the example/registration/src directory of the Seam distribution (we will omit the test sub-package for the time being). The project should compile without any error if you performed the previous step correctly.

Step 3 – fix the descriptors

Since we are using ejb3, MyEclipse can't be much help in this area yet. Fortunately, basic ejb3 descriptors tend to be quite simple. For the purpose of this exercise you can simply copy the ejb-jar.xml and persistence.xml files found under the example/registration/resources/MET-INF directory of the seam distribution directly into the src/META-INF directory of the project.

One gotcha is that Seam needs a seam.properties file in order to deploy properly, even if this file is empty (yes: this IS documented... somewhere). So, you need to create an empty seam.properties file (or, again, import one from your seam distribution). It should be located directly under the project src directory.

Here is the ejb-jar.xml

<ejb-jar>
   <assembly-descriptor>
      <interceptor-binding>
         <ejb-name>*</ejb-name>
         <interceptor-class>
             org.jboss.seam.ejb.SeamInterceptor
         </interceptor-class>
      </interceptor-binding>
   </assembly-descriptor>
</ejb-jar>

here is the persitence.xml:


<persistence>
   <persistence-unit name="userDatabase">
      <provider>org.hibernate.ejb.HibernatePersistence</provider>
      <jta-data-source>java:/DefaultDS</jta-data-source>
      <properties>
         <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      </properties>
   </persistence-unit>
</persistence>

and here is the final EJB module as is appears in the Project Explorer:


fig.2 – The ejb module


The Web module

Step 1 – add basic JSF capabilities



fig.3 adding JSF capabilities without libraries


We will setup this project with basic JSF capabilities. Our JBoss server comes with a MyFaces implementation already installed, so we will not deploy the libraries. The project does not use JSTL, so that library will not be required either.

Right click on the project, then: MyEclipse > add JSF capabilities, select the MyFaces 1.0.9 implementation and enter *.seam as the URL pattern. Since the libraries are only used for basic TLD validation, the choice of implementation is not really critical. Selecting MyFaces 1.0.9 will only produce a simpler version of web.xml, closer to what we actually need in the end. You can also opt to deselect the Install JSF Jars and Install JSF TLDs if you really want to work with a minimum set (see fig. 3). If you do so, you will need to re-add JSF validation manually (see below).


fig.4 JSF preferences


Next, click on the View and edit libraries option. In the new dialog that opens, uncheck both Copy JSF jars and Copy JSF TLDs options (see fig. 4), then apply, OK. This will avoid deployment of unnecessary JSF libraries or TLDs within the module.

If you opted not to install any JSF library (you unchecked the install JSF jars and install JSF TLDs options in the first dialog), MyEclipse will not be able validate JSF tags in your JSP pages, so you need to re-add this capability as an extra step. This can be done by adding the myfaces-impl-1.1.3.jar (for example) to your project build path. The file can be found in the lib directory of your Seam distribution.

Step 2– add the Seam tag library

Next, we need to add the Seam tag library. What we want to do here is the reverse of what we did for JSF: this library should be deployed in the WEB-INF/lib directory together with the application. In your Window > Preferences >MyEclipse > J2EE Project > Web Project:

You can now import the seam-ui.jar from the Seam distribution into the WEB-INF/lib directory of the project. In the explorer, the jar should appear directly under your project, indicating that it has been added to your build path (you can use the Ressources perspective to check that it is actually located in the lib directory).

Step 3 – fix the descriptors

Seam needs a component.xml descriptor under the WEB-INF directory in addition to the usual web.xml and faces-config.xml. You can import the last two directly form the Seam's examples/registration/resources/WEB-INF directory. The component.xml file, however, needs a bit more care: the copy found in the resource directory contains some Ant build variables, so you will need to adjust it manually. The final component.xml file that you want to deploy looks like this:

<components>

    <component name="org.jboss.seam.core.init">
        <property name="myFacesLifecycleBug">true</property>
        <property name="jndiPattern">
          jboss-seam-registration/#{ejbName}/local
        </property>
    </component>
    <component class="org.jboss.seam.core.Ejb" installed="false"/>

</components>

If you have already built the examples using Ant as explained in the Seam documentation, however, it is easier pick up the deployable version directly in your /registration/build/resources/WEB-INF directory.

You will notice that your faces-config.xml is in error since MyEclipse cannot find the SeamPhaseListener class. You can fix this by adding the jboss-seam.jar to your project build path (again).

Here is the faces-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config
PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
                       "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">

<faces-config>
   <!-- Phase listener needed for all Seam applications -->
   <lifecycle>
      <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
   </lifecycle>

</faces-config>

and here is the interesting part of web.xml

   <!-- Seam -->
   <listener>
       <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
   </listener>

   <!-- MyFaces -->
   <listener>
       <listener-class>
           org.apache.myfaces.webapp.StartupServletContextListener
       </listener-class>
   </listener>

Step 4 – import the pages

You can now import the HTML and JSP pages from the examples/registration/view of Seam into your WebRoot directory. This is the completed WEB module:


fig.5 – The web module


Both JSF and Seam tags are recognized, as expected. The user and register beans, though, are not. This is hardly surprising since these beans are managed by Seam and MyEclipse does not support Seam (yet).

A minor disappointment, though: you won't be able to fix the problem by putting your EJB project in the path of your WEB project and adding something like this to your faces-config.xml:

<referenced-bean>
   <referenced-bean-name>user</referenced-bean-name>
   <referenced-bean-class>
       org.jboss.seam.example.registration.User
   </referenced-bean-class>
</referenced-bean>

Apparently, support for the <referenced-bean> element was left out in the JSP editor.

Step 5

Voilà ! Deploy and enjoy.