Version 5

    JBoss AS4 to AS5 Upgrade Guide


    This is an upgrade guide specifically for those who are going from JBoss Application Server version 4.x, and upgrading to JBoss Application Server 5.x.

    JBoss AS4 to AS5 - Good Idea?


    The interesting part of this upgrade manual is that it's being written for a version that is already several releases past. We are all the way to AS7. This, of course, means we need a section dedicated to whether or not upgrading is even a good idea at all, or would it make more sense to go to the latest version.


    So if you are thinking about upgrading your JBoss AS4 to AS5, make sure you have asked yourself if this the best move to make.


    Start a meeting pulling in all the Java/JBoss architects that have been involved in the JBoss 4 "situation." In this meeting, create a list consisting of all the reasons your team wants to upgrade. What features in JBoss 5.1.0.Final are prompting you to move from AS4 to AS5?


    Here are things to keep in mind when determining if the port from AS4 to AS5 is a smart idea:


    1. JBoss 5 uses more RAM than JBoss 4. So if you are looking for more efficient RAM utilization, you aren't going to get it..
    2. EJB3 capabilities are better in JBoss 5 than JBoss 4. This is one of the main reasons people would consider upgrading to AS5.
    3. If you are moving to AS5, why aren't you going to AS6? AS6 is basically an improved AS5. Keep in mind that in the case of AS5 versus AS6, there really isn't that much more work getting something to work in one versus the other. Take a look as the AS6 release notes[4].
    4. You do NOT need to move to AS5 or later to use HornetQ or another alternate messaging system. You can get most of those working on AS4.

    [There are more reasons, community please add to this list!]


    Another important factor is whether you are upgrading to a community version or to an enterprise version.


    Community Edition


    JBoss AS4, AS5 and AS6 community editions are all no longer supported. So if you report a bug you find when moving from AS4 to AS5... the Jboss community will simply be like "Yeah I know it's broken, upgrade to the latest JBoss."


    At that point you would either have to find a work-around for the issue, or if that is not possible then you would have to create your own private branch and make a fix yourself. This is obviously not recommended mainly because such patches are not easily supported in the future. When you try to move to yet another later version of JBoss, those patches you applied might come to bite you.


    Enterprise Edition


    Start out by giving the Red Hat support policy a once-over and understand what to expect from the RedHat.


    In short:


    • AS4.3 has only Mantenance Support until Jan 2013 (4.2 is outdated)
    • AS5 Full support Nov 2012, Maintenance Nov 2016
    • AS6 Full support Jun 2016, Maintenance Jun 2019
    • Under a special subscription you might have 3 extra years 'Extended Life support'. (But remember Maintenance/Extended is only for limited bugfixing. You will not get new features, improvements, etc.)


    So if you use AS5 you STILL might run into an issue where you have the need to upgrade for features (i.e. EE6).


    JBoss 4.x to JBoss 5.x upgrade considerations


    So there you go! I warned you! Don't upgrade to JBoss 5.x unless you know it's for sure what you want to do!


    I’ve done four major Jboss4 to Jboss5 upgrades in my career. These upgrades have taught me that the migration process is pretty complicated, and that a “how-to” guide for how to upgrade won't be straight forward. This is because


    1. Jboss is historically not exactly well-documented (thus no official Jboss4 to 5 official migration documentation exists)
    2. Your migration process will be greatly simplified the simpler your web application is. The more JBoss4 features you are using… the more work it will be to move to a later version of JBoss. Many of the steps in a full blown migration guide would be skipped if such a guide existed because not many people utilize 100% of the features Jboss4 has to offer.


    So what will we use to create an upgrade guide? Answer: We’ll use the Jboss 5.1.0.GA release notes [0], the Jboss issue tracker [3], and all community forum posts we can Google up related to struggles others went through when they did their application upgrades.


    Get a list of the particular JBoss features you use


    The migration process usually starts with a simple research task:


    • For each web application being run on JBoss4, create a list of each JBoss feature being utilized


    This might seem kind of vague at first... but realize the goal is to answer this question:


    Pretend your applications are running on Tomcat5 alone, not on JBoss4. What extra features would you need to add to your application to get this to work on standalone Tomcat?

    Why do this? Because JBoss4 and JBoss5 are built on top of Tomcat as their web container, upgrading JBoss4 to JBoss5 will involve getting a list of each JBoss 4 features you are using that Tomcat did not provide you, and going through the JBoss5 equivalent feature. If any of these features have changed from JBoss 4 to 5, then obviously you will need to make changes to fix the issue. It might even be the case that a feature that used to exist in JBoss4 has been completely refactored out of JBoss 5.


    An example list of JBoss4 features my application might look like this:


    • JBoss security domains
      • SSO custom tailored to our company
      • Security roles imported from LDAP integration
    • EJB2
    • EJB3
    • JBoss Web Services from JBossWS
    • Jboss messaging functionality using JBossMQ
    • MDB’s
    • Clustering services


    Researching the Jboss 5 release notes


    Once you have a list of all the JBoss features that you are utilizing, you will need to research the release notes to gather all relevant changes that have occurred that might affect your web applications on Jboss 5.


    For example, let’s say one of the Jboss4 features I am using is EJB3. I will then open up the jboss 5.1.0.GA/readme.html file and then search for “ejb.”


    As a result of my search, I find the following modifications have been made that have a potential to affect my Jboss 4 EJBs:

    • If using proprietary JBoss/EJB3 annotations, those have moved (since Beta4) into the org.jboss.ejb3.annotation package, EJBTHREE-1099. Those are now included in a new artifact, jboss-ejb3-ext-api.jar
    • Interoperating with previous JBoss EJB3 implementations may present problems due to serialVersionUIDs issues, EJBTHREE-1118.
    • JBoss 5 is stricter when it comes to verifying/deploying JavaEE artifacts. EJB3 deployments that run in AS 4.2 may fail in AS5. We have tried to keep the validation messages as accurate as possible in order to help you modify your deployment descriptors/annotations to be in-line with the JavaEE 5 requirements.
    • File system layout for Jboss 5’s ejb deployer resources have been changed. Note deploy versus deployers:

    Jboss 4.2.3.GA: C:\Jboss\jboss-4.2.3.GA\server\all\deploy\ejb3.deployer

    Jboss 5.1.0.GA: C:\Jboss\jboss-5.1.0.GA\server\all\deployers\ejb3.deployer

    • EJB3 configuration is now controlled by deployers/ejb3.deployer/META-INF/ejb3-deployers-jboss-beans.xml. For more details check out this wiki page.
    • EJB was upgraded to 1.1.5.


    So I would then go through this list and make appropriate changes before even trying to deploy the Jboss5 system.


    High-level Set of Steps to Follow


    So let’s go ahead and try to create a high-level list of steps we can follow in order to upgrade Jboss 4 to 5. At this point, I’m assuming nothing about our environment and am just throwing out general procedures that one would want to follow.


    1. Obtain a development environment with a working release of the Jboss 4 application(s).
    2. Install a JBoss 5.1.0.GA on the same box as the JBoss 4.x.
      1. When launching JBoss 5.1.0.GA, remember to update JAVA_HOME to point to a JDK5 or JDK6 installation if necessary, and remember to update JBOSS_HOME to point to the JBoss5 installation directory.
    3. Configure data sources on Jboss 5 as they are on Jboss 4.
      1. Note: when installing Data source drivers, the C:\Jboss\jboss-4.2.3.GA\lib has changed to
    4. Note




    [0] JBoss 5.1.0.GA Release Notes* -

    [1] Migration Tips when upgrading from JBoss 4 to 5 -

    [2] Upgrading JBoss 4 to JBoss5 with Java5 to Java6 -

    [3] The Jboss issue tracker -

    [4] JBoss 6.1.0.Final release notes** -


    *  This is also available in your Jboss5 installation at: jboss-5.1.0.GA/readme.html file. This shows all the changes made from version 4 to version 5.

    ** This is also available in your Jboss6 installation at: jboss-6.1.0.GA/readme.html file. This shows all the changes made from version 5 to version 6.


    This article was generated from the following discussion: Upgrade Guide - JBoss 4 to 5