Spring is a really cool J2EE extension framework incorporating and 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. if this is the first time you see it.

   
   ("/contact")
   public class ContactController {
   
     (method = RequestMethod.GET)
     public String get(("newContact") Contact contact) {
       return "contact/index";
     }
   
     (method = RequestMethod.POST, params="deleteId")
     
     public String delete( long deleteId) {
       Contact contact = Contact.findContact(deleteId);
       contact.remove();
       return "redirect:/contact";
     }
   
     (method = RequestMethod.POST)
     public String add(("newContact")  Contact contact, BindingResult bindingResult) {
       if (!bindingResult.hasErrors()) {
         contact.persist();
         return "redirect:/contact";
       }
       return "contact/index";
     }
   
     ("contacts")
     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:
   First Name Last Name Phone Number
   You have no contacts in your phone book. Add a new contact using the form above.

   Id	First Name	Last Name	Phone Number
   ${contact.id}	${contact.firstName}	${contact.lastName}	${contact.phoneNumber}

   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

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 . 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 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/spring-jboss-emf will be the JNDI name of the JBoss provided persistence unit, and persistenceUnit is the name Roo give to the persistence unit configuration file (META-INF/persistence.xml)

     
       persistence/spring-jboss-emf
       persistenceUnit
     
   

2. Replace LocalContainerEntityManagerFactoryBean with JNDI lookup on applicationContext.xml

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 element to your META-INF/persistence.xml file:

   
           org.hibernate.ejb.HibernatePersistence
           java:DefaultDS
               
   
   

   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

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)

   hibernate-core
   hibernate-entitymanager
   hibernate-jpa-2.0-api
   hibernate-validator
   validation-api
   jta
   jstl-api
   jstl-impl
   slf4j-api
   slf4j-log4j12
   log4j
   jcl-over-slf4j
   

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

       
         org.hibernate
         hibernate-core
         3.6.9.Final
         provided
       
   

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%serverdefaultdeploy 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:

• For source code browsing: 
• For svn checkout:

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:

   pom.xml
   src/main/resources/META-INF/spring/applicationContext.xml
   src/main/resources/META-INF/persistence.xml
   src/main/web-app/WEB-INF/spring/webmvc-config.xml
   src/main/web-app/WEB-INF/web.xml
   

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