Recently I’ve had need to begin developing a new application using Seam. However this time I’ve decided to go lightweight, so the obvious choice was Tomcat 6. I realized that the Seam plugin for NetBeans was limited to project generation for JBoss and so wasn’t an option. I decided to create everything on my own. Thankfully there is an example of the booking application with build scripts for Tomcat 6, Glassfish, WebLogic and WebSphere under jboss-seam-2.0.GA/examples/jpa. So here’s how you can set up yours work on Tomcat 6.
First, build the tomcat example by running ant tomcat6, which generates 2 folders – dist-tomcat6 and exploded-archives-tomcat6. With that done, create a library in NetBeans which you’ll add it to your project. I called mine “Seam4Tomcat” and added all the jar files in jpa/exploded-archives-tomcat6/jboss-seam-jpa.war/WEB-INF/lib.
Then create the project itself. Select the “Web Application” project type, specify Tomcat 6 as the target server and JavaEE 5 as the version of JavaEE. Next check Facelets as the framework to be used and create the project. Right click on the project and select “Properties”. Select “Libraries” on the left panel and “Add Library” to add your Seam4Tomcat (or whatever name you gave it) jars to your project. Remember to uncheck the Facelets related libraries provided by the NetBeans facelets support, since they are already in you newly added library.
Since the Seam filter needs to be installed to allow seam integration (as well as other configurations), just copy the contents of jpa/exploded-archives-tomcat6/jboss-seam-jpa.war/WEB-INF/web.xml and paste them in your web.xml file. You may change the <url-pattern> under the “Faces Servlet” servlet mapping to the url you want from the default “*.seam”.
Append this to the top of the web.xml file to add the blueSky RichFaces skin to RichFaces components you might use in the application.
Note that your faces-config.xml will already contain the reference to the Facelet view handler as well after creating the project.
Next, Seam gives you advanced navigation in its pages.xml file compared to JSF’s faces-config.xml file. To use it, just copy the jpa/exploded-archives-tomcat6/jboss-seam-jpa.war/WEB-INF/pages.xml into your WEB-INF folder. Also add the components.xml from the same directory to your WEB-INF folder. This is the most central file to any seam application and must always be there.
We’ll need to connect to some database to begin work with. So right-click your project, go to “New” and select “Entity Classes from Database”. We’ll assume no existing datasource and create one from an existing database connection. Drop down the “Data Source” combo box and select “New Data Source”. Enter a jndi name (mine is “jdbc/example”) and select the database connection. Enter the username and password for connecting to that database and your tables will be displayed.
Select the tables you want to generate entities for and click “Next”. You are then given the chance to edit the names of the Entities to be generated as well as specify the package within which they will be kept (mine is “example.entity”). NetBeans can generate named queries for you, but more importantly any JPA project needs a persistence unit. This consists of your entities and an ever so vital persistence.xml or orm.xml file.
Click the “Create Persistence Unit” button to create a persistence.xml file. Enter a persistence unit name (note the name you give. It will be used later). Specify your persistence provider – NetBeans comes with TopLink, but for Seam Hibernate is the better persistence provider. Note that I’ve changed the “Data Source” from “jdbc/example” to “java:comp/env/jdbc/example”. This is the fully qualified JNDI name that will be used by the container to resolve the EntityManager resource we’ll be injecting into our code. Since our database tables already exist, we’ll select “None” for “Table Generation Strategy” and click “OK”. We are finished with everything now and will click “Finish” to end the wizard.
The preceding process creates two very important files: context.xml and persistence.xml files. Every resource that would be used in Tomcat should be declared in context.xml as a resource. Here is mine from the process above. You are free to tweak yours as the need may be.
<Resource auth=”Container” driverClassName=”com.mysql.jdbc.Driver”
maxActive=”20″ maxIdle=”10″ maxWait=”-1″
name=”jdbc/example” password=”” type=”javax.sql.DataSource”
Here is my persistence.xml file as well. Note that I have changed the transaction-type to “RESOURCE_LOCAL” from “JTA”. However Seam provides JTA support for our application and therefore the <jta-data-source> declaration instead of <non-jta-data-source>. These must be exactly as it is here or your application will DEFINITELY give you errors.
<persistence-unit name=”exampleDatabase” transaction-type=”RESOURCE_LOCAL”>
Now go back to your components.xml file. If you did copy the one from the exploded jpa example, you should have the following declaration in this file.
First things first. Replace all instances of “bookingDatabase” with the name of your persistence unit (I told you to take note of that – mine is “exampleDatabase”). Secondly, by giving the name “em” to all references to EntityManager and managed persistence contexts, it means that your code can only inject the EntityManager under the same name like so
@In EntityManager em
If you use a different name to inject it don’t say I didn’t tell you about the errors you’ll be getting. Alternatively you could change it to “entityManager” or whatever, just make sure that you use the same name as declared in components.xml throughout your code.
The last but often most forgotten thing that needs to be added is a seam.properties file. I can recount the number of times I’ve had nightmarish debugging sessions when a fresh application I’d just created to display Seam to someone didn’t work because of this file. In NetBeans, just right-click the project, select “New” and the “Properties file”. Call it “seam” and do not put it in any package (which puts it in default).
With all this done, you are good to go developing for Tomcat 6 using Seam. NetBeans offers some level of incremental deployment to Tomcat, detecting if Java classes have changed and redeploying the application. However, since NetBeans remotely deploy web applications to Tomcat, Tomcat will be reading from your project folder directly to deploy the application. This means that some changes like changes made to your facelets page will immediately appear on your web-browser. Just save the changes you make to a facelet, refresh your web browser and boom! For me that is enough. Tomcat deploys quickly and so redeploying when a Java class changes is not that painful.
Here’s an application I created to display this process to a mate. It’s got all the configurations files, some entities and Seam components to get you started.