Building a JBoss Ready Spring MVC Web App

Spring is a really cool J2EE extension framework incorporating Inversion of Control and Aspect Oriented Programming techniques, and JBoss is one of the first open-source J2EE container well-known in the community. However building a Spring based application to fit for a JBoss deployment isn’t always a straightforward task.

Spring provides an easy-to-use rapid code generation tool called “Spring Roo” so you don’t have to start from scratch to achieve most of the configuration plumbing. However the code generated by Roo assumes a minimalistic web container (such as tomcat) where almost all Java EE API modules are deployed on the application side — not on the container.

Although this topic is still widely open for discussion, the benefit of using a container managed modules includes ease of configuration, operation and maintenance. For example if you deploy your datasource on JBoss, it would provide you with the connection pool usage statistics.

This guide demonstrate process of developing a simple Phonebook application where user can list and add contacts. Following are the goals we’re trying to achieve:

  • Spring-based application generated by Spring Roo which should be suitable to deploy to JBoss container.
  • Minimal (none if possible) JBoss customization. The web-app we’ll create should deploy straight into a fresh-install JBoss container. Only stuff like datasources should need configuration on JBoss
  • Use JBoss provided Java EE API modules whenever possible. The JBoss server profile we’ll use is ‘default’ which already provide a lot of stuff, including servlet, JSP, JSTL, EL, JTA, EJB3, JPA and Hibernate.

This guide and the demo source code is written against following versions:

  • JBoss 6.0.0.Final & 7.1.1.Final
  • Spring Roo 1.2.2.RELEASE
  • JDK 6
  • Apache Maven 3.0.3

Let’s Start the Rapid Code Generation

Start the Spring Roo shell (either via command line or your favourite IDE) and use following commands:

  1. Create new war project. Adjust project name and top level package to your liking. IDE such as eclipse provide a dialog box to create a new project, feel free to use it instead.
     project --topLevelPackage com.wordpress.gerrytan.springjboss --projectName spring-jboss --packaging war 
  2. Setup JPA persistence. JBoss came with pre-installed HSQL datasource available via JNDI under the name java:/DefaultDS, so we’ll leverage this. Feel free to install and use another database if you want to. (If you use JBoss 7, the sample datasource JNDI name is java:/jboss/datasources/ExampleDS)
     jpa setup --database HYPERSONIC_PERSISTENT --provider HIBERNATE --jndiDataSource java:/DefaultDS 

    After you run this command, Roo will create a Spring applicationContext.xml configuration file that will scan and contain your data and business layer beans and JPA persistence.xml persistence unit configuration.

  3. Setup Spring MVC controller. If this is the first time you hear about Spring MVC, you might want to read their manual (or keep going — trust me, Spring MVC provides a powerful API for your web-app 🙂 )
     web mvc setup 

    After you run this command Roo will create a web.xml with Spring MVC DispatcherServlet configured, and a webmvc-config.xml that will scan and contain your Controller beans. Note that the webmvc-config.xml context will be set as a child of applicationContext.xml context so that your data layer beans will be instantiated first, and then injected to your controller beans. Roo will also configure JSP + Apache Tiles based views for you which we’ll cover later.

Great! At this point you have almost all the boilerplate and plumbing you need to start writing your web-app.

Start Writing the Web App

