Configuring a Seam EJB project for development with Maven and JBoss Tools

Maarten Winkels

Say you want to build a web application and you want to use Seam for integrating standard technologies like JSF and EJB. Furthermore, you want to use the power of Maven to build your project for different environments, on different systems (like you continuous build system) and use its' rich reporting features to get an overview of the code quality of your project. And of course you want to use a good IDE, like Eclipse with JBoss tools to aid you in development. How does one go about setting up all these things?

Maven - Project structure
module-dependenciesThe first thing to realize is how to setup the maven project structure for this project. To develop a Seam project that uses EJBs (and JSF), we need an ejb-archive and a web-archive. These should be combined in an ear-archive. For maven this means we need at least three projects, one for each artifact, and preferably one more to easily build the others.
The picture hows how these projects are related:

  1. The BLD (build) project is the parent project of all the other projects, that in turn are modules of the BLD project. The main purpose of this project is to provide a place for common configuration and a common build for all modules.
  2. The WAR project depends on the EJB project, because it will use some of the services.
  3. The EAR project depends on both the WAR and the EJB project, because these should be packaged in the ear.

Maven - Dependencies
Maven is all about dependencies. Luckily Seam libraries are available in the repositories, both the special repositories hosted by JBoss and the central repository. And there is more: Seam provides a very useful maven project, that can be used as the parent for our own project: org.jboss.seam:root. This project contains the JBoss repositories and a dependency management section that will ensure that compatible versions of all libraries are referenced. So the first step is to make our BLD project a child of the org.jboss.seam:root project.
Then we have to add the necessary dependencies for Seam.

  • The EJB project depends on org.jboss.seam:jboss-seam:ejb and on org.hibernate:hibernate-entitymanager, since we're gonig to use hibernate for persistence.
  • The WAR project depends on org.jboss.seam:jboss-seam-ui. Now depending on your preference of front end technology, other dependencies will need to e added, but we will come to that later.

The good thing is that since we're using the org.jboss.seam:root as parent, we don't need to specify versions, this is handled by dependency management.
The Maven structure and dependencies (and some more support files like web.xml and ejb-jar.xml) can be packaged in a Maven archetype. Attached to this blog, you can find the one we are building right now. It can also be found in Xebias Opensource Maven repository or the snapshot repository.

Eclipse
jboss-projectNow, after handling Maven, let's turn our attention to this Eclipse beast. We would like to have an easy path from the Maven project to the Eclipse development environment. Eventually we would like to have JBoss Tools running out-of-the-box starting from the simple Maven project. First let's take a look at a JBoss Tools Seam project.
The image on the left shows the outline of a Seam project as created by JBoss Tools. There are 4 projects: test (WAR), test-ejb, test-ear and test-test. The last contains the tests, which in a maven project will be part of the same project, so we will not discuss it further. The other three projects are WTP enabled projects. looking at the configuration files (.settings/org.eclipse.wst.common.component in each project), we find that it is using WTP version 1.5.
Now we'll try to build a similar configuration starting from the maven project.

Eclipse - WTP support
Maven has a maven-eclipse-plugin, that has as sole purpose to transform a maven project into a working eclipse project configuration. Unfortunately, it's WTP support is seriously broken. To configure the plugin, we use this XML snipped, taken from the official documentation.

    
      
        maven-eclipse-plugin
        
          true
          true
          true
          1.5
          ${basedir}/src/main/resources/META-INF/MANIFEST.MF
        
      
    

This snipped should be placed in the pom.xml of the BLD project, so it is applied to all projects.

Now, running the eclipse:eclipse maven goal on the BLD project will generate the eclipse configuration (.project, .classpath and WTP files) for all projects. The version of the JEE specifications will be inferred by the maven-eclipse-plugin by looking at the maven dependencies for the respective specifications. To make sure the plugin generates the correct WTP configuration, we need to add the javax.ejb:ejb-api:3.0 dependency to the EJB project and the javax.serlet:servlet-api:2.5 to the WAR project. With this, the configuration for these two projects is working fine. Unfortunately, the EAR project is not working and cannot be deployed. For some reason WTP does not recognize the modules for this project and when trying to deploy it, some ClassCastException is thrown. So much for maven-eclipse-plugin...

eclipse:m2eclipse
...or not? The plugin features another goal, that could be useful here: eclipse:m2eclipse. This will generate the eclipse configuration in the same manner, but it will add the M2Eclipse plugin to the projects. This plugin has a lot of useful features: It makes synchronizing the eclipse configuration with the maven configuration a breeze. It will, for example, add the maven dependencies to the eclipse classpath, but it will also synchronize other properties, like the java version. Furthermore adding dependencies and changing the POM in general becomes really easy and, finally, creating new Maven project or modules from within eclipse becomes really easy.
This way of setting up the eclipse project is rather different from the previous one: In stead of generating all the configuration files correctly, the M2Eclipse plugin works from within eclipse to synchronize the eclipse and WTP configuration. The eclipse:m2eclipse goal does not work well with the configuration given above for the eclipse:eclipse goal, especially for EAR projects. It is better to remove all configuration from the maven-eclipse-plugin configuration and let the plugin do it's work. This means that after generating the eclipse project files, you'll have to open the Eclipse workspace and kick-off the synchronization process manually. More about this can be found on the Maven site for the archetype.

