Tomcat to JBoss migration

Tomcat to JBoss migration is a typical scenario when you Web application requires some additional services (like JMS or transactions) which are available when using an application server. In this tutorial we will show some of the common pitfalls you can encounter when upgrading from Tomcat to JBoss AS.

There are mainly three areas which you should consider when migrating from Tomcat to JBoss AS: Common libraries, Data source configutation, JNDI bindings and basic server configuration. Let’s see them all:

Common libraries

 Apache Tomcat stores the common libraries into the CATALINE_HOME/lib folder.

 The lib directory is the direct replacement for both common/lib and common/classes subdirectories used in Apache Tomcat 5.x releases: it accepts both JARs and exploded class hierarchies.

When moving to JBoss AS you should place the common libraries in the following location:

JBoss AS release Path for common libs
4.x JBOSS_HOME/server/[server-name]/lib
5.x – 6.x JBOSS_HOME/common/lib
7.x JBOSS_HOME/modules

Check this tutorial if you want to learn how to install some libraries as modules into JBoss AS 7.

JDBC configuration

A Datasource is configured in the context.xml file of Tomcat:

    <Resource name="jdbc/oracledb"

then, you should add your JDBC driver into CATALINA_HOME/lib folder

On the JBoss side, this is configured:

JBoss AS release Path for data source
4.x – 5.x – 6.x datasource-ds.xml file into JBOSS_HOME/server/[server-name]/deploy

datasource-ds.xml file into JBOSS_HOME/standalone/deployments or

as a module into JBOSS_HOME/modules

Here’s a tutorial for configuring a Data source using JBoss AS 4-5-6

Here’s a tutorial for configuring a Data source using JBoss AS 7

JNDI Bindings

A common source of problems is that each platform stores Objects under different locations of the JNDI tree. For example, here’s how you would retrieve the data source you have just configured in Tomcat:

DataSource ds = (DataSource)initContext.lookup("java:comp/env/jdbc/oracledb");

Don’t be surprised that this won’t work in JBoss AS. In particular, when using JBoss AS 7 you have to choose a JNDI location like java:/ or java:/jboss for your datasources in order to be accepted. So, how’s a portable way to write a code that works in both environments ? The portable approach for defining data sources is to use a resource reference.

Resource references enable you to define the JNDI name for your data source, relative to your application naming context (java:comp/env), and then map that logical reference to the physical resource defined in the application server, whose JNDI name is proprietary to the application server. This approach enables your code and assembly to be portable to any compliant application server.

In our example, we need to define into your web.xml for your connection pool:

      <description>DB Connection</description>

Alternatively, starting in Java EE 5 (Servlet 2.5), this can be done even easier within your code using the @Resource annotation.
public class MyServlet extends HttpServlet {

    @Resource(name = "jdbc/oracledb")
    private DataSource dataSource;

Then on the JBoss side define in your jboss-web.xml


Fine, now your JNDI lookup will work in either environment, without changing one line of code!

Server configuration

As last option you should check if you have any customization in your apache tomcat’s server.xml. Although by default both Tomcat and JBoss are delivering http applications on port 8080, chances are that you might need configuring the http port. Here’s tomcat’s server.xml

    <Connector port="32080" protocol="HTTP/1.1"
               redirectPort="8443" />

 If you are using JBoss AS 4/5/6 you can easily merge your server.xml configuration into jboss-web.sar/server.xml file.  If you are using JBoss AS 7, then you should either use one of the management interfaces (Web /CLI)

tomcat to jboss migration

or change it by hand into standalone.xml/domain.xml file

   <socket-binding-group name="standard-sockets" default-interface="public"  >
        <socket-binding name="management-native" interface="management" port="${}"/>
        <socket-binding name="management-http" interface="management" port="${}"/>
        <socket-binding name="management-https" interface="management" port="${}"/>
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="32080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>

from tomcat to jboss wildfly

Suggested reading: From Tomcat to WildFly in one day.

A 100 pages long practical guide that will help you to get into WildFly configuration and deploy applications on it for users with a Tomcat background.

Covering all key aspects of software migration including core server configuration and its services, Tomcat application migration, porting Security and Clustering services to WildFly.