The small web app we’re going to write has one page with two panels, one for add-contact form, and the other for listing and deleting contacts:

  1. Create a new Contact entity with firstName, lastName and phoneNumber fields. We’ll again leverage Roo to do this. Issue following command on a Roo shell:
    entity jpa --class ~.Contact
    field string --fieldName firstName --notNull
    field string --fieldName lastName --notNull
    field string --fieldName phoneNumber --notNull
  2. Create (manually) a new Controller. I won’t use Roo this time because the controller code generation feature of Roo provides us more than we need, so we’ll just create a simple Spring MVC controller here. The controller has all handlers method to perform addition, listing and deletion. Familiarize yourself with Spring MVC Controller if this is the first time you see it.
    public class ContactController {
      @RequestMapping(method = RequestMethod.GET)
      public String get(@ModelAttribute("newContact") Contact contact) {
        return "contact/index";
      @RequestMapping(method = RequestMethod.POST, params="deleteId")
      public String delete(@RequestParam long deleteId) {
        Contact contact = Contact.findContact(deleteId);
        return "redirect:/contact";
      @RequestMapping(method = RequestMethod.POST)
      public String add(@ModelAttribute("newContact") @Valid Contact contact, BindingResult bindingResult) {
        if (!bindingResult.hasErrors()) {
          return "redirect:/contact";
        return "contact/index";
      public List getContactList() {
        List result = Contact.findAllContacts();
        return result;
  3. Create the view, we’ll leverage the Apache Tiles API provided by Roo. Tiles adds much-needed templating and inheritance feature to JSP so it’s easy for you to reuse parts of your presentation code in multiple place. Have a look at their manual page for more info. Create a jspx file src/main/webapp/WEB-INF/views/contact/index.jspx which will contain our jsp view presentation code to list Contacts and add a new one:
        <!-- HTML headers and other stuffs omitted for brevity -->
        <!-- Add Contact Form --></pre>
    <div><span class="label">First Name</span>
     <span class="label">Last Name</span>
     <span class="label">Phone Number</span>
     <input type="submit" value="Add Contact" /></div>
        <!-- List Contacts --></pre>
     You have no contacts in your phone book. Add a new contact using the form above.
    <th>First Name</th>
    <th>Last Name</th>
    <th>Phone Number</th>
    <th><!-- empty column --></th>
    <td><form method="POST"><input type="hidden" name="deleteId" value="${}" />
     <input type="submit" value="Delete" /></form></td>
        <!-- HTML footers and other stuffs omitted for brevity -->

    And create a views.xml tiles configuration file. This file contains metadata information about template, inheritance, and other tiles feature. Since this is just a simple web-app, I’m not superclassing any other page or template, but just create a new standalone jsp page

      <definition name="contact/index" template="/WEB-INF/views/contact/index.jspx">

That’s about all the code we’ll need for this web-app. Now is the slightly tricker part, plumbing Spring into JBoss.

EntityManagerFactory Plumbing

When you setup JPA using Roo, it gives you a Spring-managed persistence unit via LocalContainerEntityManagerFactoryBean. However when you deploy your app to JBoss, the presence of META-INF/persistence.xml also causes JBoss to create its own persistence unit, causing conflict. Of course you can avoid JBoss from creating a persistence unit and keep the Spring-managed ones if you want, but the approach we’ll take here is to use the JBoss provided:

  1. Configure the JNDI name of the JBoss-provided persistence unit. Add following element to your web.xml. <persistence-unit-ref-name>persistence/spring-jboss-emf</persistence-unit-ref-name> will be the JNDI name of the JBoss provided persistence unit, and <persistence-unit-name>persistenceUnit</persistence-unit-name> is the name Roo give to the persistence unit configuration file (META-INF/persistence.xml)
  2. Replace LocalContainerEntityManagerFactoryBean with JNDI lookup on applicationContext.xml
    <!-- <bean class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean" id="entityManagerFactory">
            <property name="persistenceUnitName" value="persistenceUnit"/>
            <property name="dataSource" ref="dataSource"/>
        </bean> -->
  3. Let the persistence unit know what the datasource JNDI name is. We’ll just use the sample HSQL datasource which came with out-of-the-box JBoss install (java:DefaultDS on JBoss 6 and java:jboss/datasources/ExampleDS on JBoss 7). Add <non-jta-data-source> element to your META-INF/persistence.xml file:
    <persistence-unit name="persistenceUnit" transaction-type="RESOURCE_LOCAL">
                <!-- remaining code truncated for brevity -->

    We didn’t have to do this with Spring-managed persistence unit because LocalContainerEntityManagerFactoryBean already done it for us. Change java:DefaultDS into java:jboss/datasources/ExampleDS if deploying into JBoss 7.

  4. And since we already done step 3, we no longer need to keep the datasource bean on applicationContext.xml. Feel free if you want to keep it though
     <!-- <jee:jndi-lookup id="dataSource" jndi-name="java:DefaultDS"/> --> 

Maven Fine Tuning

We’re nearly there. This last bit is related to Maven (the build, packaging, and dependency management tool):

  1. (Only if you use eclipse) Change java.version properties on pom.xml from 6 into 1.6. You might not need to do this but I use eclipse and somehow I couldn’t get it to run in jdk 6 mode unless I change it. Right click on your project –> choose Maven –> Update project configuration once you’ve done this
  2.  Change the scope of following Maven dependencies into “provided”. These are the dependencies that will be provided by JBoss, so unless you mark it as so, Maven will include it on the war file (and potentially causing classpath conflict)

    You can change the scope of a dependency by adding <scope>provided</scope> element. The default if not provided is “compile”


Compile, Deploy and Cross Your Fingers

Here comes the moment of truth!

  1. Run mvn clean package command to compile and package your war file. Once it completes you will get a target/spring-jboss-1.0-SNAPSHOT.war file. Deploy this file by placing it to your %JBOSS_HOME%\server\default\deploy folder
  2. Start your JBoss server
  3. Open http://localhost:8080/spring-jboss-1.0-SNAPSHOT/contact on your web browser
  4. Enjoy your JBoss-ready Spring MVC web-app 🙂

Check the Demo Sourcecode

The demo sourcecode for this blog post is available here:

Note that if your code output some logging content, it’s best to use the slf4j logging API. Slf4j provides an abstraction of all other available logging APIs so your code will still work regardless of which logging implementation is used.

It Doesn’t Work!

Relax, it does take time to get everything in place. Here are few tips for troubleshooting JBoss deployed Spring web app (apart from the obvious: inspecting the exception, stack trace, logs, etc):

  1. Review all the ‘plumbing’ work, make sure there’s no leak on the pipe! Following are the list of all the configurations file we’ve touched in this guide:
  2.  Review the jars included inside your war file against the one provided by JBoss. If you think you’re packaging something already provided by JBoss, maybe you should mark the dependency as “provided”
  3. Consult the manuals, reference guide, and ask the community

One thought on “Building a JBoss Ready Spring MVC Web App

  1. Hi, quite detailed post. Is it possible to provide the solution where you avoid JBoss from creating a persistence unit and keep the Spring-managed ones?
    I am experiencing a problem with persistence Unit definitions when deploying into JBoss AS 7.1. The exception I get on runtime indicates the presence of multiple persistence units:
    java.lang.IllegalStateException: Conflicting persistence unit definitions for name ‘persistenceUnit’
    I have renamed persistence.xml to jpa-persistence.xml and have LocalContainerEntityManagerFactoryBean defined as:

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s