JBoss Tools support
JBoss tools is a Eclipse feature, that can be enabled on a project by adding some configuration (JSF and Seam facets, the SeamBuilder and SeamNature) to the eclipse project. JBoss Tools will manage two projects: the WAR and the EJB project, but the WAR project will be the main source of configuration. By adding the necessary items to the maven-eclipse-plugin configuration for this project and also adding a special Seam configuration file to the .settings directory, JBoss tools will recognize the project correctly.
For some reason, JBoss tools also stores some configuration in the workspace configuration. This can not be configured from the Maven Archetype and thus the JBoss Tools configuration is not complete. Because of this, the link between the WAR and EJB project will not be found by JBoss Tools from the EJB project. When a new Seam Artifact (Action, Entity, Form or Conversation) is added from the EJB project context meny, the configurations made in the WAR project are not picked up. When adding from the WAR project they are picked up and some sources will also be written in the EJB projects, as required.

JBoss Tools - JSF templates
JBoss Tools will generate Java sources and JSF pages when a new component is added. The JSF pages expect certain templates to exist in the Seam project and wont work correctly if they are not found. Adding these files to the Maven Archetype makes the generated JBoss Tools project work correctly. Also the Maven projects needs additional dependencies on RichFaces and Facelets in a certain configuration (some jars should go in the WEB-INF/lib, some in the EAR/lib) to make the deployed application work correctly.
The JBoss Tools project generated by the (current version of the) archetype will be exactly the same as a project created from within JBoss Tools, except for the security configuration.

Deploying on JBoss - application.xml troubles
One last problem arises when trying to deploy the generated application on JBoss AS 4.2: It will complain about the missing META-INF/application.xml. As per latest JEE spec, the application.xml is no longer mandatory, but JBoss AS 4.2 doesn't handle this correctly. To make it work with WTP on JBoss and also with the Maven created artifacts, we have to apply a few tricks to make it all work:

  1. We need to add an 'empty' application.xml file in the META-INF directory in src/main/application of the EAR project.
    This file is changed by the M2Eclipse plugin and used by WTP to make the deployment work on JBoss AS.
  2. We let Maven generate an application.xml file during the build by setting the property generateApplicationXml on the ear plugin.
    The file is generated in the normal bulid directory and not the same as the previous.
  3. We exclude the first file from the maven-bulid EAR file using the property earSourceExcludes on the ear plugin (value:META-INF/application.xml).
    this way the first file is ignored and the second is used in the maven build.

Et voila! At this point we have reached our goal of building a Seam project with Maven while still being able to use JBoss Tools, Eclipse and WTP for development.

Happy Coding!

Comments (8)

  1. Martin Borgman - Reply

    June 6, 2009 at 6:36 pm

    Hi Maarten,

    One small note, JBoss 4.2 is actually a J2EE 1.4 compliant server with some JEE 5 like features. JBoss 5.0 and 5.1 should be JEE 5 compliant.
    Like the article.

    Cheers,

    Martin

  2. [...] Configuring a Seam EJB project for development with Maven and … [...]

  3. Carlos Perez - Reply

    June 6, 2009 at 9:37 pm

    Thanks! I will make yet another attempt at this incredibly complex configuration.

  4. Balaji D Loganathan - Reply

    June 7, 2009 at 7:34 am

    Hi Maarten,
    Nice blog, especially the last part "Deploying on JBoss - application.xml troubles". This is something that the users of Jboss-Maven were missing.

    What I couldn't find so far on any blogs/articles is a plain vanilla Jboss-Maven project src files (a simple hello world with jpa integration). If you could add the sample project src files to this very blog, then the readers have all they want.
    Thank you.
    Regards
    Balaji D Loganathan, Spritle Software.

  5. max Andersen - Reply

    June 7, 2009 at 2:50 pm

    Great blog! What are the settings you think we should be saving on the project instead of workspace ? The only settings that are in there is the seam runtime afaik.

    Fyi We are about to release m1 of JBoss tools and shortly after this snjezana will add our first maven integration to JBoss tools - feedback and other contributions very welcome!

  6. Maarten Winkels - Reply

    June 7, 2009 at 4:26 pm

    Hi Max,

    I find all the projects that are created through JBoss Tools in the workspace metadata of org.jboss.tools.seam.core plugin. There is a projects directory that lists all projects with their respective components.

    When creating the project through Maven with M2Eclipse, this is not updated and thus JBoss Tools seems unable to detect all components correctly, as well as being unable to see the relation between the EJB and WAR projects.

    I haven't really dug into it, but this is what I found sofar.

    Thanks for the thumbs-up!
    Cheers,

    -Maarten Winkels

  7. [...] a Seam EJB project for development with Maven and JBoss Tools (Maarten Winkels) [Link] Lesezeichen erstellen  Artikel per E-Mail empfehlen Links Tags: JEE, [...]

  8. Moritz Winter - Reply

    July 1, 2009 at 2:52 pm

    We actually use this configuration in our Seam Project. The differences are we don't use eclipse:m2eclipse or clipse:eclipse because we handle eclipse config in svn and we use JBoss 5.x.
    My experiences with this project configuration are awful, the whole thing doesn't work. First the application.xml isn't generated correctly by m2e (https://issues.sonatype.org/browse/MNGECLIPSE-1088) and the libraries are cluttered all over the place in the ear. Then theres a error in m2e which causes the ejbs to be not included sometimes (https://issues.sonatype.org/browse/MNGECLIPSE-1447). The war-libraries are not copied by m2e (https://issues.sonatype.org/browse/MNGECLIPSE-1117).
    The worst thing about this is the hot deployment doesnt work with ejb 3.0 at all, not even the war-deployment.
    So I don't recommend to anyone to develope a seam-application like this, i didn't find no alternative tough.

Add a Comment