How to Create a Simple Seam Project in Eclipse
The goal of this little Howto is to setup an example Seam project within Eclipse. You will see which files you need to grab from the Seam examples and which modifications you need to do. You'll see how to set up packaging in Eclipse to be finally able to deploy your application on the JBoss Application Server.
Our example project will be the booking example which comes with Seam. Although this isn't the most trivial application, we have the advantage of a fully configured application with uses Seam in combination with JSF navigation and facelets.
A word in advance: Why another Howto?
You may have noticed there are other Howtos dealing with more or less the same subject. However, at the time writing (Jun, 30 2006) there are only descriptions available how to setup eclipse projects using embedded ejb3. If you don't use embedded ejb and want to deploy your application on a JBoss application server, you are able to reduce the configuration complexity and should be able to gain more overview. In this Howto we will follow this idea and we will get rid of quite a few library and configuration files we don't need. This way you should end up with an Eclipse project which just contains what is needed to study the example and it's configuration - and it can be used as a template for your own project.
Make sure to have the newest software releases
At the time writing, you need to have to latest version of Seam and ejb3, there are issues with older versions. Right now you need to make sure that you are using:
a Java 5.0 (or higher) JDK, Java 1.4 won't do any more.
you need the latest version of JBoss AS! The key issue seems to be ejb3.
At the time writing the easiest way to avoid problems is to do a fresh installation the JBoss apllication server with the Jems installer 1.2.0.BETA or higher. Start the installation with java -jar jems-installer-1.2.0.BETA.jar, then choose the ejb3 profile.
In case you installed the JBoss Application Server 4.0.4.GA (4.0.4.GA this is the latest version at the time writing) without using the Jems installer, you will most likely have to update ejb3. You will need at least release EJB3-RC8. In directory /jboss-install-dir/server/default/deploy/ejb3.deployer you need to update the files jboss-ejb3.jar, jboss-ejb3x.jar, and jboss-annotations-ejb3.jar.
Remark: It's just a question of time until a newer version of JBoss AS will come with a proper ejb3 version. Don't worry about ejb3 if you already got a newer version than JBoss AS 4.0.0 GA.
at least Seam 1.0.1 GA. Install it into whatever directory it is convenient for you. For simplicity we will later call this installalation directory /seam-inst.
Set up your Eclipse project
For this project we will use the booking application from the Seam examples. Although this is not the most trivial project, it has the advantage that Seam, Facelets and JSF navigation is used and can be studied and modified.
in Eclipse create a new "EJB 3.0 project" and name it seam-booking.
get the libraries we need (NOTE: If you're going to develop multiple Seam-based projects, you migth want to create "User libraries" for Seam, MyFaces, Facelets and jBPM; to create user libraries in Eclipse just go to Window -> Preferences -> Java -> Build Path -> User Libraries. Once you create these libraries, you can add them easily to your project; this way, you won't have to create a "lib" structure as indicated below).
create new folders lib/seam, lib/facelets, and lib/ext in seam-booking.
copy jboss-seam.jar, jboss-seam-debug.jar, and jboss-seam-ui.jar from your seam installation directory /seam-inst to the lib/seam folder.
In Eclipse highlight seam-booking then choose menu file > Properties > Java Build Path > Libraries. "Add Jars..." now and choose one of the libs you just copied to lib/seam. You need to repeat this for all 3 jar files you just copied.
copy jsf-facelets.jar, el-api.jar, and el-ri.jar from /seam-inst/facelets/lib to the lib/facelets folder.
Add these jar files to your Java Build Path as you did before.
we also need to have the JSF library in our build path. JBoss AS comes with the Apache MyFaces implementation. I suggest to add that library to your classpath, which is also used by the application server. If JBoss AS runs on the same machine, just edit the Properties of your project again, choose Java Build Path > Libraries and "Add External JARs...". Then find jboss-install-dir/server/default/deploy/jbossweb-tomcat55.sar/jsf-files/myfaces-api.jar and press OK.
at this point you got all seam and jsf/facelets lib files you need. However, Seam needs a few more libraries to run. Copy jbpm-3.1.1.jar and thirdparty-all.jar to the lib/ext folder. You will have 2 choices now
copy jbpm-3.1.1.jar and thirdparty-all.jar into the deploy directory of the JBoss application server (for instance /jboss-install-dir/server/default/deploy) and you are done.
alternatively you can later package these files in your ear file and deploy it together with you application. This is quite straightforward, but to keep things as simple as possible, this won't be described in this Howto. So don't forget to do this if you don't want to copy the 2 files as described above!
it's not neccessary to include the jar files in lib/ext into your classpath unless you later use them yourself in your project.
copy the source tree from /seam/examples/booking/src to your src folder. You will notice that Eclipse shows errors in subdirectory org/jboss/seam/example/booking/test. Don't worry about that now. If you are interested, take a look here for a little description what remains to be done to get TestNG running. But first keep on going to set up this project.
create a folder named view and import or copy all files from /seam-inst/examples/booking/view.
create resources/META-INF and resources/WEB-INF folders and get the following files from /seam-inst/examples/booking/resources. (Here is a quick overview what these files are good for)
/seam-inst/examples/booking/resources/META-INF/application.xml -> resources/META-INF
/seam-inst/examples/booking/resources/META-INF/ejb-jar.xml -> resources/META-INF
/seam-inst/examples/booking/resources/META-INF/jboss-app.xml -> resources/META-INF
/seam-inst/examples/booking/resources/META-INF/persistence.xml -> resources/META-INF
/seam-inst/examples/booking/resources/WEB-INF/faces.config.xml -> resources/WEB-INF
/seam-inst/examples/booking/resources/WEB-INF/pages.xml -> resources/WEB-INF
/seam-inst/examples/booking/resources/WEB-INF/web.xml -> resources/WEB-INF
/seam-inst/examples/booking/resources/booking-ds.xml -> resources
/seam-inst/examples/booking/resources/import.sql -> resources
/seam-inst/examples/booking/resources/components.properties -> resources
/seam-inst/examples/booking/resources/seam.properties -> resources (or create an empty seam.properties file in resources)
load the attached components.xml and put it into the resources/WEB-INF folder.
There is one very important point you should to know about this file. If you take take a look at line
jndiPattern jboss-seam-booking/#{ejbName}/local, you will probably be kind of surprised. The preceding jboss-seam-booking/ is the name of the ear file you are deploying (jboss-seam-booking.ear in our case). Unfortunately we have to provide this information if we don't use embedded ejb. So don't forget to change this whenever you change the name of the ear file. Currently: you must change property myFacesLifecycleBug to true
load the attached jndi.properties and place it in the resources folder. This is the standard jndi.properties file as usually used in the JBoss AS. If you have a special JNDI configuration, just take your own jndi.properties. The file which comes with the Seam examples can't be used in our case. That one is for embedded ejb, which uses a different JNDI implementation.
Eclipse packaging Configuration
Now we are ready to setup packaging in Eclipse. Right click on the seam-booking project, choose Properties and Packaging Configurations. "Enable Packaging" and "Add..." Name: jboss-seam-booking.jar. Then
right click on jboss-seam-booking.jar and "Add Folder...". Choose "Project Folder..." and bin in your seam-booking project, finally OK.
right click jboss-seam-booking.jar again and "Add File...". Choose "Project File..." and resources/META-INF/ejb-jar.xml. Set Prefix to META-INF.
in the same way add resources/META-INF/persistence.xml to jboss-seam-booking.jar. Prefix is META-INF again.
also and resources/booking-ds.xml, no prefix
and resources/import.sql, no prefix.
resources/jndi.properties, no prefix.
resources/seam.properties, no prefix. Although this is an empty file, Seam won't run without it. Actually it needs to be in the root of every archive containing Seam components since Seam won't look for Seam components if it doesn't find seam.properties.
In the right side bar of Packaging Configurations choose "Add..." again and create jboss-seam-booking.war. Now
right click on jboss-seam-booking.war, then "Add File..." > "Project File...". Choose lib/seam/jboss-seam-ui.jar, prefix WEB-INF/lib
also add lib/seam/jboss-seam-debug.jar, prefix WEB-INF/lib
lib/facelets/jsf-facelets.jar, prefix WEB-INF/lib
lib/facelets/el-api.jar, prefix WEB-INF/lib
lib/facelets/el-ri.jar, prefix WEB-INF/lib
resources/WEB-INF/components.xml, prefix WEB-INF (not WEB-INF/lib!)
resources/WEB-INF/faces-config.xml, prefix WEB-INF
resources/WEB-INF/pages.xml, prefix WEB-INF
resources/WEB-INF/web.xml, prefix WEB-INF
finally add the view folder to jboss-seam-booking.war, no prefix.
We will also need jboss-seam-booking.ear, so in the right side bar of Packaging Configurations choose "Add..." again and create jboss-seam-booking.ear. Then
right click on jboss-seam-booking.ear, then "Add File..." > "Project File...". Choose resources/META-INF/application.xml, prefix META-INF
also add resources/META-INF/jboss-app.xml, prefix META-INF
lib/seam/jboss-seam.jar, no prefix
also add jboss-seam-booking.jar, no prefix. Since this file doesn't exist yet, you need to type in the name in the "Select A File" Dialog (where you previously clicked on the file you wanted to add). Below there is a text field in which you should enter /seam-booking/jboss-seam-booking.jar.
in the same way add jboss-seam-booking.war, no prefix again
And finally...
Run Packaging (right click on the seam-booking project, then "Run Packaging"), deploy jboss-seam-booking.ear (right click on jboss-seam-booking.ear, then "Deployment" > "Deploy To..." > ... ) and the example application should deploy if the JBoss application server is running already. Open a browser window and type "http://localhost:8080/seam-booking" and see it running...
Reminder:
Take a look here if you like to set up TestNG now.
Comments