Reading Time: 13 minutes

There is no shortage of well-known reasons for wanting to migrate your Java EE web application to open source Tomcat. But without development experience with both your current Java EE application server as well as with Tomcat, it isn't clear what you must change in your Java EE application to get it to run properly on Tomcat. The benefits of being able to run it on Tomcat are significant — for example, Tomcat is free to run in production, and Tomcat is faster at tasks such as redeployment.

It's easy to migrate your Java EE app to Tomcat as long as it's mainly a web container app, and as long as you know what you might need to change in your app's code to get it running on Tomcat. Even if your Java EE app uses other Java EE server components, you can still migrate it to run on Tomcat if you add the open source counterparts of those Java EE components to Tomcat — you would need to know which open source components to add, and some instructions on how to make them work with Tomcat. For example, if your app used EJB, you could add OpenEJB to Tomcat.

latest report
Learn why we are the Leaders in management and

For the purposes of this blog, I'll focus on migrating from Weblogic to Tomcat, and on migrating from WebSphere to Tomcat. But, it's a similar process if you're migrating from other app servers such as JBoss or Glassfish.

If you're using Weblogic, see this page about the steps to migrate your Java EE app from Weblogic to Tomcat. The steps for changing the webapp's code to run on Tomcat include:

  • If your web application has JSPs, make sure that any references to java.util.* packages have corresponding import statements in the JSP file.
  • Make sure the root of your web application directory includes a WEB-INF directory with a web.xml file inside it. The XML in this file needs to declare your mappings from any weblogic.properties file you had.
  • If you were already using a web.xml file for WebLogic, you will likely have to scrub it for nonstandard elements and attributes, and find the standard way of doing the same thing. Tomcat will point these out to you.
  • Move your classes directory (if you have one) from the root of your web application to WEB-INF/classes.
  • Move any JSP files from your jspfiles directory (if you have one) into the root of your web application's directory. Tomcat requires them in the root of your web application.
  • Move any JAR files bundled by your web application to WEB-INF/lib.
  • Remove or stub out any code in your web application that imports/uses the com.bea.* or com.weblogic.* packages.

If you're using WebSphere, see this page about the steps to migrate your Java EE app from WebSphere to Tomcat. The steps for changing the webapp's code to run on Tomcat differ greatly depending on the version of WebSphere you're currently using.

For WebSphere 7.0:

  • From the WebSphere admin console, click Environment > Shared Libraries and inspect the list of container-wide shared jars. You may need to copy each of those jars into Tomcat's lib/ directory, if there isn't already a copy of it there.
  • Websphere 7's server-wide shared jars directory is the websphere/appserver/lib directory.
  • If your webapp uses JDBC, the driver jar file will reside in WebSphere CE's repository/ directory. Move it to Tomcat's lib/ directory. See Resources > JDBC Providers in the Websphere admin console.
  • If your web application uses JavaServer Faces, download an implementation of JSF 1.2 and place the jar(s) in your web application's WEB-INF/lib directory. See the Apache MyFaces project at http://myfaces.apache.org.

For WebSphere CE 2.1.x and 2.2.x:

  • In server.xml, change any WebSphere-specific realm implementation to a Tomcat-supported realm class name.
  • WebSphere CE runs a bundled version of Derby database. If you're using that, you'll need to download a separate release of the Derby jars and run that as part of your webapp. Place Derby's jar files in your webapp's WEB-INF/lib directory if you have just one web application that uses it, or place the jars in Tomcat's lib/ directory otherwise.
  • If your web application uses the ActiveMQ JMS broker that is part of WebSphere CE, you must download a separate release of ActiveMQ and run it as a separate JVM process. Change server.xml to access this separate ActiveMQ broker.
  • Configure Tomcat's connectors in server.xml by looking at the WebSphere CE property settings in var/config/config-substitutions.properties. See
  • If your webapp uses JDBC, the driver jar file will reside in WebSphere CE's repository/ directory. Move it to Tomcat's lib/ directory.
  • If your web application uses JavaServer Faces, download an implementation of JSF 1.2 and place the jar(s) in your web application's WEB-INF/lib directory. See the Apache MyFaces project at http://myfaces.apache.org.

For WebSphere 6.0 and 6.1:

  • From the WebSphere admin console, click Environment > Shared Libraries and inspect the list of container-wide shared jars. You may need to copy each of those jars into Tomcat's lib/ directory, if there isn't already a copy of it there.
  • If your web application uses JavaServer Faces, download an implementation of JSF 1.1 and place the jar(s) in your web application's WEB-INF/lib directory. See the Apache MyFaces project at http://myfaces.apache.org.

For WebSphere 5.1:

  • Websphere 5.1 ships with a very old version of JDOM. You may want to use a newer version of the JDOM jar. Place it into your webapp's WEB-INF/lib directory if you have just one webapp that uses it, or in Tomcat's lib/ directory otherwise.
  • If you are using scriplets, you may have to unescape some double quotes. For example:

    The above had to be changed to:

    in order to work properly in Tomcat.
  • If your web application uses JavaServer Faces, download an implementation of JSF 1.0 and place the jar(s) in your web application's WEB-INF/lib directory if you have just one webapp that uses it, or in Tomcat's lib/ directory otherwise. See the Apache MyFaces project at http://myfaces.apache.org.

Once you have your webapp running properly on Tomcat you'll enjoy some significant new benefits:

  • You have no more vendor lock-in
  • You run a much leaner / faster server
  • You're using the most popular application server in the world, with an active community around it
  • You have the full source code of the application server available to you, if you ever want to change the behavior, fix a bug, or fix a security issue

Once you migrate your Java EE app to run on Tomcat, you may then use Tcat Server for enterprise management and monitoring.  With Tcat server you may then continue to enjoy enterprise app server features as you are used to now, but this time Tcat Server allows you to do some additional things that weren't possible before, including:

  1. Connect up any Tomcat version you choose (5.5 – 7.0) to an enterprise-style central administration console
  2. Monitor and manage your open source Tomcat instances
  3. Gain Tomcat-specific visibility into your servers, and diagnose any issues
  4. Deploy webapps, configure open source Tomcat instances, perform reliable server JVM restarts across server groups of Tomcat instances from the GUI console
  5. Script redeployments, continuous deployment using either Maven or Ant, server restarts, server group administration, etc, via the Tcat console's REST API, where the scripts are written in your favorite scripting language.

.. and more.  Just because you're migrating to the world's most popular application server does not mean that you need to give up the enterprise management and monitoring feature set that you need.  With Tomcat and Tcat Server you get the best of both worlds! Start by downloading it here today, and begin using your open source Tomcat with the enterprise features you're used to.