March 12, 2014

Migrating from GlassFish to JBoss or TomEE

Java Tools
Enterprise Development

In this post, we offer up a little history of GlassFish before jumping into a tutorial on migrating from GlassFish to another application server. We look at all the options, make suggestions and take you through the process.

Chapter I: A little history of GlassFish

"This announcement and Oracle's 'optimizations' is the perfect opportunity for other vendors like TomEE (with commercial support by Tomitribe), Wildfly (supported by Red Hat) or WebSphere Liberty Profile (supported by IBM), to step in."Adam Bien, In his Blog

From Caviar to Great White Shark

Officially, the tool we all know as “GlassFish” is really GlassFish Open Source Edition, which is Oracle’s GPL/CDDL-licensed Java EE application server.

GlassFish came a long way, starting as a Sun Microsystems Inc. project back in mid-2005. It was based on the source code for the Sun Java System Application Server (SJAS) PE 9, which was donated to the community by Sun Microsystems along with Oracle’s donation of TopLink persistence code. The joint goal was to encourage communication between Sun & Oracle engineers and the community, enabling all developers to participate in the application server development process along with the JCP.

With this donation, developers from all over the world could access source code, nightly builds, discussion groups, and mailing lists. For the very first time in history, developers were able to meaningfully contribute to the application server creation process.

A Free and Fast Competitor to Oracle and IBM

Historically, GlassFish has always been backed up by a commercial distribution. Initially named SJAS, it became Sun GlassFish Enterprise Server with the Version 2.1 in mid-2009. At the end of the same year. Sun released the first Java EE 6 compatible version carrying the famous “v3” as the version number. It contained the completely rebuilt OSGi foundation created on Apache Felix and delivered an awesome developer experience by cutting down startup-times, providing hot-deployment and preserving http sessions across development redeployments.

GlassFish’s main competitor back in the day was the extremely lightweight Apache Tomcat. Developers got attracted to both the new Java EE 6 specification, which finally improved development productivity and ease of use, establishing convenient handling and administration as well. All this happened a year and a half after Oracle completed its acquisition of BEA Systems.

With increasing uptake on Java EE technologies, GlassFish became a solid alternative for even the most attractive and performant commercial application servers. Leading the field by continuously delivering technical innovation and driving specifications on the JCP had always been BEA Systems with their WebLogic server, but the release of GlassFish 2.1 was in more or less direct competition with Oracle’s and IBM’s WebSphere product line. But GlassFish was for free. And much faster.

Oracle Buys Sun Microsystems

The famous Oracle-Sun merger in early-2010 changed the rules. The GlassFish community was afraid of Oracle cutting off GlassFish completely in favor of the commercial WebLogic product they just recently integrated as their foundation for almost all commercial products. But basically nothing happened. Aside from a bunch of extra marketing and re-naming efforts for both the OSS and the commercial edition, pretty much everything else remained the same.

It had seemed that Oracle wanted invest into their new assets by putting up the so called 100-day releases with patches for both 2.1 and 3.0 versions. Unfortunately, this was followed by nothing groundbreaking. The 3.1.0 - 3.1.2 releases brought clustering back to the 3.x branch and delivered on long-overdue component updates and fixes in early 2011.

In mid-2012, a micro-release fixed a handful of exceptional issues. No further updates took place until June 2013, with the initial release of GlassFish 4.0 being the reference implementation of Java EE 7. The community stood behind GlassFish the whole time. The NetBeans bundle, the unzip and start packages, the comparably good startup times and the overall availability of examples and documentation made GlassFish the #1 choice not only for beginners but also for people running real applications on it.

Oracle pulls commercial support

Starting in November 2013, things began going downhill for GlassFish. Oracle announced that they were cancelling the commercial supported version and that there will not be an Oracle GlassFish Server 4.0. This essentially means that GlassFish stays the reference implementation for subsequent Java EE versions, but isn’t seen as a commercial offering for customers.

There are various interpretations of this announcement. Common sense would dictate that given the actual setup of the GlassFish open source project and the remaining scope as a reference implementation, it is not going to be a fully-competitive app server anymore. The major point of the criticism is that it basically isn’t easy to contribute to the open source project. Compared with other leading frameworks (i.e. Spring) or app servers (i.e Tomcat) which have a vital community around them, the hurdles put in front of GlassFish are pretty high.

Transparency is probably another issue. Beside being closely tied to future Java EE releases, there is no clear vision for features and developments beside the scope of the umbrella specification.

Even if GlassFish stays the ideal way to learn the latest Java EE features and build the first applications using them, it will be hard to trust it for production because nobody knows if, when and how bug-fixes for reported issues might find their way into the code-base.

timeline of Glassfish server releases

Other Barriers to the Longevity of GlassFish

Whew. So, there’s more going on here too. Did you realize that there are a bunch of value-added features provided by every application server which are not covered by any specification? Clustering features are probably the most prominent example. Talking about administration features or adding new supported data sources or other products makes it even harder to imagine that GlassFish will stay the first choice without having a commercial payout for Oracle and without laying the ground for a vital community to deliver patches and contributions.

So if we assume that Oracle is just moving slowly and things will keep moving in the right direction, there is still another complex set of questions to be answered. Both GlassFish and WebLogic share a bunch of components (Jersey, Tyrus, etc.) and proposed community changes might potentially interfere with the needs of a future WebLogic product visions. This would require either a real product management team, some kind of extension points or much-increased transparency on the project management level. We think you can judge on your own how likely you think these things might happen.

Ok, enough with the history, let’s talk about the future! In upcoming chapters, you’ll see how to migrate your application and DB connections and datasource, plus what to do now with your Java EE implementations of EJB, CDI, JSF, JPA, plus all the changes you’ll need to make to your repositories, IDE, Continuous Integration server and frameworks. Go!

Chapter II: Migrating your application ecosystem from GlassFish

What are GlassFish users supposed to think--as well as plan--for the future in light of these changes? Will you be patient or pragmatic...or both? In this chapter, we discuss migrating your application code and DB/datasource elements.

How did we choose TomEE and JBoss as options for GlassFish users?

When GlassFish 4 was released, many users were planning to migrate their applications from GlassFish 3 to get advantage of all benefits brought by the Java EE 7 specifications. But now, they have been forced to plan a migration effort towards a different application server instead, pushing the excitement about using Java EE 7 away for now.

GlassFish users are probably facing the following options:

MeaningFind an alternative to the GlassFish 3 web/full profile and postpone the plans to migrate to Java EE 7Leave things alone for a while and start evaluating alternatives to GlassFish 4
Why?You’ll probably want to start a relationship with another support team as soon as possible to eliminate all lock-in features and avoid a hurried and risky migration in the future. They will focus all their attention on the migration and stop thinking about Java EE 7 for a while.If you believe your apps are not that locked-in, you’ll want to increase productivity and reduce app complexity, thus it’s ok to stay with GlassFish for a while and postpone the migration opportunity towards an application server that already supports Java EE 7.

At this point, you might may face yet another dilemma: do you continue relying on OSS, or move to a proprietary solution?

GlassFish is an open source software and it is certainly a reason why people decided to use it. These people are probably looking for an open source alternative because they need full transparency, have a lower budget and are able to improve the product if they can to.

Some of you don’t care if the application server is open source or not. You might fear that other open source options will end up like GlassFish, with no long-term technical support for subsequent releases. The lack of transparency and budget are not a problem for them either, and they hardly would have time to look at the code to find the root cause of the problem.

We can combine the options above and identify alternatives for each combination. The following table shows potential candidates to replace your Glassfish installation based on the options above:

 Stay using Java EE 6Also move to Java EE 7
Open source
TomEE 1.6, JBoss EAP 6
WildFly 8 *
WebLogic, WebSphere

* Red Hat doesn’t offer technical support for WildFly yet.   It is true that there are many other alternatives out there, such as Jetty, Resin, Geronimo, JOnAS and more; however, we have decided to limit our focus to the tools mentioned above due to the following reasons:

The vibrant developer community around these tools, namely JBoss and Tomcat The amount of documentation available on the web The sponsorship and support by market leaders [/list]

Open Source Options With Commercial Support - TomEE and JBoss

If you want to stay using Java EE 6 for a while and keep trusting on open source software, we suggest TomEE 1.6 and JBoss AS 7 / JBoss EAP 6 as alternatives to GlassFish.TomEE is a bundle of Apache implementations of the Java EE 6 specifications. It’s a relatively new product in the market, but it profits from Tomcat’s maturity, making it reliable and competitive. TomEE recently got Java EE web profile certified, which reduces the need for application changes when migrating from another certified product, such as GlassFish. Its official support is provided by

Tomitribe, the company started by David Blevins in 2013, who engaged several TomEE committers to interact directly with customers.

Red Hat has a very similar business model. Like TomEE, they offer official support for customers using products under the JBoss brand (i.e. JBoss = JBoss EAP and WildFly, formerly JBoss AS), which has a mature and established codebase. Among the above-mentioned, JBoss also has the largest installation base, documentation and a huge community. They are very competitive--indeed, our own Great Java Application Server Debate awarded 1st place to JBoss--but it doesn’t mean they are competition killers.

As part of Red Hat, they seem to have become slower to respond and more bureaucratic over time as they grow, a syndrome that attacks most growing IT corporations. The much-smaller and more agile Tomitribe is far more efficient in terms of decision making and response time, but cannot compare with resources. At least, that was our perception when we contacted both companies to request a offer for support and training.

Proprietary Options - WebLogic and WebSphere

Outside of the open source world, you find WebLogic and WebSphere as the two main proprietary players, provided respectively by Oracle and IBM. These companies have large developer bases and equally large contracts. In terms of service agility, we can apply the rule “the bigger you are, the slower you move”. It means their support works according to the agreed terms, but it might take more iterations to finally get a solution to the issues.

There is a very low probability that you are going to talk directly with a WebLogic/WebSphere committer (one of the people in charge of programming the application server), which is the opposite case with TomEE and, to some extent, JBoss. On the other hand, WebLogic and WebSphere have much more means to invest into their products for achieving higher levels of reliability, stability, optimizations, vendor support, HW/SW cost efficiency, and so on.

Oracle is tempting users with a claim that the easiest path away from GlassFish is directly to WebLogic, since it supports GlassFish’s deployment descriptors and share some of the libraries already.

However, the open source alternatives already support those deployment descriptors as well and JBoss also shares most of those libraries too. Therefore, the most logical decision when migrating from GlassFish is opting for an equivalent open source alternative. That’s why we have decided to explore only the technical details of JBoss and TomEE in the following sections.

Your Next App Server: Installing JBoss and TomEE

"Anyone who wants change in the market should support TomEE. Not because it's better than JBoss, but because we need another Red Hat. Another strong open-source vendor in there alongside Red Hat can change the market. It's currently a two against one scenario, with Oracle and IBM challenging Red Hat--though adding TomEE to the mix makes an even strong combination." – David Blevins, creator of TomEE and Tomitribe

The good new for us, being the intelligent, community-supportive, good-looking developers that we are, installing TomEE or JBoss is nice and straightforward: to get TomEE and JBoss up and running it's enough to download the zip file, unzip it on your machine and run one of the files in the bin folder.

We’ll leave the decision about the best location to install it up to you, since it depends on the operating system, the server configuration and personal preferences. At this time, it’s best to ensure you stopped Glassfish and any other application server(s) to avoid TCP/IP port conflicts.

Installing TomEE (or TomEE+)

Did you just see a “+” attach itself to TomEE? This is because we assume you are migrating from Glassfish full profile, not only web profile. So, download the TomEE+ (plus) installation package, available at and unzip it in a place you can easily remember. Create the environment variable $CATALINA_HOME​ pointing to the exact location where you unzipped TomEE+.

Check if it's correctly installed starting the server with the command:

Windows #> %CATALINA_HOME%\bin\catalina.bat run
Unix #> ./%CATALINA_HOME%/bin/ run

You know when the startup finishes when you see the following message:

 INFO: Server startup in 1344 ms

Open a web browser and access the url http://localhost:8080 to see the TomEE+ welcome page. We still have to create an admin user to be able to operate the admin console, and unlike Glassfish, TomEE+ comes with no user defined. Go to %CATALINA_HOME%\conf and edit the file tomcat-users.xml. You find at the end of the file the default security configuration for TomEE+. You just have to uncomment those lines to make it work:

<!-- Activate those lines to get access to TomEE GUI --> 
<role rolename="tomee-admin" />
<user username="tomee" password="tomee" roles="tomee-admin,manager-gui"/>

According to the configuration above, you can authenticate within the application manager using the username tomee and password tomee.

Installing JBoss

Download the latest installation package from In case of JBoss, there are two options:

  1. JBoss Enterprise Application Platform (EAP): commercial support by RedHat, more stable and with consistent releases of bug fixes.
  2. WildFly: supported by the community through the mailing list and forums, infrequent bug fixes but with the newest features available faster.

Both versions are installed the same way: just unzip the downloaded file in a place you can easily remember. Create the environment variable %JBOSS_HOME% pointing to the exact location where you unzipped JBoss.

Check if it's correctly installed starting the server with the command:

Windows #> %JBOSS_HOME%\bin\standalone.bat
Unix #> ./$JBOSS_HOME/bin/

You know when the startup finishes when you see the following message in the console:

(EAP) JBoss EAP 6.1.0.GA (AS 7.2.0.Final-redhat-8) started in 2659ms

(AS) JBoss AS 7.1.1.Final "Brontes" started in 2053ms

Open a web browser and access the URL http://localhost:8080 to see the JBoss welcome page. We still have to create an admin user to be able to operate the admin console, since JBoss also comes with no admin user defined. To create one, follow the instructions in the console URL: http://localhost:9990.

Migrating Your Database Connection

The database connection is by far the most frequently accessed component for Java EE applications. We will use MySQL to illustrate the deployment and the creation of a module for the JDBC Driver. If you use another database, you’ll probably go through the same steps, but using different parameters.

Installing the JDBC Driver on TomEE+

TomEE+ follows pretty much the same principle of Glassfish. The JDBC driver becomes available when it is visible in the classpath. The practical way of doing it is dropping the MySQL driver (mysql-connector-java-5.1.23-bin.jar) in the %CATALINA_HOME%\lib folder. Restart the server to make it available for the creation of the datasource.

Installing The JDBC Driver on JBoss

On JBoss, you have two ways of doing it: 1) you can deploy it as any other application package or 2) you can install it as a module.

For clustered environments, we recommend option #1 and deploy the driver, since the deployments are automatically propagated to all servers. If your driver is not JDBC4-compliant, you’ll have problems. In this case, take option #2 and create a module for your driver. The advantage of the JDBC driver as a module is the possibility of creating a custom JBoss bundle for your organisation--this way, you can repeat exactly the same installation throughout several machines, preserving the same configuration.

1. Deploying the JDBC Driver In the admin console, go to Runtime > Server > Manage Deployments and click on Add Content to deploy the MySQL driver. Upload the driver and give it a new name. Any JDBC4-compliant driver is automatically recognized by JBoss and made available for new datasources. If you are not using a JDBC4 driver, then click on En/Disable right after the deployment. screenshot of upload deployment selection window

2. Creating a Module for the JDBC Driver To create a module:

1. Go to %JBOSS_HOME%/modules/system/layers/base/com and create the folder mysql/main
2. Copy the file mysql-connector-java-5.1.23-bin.jar to the new folder %JBOSS_HOME%/modules/system/layers/base/com/mysql/main
3. Create the file module.xml in the same folder with the following content:
<!--?xml version="1.0" encoding="UTF-8"?-->

The name of the driver file may vary, so make sure you declare exactly the same name in the resource-root tag. Restart the server to make it accessible using the name com.mysql elsewhere in the configuration.

Configuring the Datasource on TomEE+

The configuration of a datasource on TomEE+ is really simple. All you have to do is to open the tomee.xml file and add the following configuration:

JdbcDriver com.mysql.jdbc.Driver JdbcUrl jdbc:mysql://localhost:3306/app UserName app_user Password user_password

Restart the server to make it available for the application.

The JNDI name is used by the application to reference the datasource, and here is a fundamental difference between Glassfish and TomEE+. Your current JNDI name may look like jdbc/appds in Glassfish, but in TomEE+ you need to append the prefix openejb:Resource/, resulting in openejb:Resource/jdbc/appds.

Configuring the Datasource on JBoss

The JNDI name on JBoss is also different from Glassfish.

You need to append the prefix java:/ or java:jboss/, resulting in java:/jdbc/appds or java:jboss/jdbc/appds respectively. You can create a datasource by directly changing one of these files:




If you have a clustered environment, which usually happens in production, then add the following configuration to the file domain.xml. To do the same with a single JBoss instance, add it to the file standalone.xml.

        <datasource jndi-name="java:/jdbc/AppDS" pool-name="AppDS" enabled="true" use-java-context="true">

Restart the server to make it available for the application.

Application Configuration for the Datasource

Because of differences in the JNDI naming rules, it's necessary to change all occurrences of the previous JNDI name to the new one.

For TomEE+, search for jdbc/AppDS and change it to openejb:Resource/jdbc/AppDS.

For JBoss, change to java:/jdbc/AppDS. If you are using JPA, you will find a reference to the datasource in the file persistence.xml. You may also find such references in @Resource annotations.

Chapter III: Setting up your Java EE Specifications/Implementations: EJB, CDI, JSF and JPA

You might assume that your Java EE specs, being standardized, will port directly and easily over to your new application set up...but you know what they say: if it seems too good to be true, then it probably is! ;-)

These Standards Should Migrate Seamlessly, Right?

One of the great things about specifications is that every developer who reads and implements them will understand them in exactly the same way, thus providing an implementation which isn’t just accurate, performant and bug free, but is entirely interoperable with any other implementation.

That is to say, an application which runs on implementation A of a specification will equally work when ported to implementation B of the specification. Isn’t that great! So we’ll just assume everything will just port across and work….WAIT, WHAT? That’s not what actually happens in reality?!? Shock! Horror! *Drops donut on the floor*

In reality, there are always going to be differences in how developers implement a specification irrespective of how a spec is written, because we’re human, we have different viewpoints and our brains make assumptions, where perhaps they shouldn’t. We need to understand the jump between specification and implementation.

The only way to guarantee a reasonable level of interoperability is to be assured that the implementations act the same, which means they need to be tested effectively. As a result, the key isn’t so much in the specification, but in the Technology Compatilibity Kit (TCK), which is a set of tests designed to confirm an implementation of a JSR as compliant. If the TCK for a specification is bulletproof, it doesn’t matter how loose the specification is, as the implementation is all we really care about. OK, it’s a lot easier if we have a good spec to write from, but the TCK holds the key. When we have 2 vendors which both implement a standard or spec, and interop is a pain, do not blame the vendor, blame the TCK. Oh and by the way, you can’t access the TCK as a user, it’s all under wraps.

We’re going to go through each of these specifications and see which implementations each application server uses and reflect on the migration paths between these variations.

Enterprise JavaBeans (EJB)

The EJB specification is one which many vendors actually choose to implement themselves, rather than use existing implementations. TomEE on the other hand has a history with Tomcat, which needs to be respected. This is from Tomcat users who already latch an EJB implementation onto the existing Tomcat base for use in a broader application environment. As a result, TomEE uses the Apache OpenEJB implementation. This was also a good choice, as for a new application server it’s important that it uses a well-trusted and tested implementation.

GlassFish uses it’s own EJB implementation, as does JBoss, but the EJB TCK is pretty strong and while it’s not rare to find interop problems during migration between vendors, it’s certainly not one of the bigger areas to worry about. Image of coffee bean

Context and Dependency Injection (CDI)

The reference implementation of CDI in Java EE is called Weld, a project driven mostly by RedHat, but included in both GlassFish and JBoss, whereas TomEE uses OpenWebBeans. Let’s take a look at the different versions supported by the different levels of application servers…

Weld logo

GlassFish 3.1.2 embeds Weld 1.1.4, while GlassFish 4 embeds Weld 2.0.0 SP1--although, if you’re using JSF as well, you may have upgraded to SP2 due to a Weld GF issue. JBoss EAP 6 uses Weld 1.1.8 and WildFly 8 uses Weld 2.1.1. TomEE, as we said, uses Apache OpenWebBeans as it’s CDI implementation. OpenWebBeans logo

When we look at the differences in these implementations, there are a couple of things to look out for. Firstly, you should ultimately care if the implementations are actually different projects, but you should also take note of the versioning, as sometimes that can offer up different problems based on the version migration path. This is very much up to the vendor / implementer though.

With CDI, both GlassFish and JBoss have the same implementations by CDI project, but at different versions. Weld is backwards compatible, and has a well-trodden path for upgrading versions, so you should have few CDI migration issues going from GlassFish to JBoss. TomEE meanwhile uses OpenWebBeans from Apache, so does have greater potential for migration problems.

JavaServer Faces (JSF)

The Java EE reference implementation of JSF is Mojarra. GlassFish embeds this directly into its runtime, whereas JBoss has a JSF implementation which contains Mojarra inside it. GlassFish 3.1.2 contains Mojarra 2.1.6, but of course you may have upgraded this to 2.2 to test-drive some of the new Java EE 7 features. GlassFish 4 contains Mojarra 2.2 out the box. JSF logo

Both WildFly and JBoss EAP have implementations of JSF based on Mojarra, so you should get a very similar experience with your vanilla Mojarra-based applications. JBoss now ships with a feature called Multi-JSF, which allows you to install multiple JSF implementations at different versions from JSF 1.2 up to and beyond JSF 2.2. This includes Mojarra or Apache MyFaces and so on. This gives you great flexibility for changing the JSF implementation in the future or using an implementation closest to GlassFish to migrate to initially; however, their default wrappered implementation shouldn’t prove that tricky to move to.

As you may guess, TomEE+ uses Apache MyFaces and ships with version 2.1.13, so it’s at the Java EE 6 level and if you’re already using JSF 2.2, you’d need to try to patch TomEE+ with MyFaces 2.2 which some have tried, or simply wait for TomEE to support it. As a migration from Mojarra to MyFaces, Mojarra tends to allow things which MyFaces does not, such as nested forms, actionListener validation, and more, so be prepared to do some work here during your migration.

Java Pesistence API (JPA)

The reference implementation for JPA is EclipseLink, a little-known JPA implementation compared to Hibernate or OpenJPA, but it’s the implementation that GlassFish uses.

EclipseLink logo

Interestingly, TomEE+ and JBoss each choose different implementations also, with TomEE+ opting for Apache OpenJPA (predictably) and JBoss using Hibernate (core).

apache openjpa logo

So realistically there isn’t going to be a plain and simple migration regardless of the route you take here, although the truly painful path of migrating from Hibernate to X, which is heavy on customizations, isn’t being considered. Of all the specifications, JPA migration looks to be the worst, with many experiencing exceptions throughout their persistence units during the migration. Hibernate logo

Chapter IV: Getting the rest of your environment back online (repository, IDE, CI server and frameworks)

Getting close to the end--here we go over getting your general development infrastructure back online, from repository to web framework.

Your Repository

We hope at this point you’ve stopped the thought process whereby you are thinking, “Well, at least I don’t need to do anything regarding migration of X”, where X = repository ;-)

Luckily, we don’t really see any problems with repositories. We include this for the sake of completeness, unless of course you work on a product that uses the application server as a dependency. In that case, the dependency is probably wired deeply into the logic of your code and only your team could have enough insight to predict the pain this migration might bring.

But if you’re really interested in it, here’s with the source code

for JBoss and the SVN repo for TomEE+. Both provide enough instructions to get started, build the project, start and run some tests. And hey, if you’re in the mood, you can contribute a bugfix or two!

Your IDE

Brace yourself though, IDE configuration requires probably the most changes out of all the sections of your development environment. Changes here are IDE-specific, so we divided this chapter into relevant parts covering the three most widely-used IDEs: Eclipse, Intellij IDEA and NetBeans.


As you probably know, Eclipse is the most popular open source IDE for Java development, with an enormous community behind it. Eclipse is an excellent IDE, as we wrote in Using Eclipse for Java Development, but it’s also a platform for rich applications and has the largest number of plugins available. Eclipse and TomEE+ Managing your application server and deploying to it from within Eclipse is supported for nearly all of the app servers out there. For some of them, however, integration is more complex: for example, TomEE+ deployments work fine, however it uses Apache Tomcat’s connector to make it done.

screenshot of TomEE server runtime environments preferences windo

When you configure a TomEE+ installation, just pick Apache Tomcat 7’s connector and point your Eclipse to a directory where you’ve unpacked a TomEE+ archive. As a tip, we’d recommend naming this server runtime “TomEE” or something to distinguish it from the regular Tomcat instances.

Your next steps are straightforward and are the same for all the servers: Just click on the application and make it Run on server, then select your TomEE+ instance and check “Always use this server when running this project”. screenshot of Apache TomEE run on server selection window

That’s it! And when the server starts, it will deploy your application. If instead of starting the server, Eclipse mumbles something about Runtime Environment not being configured, open the server configuration and ensure that one is configured. screenshot of TomEE server configuration window

That’s it, now it should run without any problems.

Eclipse and JBoss

Now let’s configure a JBoss instance to be up and running as well. Eclipse has an excellent JBoss Tools plugin, which is actually an umbrella project for several tools to support JBoss, Drools, JBoss Portal, Seam and other JBoss technologies. screenshot of JBoss tools folder contents

Installing JBoss tools will bring tons of plugins to your Eclipse instance, however, these come from a single source and are verified to work together well. So don’t worry about performance, they bring value if you’re using JBoss.

Configuring a JBoss instance works like the same way as for the others servers. Just select the server type and point it to some unpacked JBoss location:

screenshot of JBoss runtime configuration window

By dragging-n-dropping your project to a configured server on the Servers tab, it will create a configuration to deploy the application. Starting the server will bring that application up now.

Intellij IDEA

What’s good about Intellij IDEA is that, being a commercial IDE with rapid release cycles, it almost always comes with ‘batteries included’. IntelliJ has a good integration with TomEE+, so that when you specify a location of your TomEE server directory, IntelliJ parses versions of the libraries you’re using and presents all the information clearly.

IntelliJ IDEA with TomEE+

screenshot of tomEE libraries directory in intellijIDEA

In all other aspects it just works so after a couple of clicks you’ll get your server up and running.

IntelliJ IDEA with JBoss

It’s also pretty much a breeze in the case of JBoss. IntelliJ offers a sample configuration and the only thing needed is to point it to a location of local JBoss home directory and specify what artifact to deploy. screenshot of JBoss home directory in IntellijIDEA

The server now can be started with just a click of the ‘Run’ button. And the application is deployed as one would expect.


For this report, we tried out and configured a beta build of NetBeans 8.0. Allegedly, it’s stable and faster than its predecessors.

NetBeans and TomEE+

TomEE integration requires the Java EE Base plugin to be installed, which is a good thing since we actually set up JBoss first and realized that since we didn’t have it installed, we were prevented from deploying to the application server configured. However, installing the plugin solved the issues... When you develop web or enterprise applications, you want the first class support for it in your IDE.

screenshot of migrating from glassfish to netbeans + tomee installation server location selection

Let’s say you have a TomEE+ instance unpacked and ready to be configured. When you select TomEE as a server type in NetBeans 8.0, it asks a bit more details than just a location of binaries.

You can optionally specify which directory you want to have as $CATALINA_BASE, so different server configurations won’t compete with each other. Additionally, you can specify the manager user credentials, so they can be used for deployment.

Compared to WildFly, which is a certified Java EE 7 application server, TomEE at the time of this report being written only supports Java EE 6. So it might be smart to review this option in the NetBeans run dialog.

NetBeans and JBoss

Out of the box NetBeans 8.0 doesn’t have any support for JBoss servers, so to fix this problem, go through Tools > Plugins > Available plugins > “WildFly application server” and install this support. As we mentioned above, the Java EE Base plugin is completely necessary here to avoid major headaches.

After an IDE restart, you can start configuring JBoss instances. The menu to add servers is located under the Tools > Servers item. Configuration closely resembles that in all IDEs mentioned above: just point to the location of JBoss and continue. Screenshot of Netbeans + JBoss server configuration window

The NetBeans wizard automatically goes through another screen to configure instance parameters. image of Netbeans wizard instance parameters screen

So in order to deploy, you should open project properties, select the Run tab and specify what application server should NetBeans use.

image of netbeans project properties run tab

Your CI server

Continuous Integration is the key to successful development and project monitoring--your software project simply isn’t healthy or reliable if you don’t use this pretty-much standard concept. Arguably, there are not so many differences for between application servers that affect CI servers like Jenkins, Hudson, Bamboo, TeamCity and others.

However, for the sake of completeness, we’d love to provide some insight about how to configure your CI server to deploy build artifacts to JBoss or TomEE application servers, using Apache Cargo.

Apache Cargo

Different projects have different needs and have to be treated personally. We’re going to focus on a default Maven web-application project setup, just to give you hints where to look when you want to set up your new application server from within your CI server.

In the Java world, Apache Cargo is a de facto leader among application server manipulation tools. Cargo provides a Java API, Ant tasks and Maven plugins to manage your application servers and you can see in the feature matrix that it has support for GlassFish 3.x/ 4.x, JBoss and TomEE (though Tomcat connectors).

Here are a couple of sample configurations for the Cargo-Maven plugin. First of all, we want to install the application server automatically. Luckily, most of the servers are available as Maven artifacts, so we can use Cargo’s default installer here.


The installer will download and unpack the application server artifact. The configuration section specifies which port Cargo should use to deploy your application to the WildFly.

Respectively, if you’re interested in the TomEE+ configuration, you just need to change a couple of lines. For example, Maven’s artifact with a TomEE+ distribution is:


Other settings are also somewhat specific to the connector that Cargo uses to manage the server, however there are no dramatic differences. With Apache Cargo you can easily include an application server setup into your continuous integration builds.

Your Java Frameworks

Most frameworks you’re using are not directly tied to an implementation of the application server, but there can be differences. In general, every application server allows overwriting its default configuration to specify the versions of libraries to use for a given deployment. So one of the easiest ways to migrate your application to another application server is to bundle all the implementations within the archive and make the server prioritize these.

However there are exceptions to a lot of rules. When we talk about frameworks that are required to manage servers themselves, it’s different story. Let’s take a look at whether your tests can be executed on another application server. Arquillian

Arquillian is a testing platform for Java maintained by Red Hat, which works best for integration tests that run in an actual application server environment. It’s a different approach from unit testing, where you want to ignore or mock as much of the external environment as possible. Luckily, Arquillian is designed to handle application server environments where you need to:

  • Manage the lifecycle of the container;
  • Deploy the archive to the container;
  • Execute the tests inside or against it.

In general, all server-related activities are done by a specific component inside Arquillian, a container adapter. Naturally, there are adapters for the most established application servers.

Another cool thing is that Arquillian is a Maven project, so specifying an adapter is a matter of pom.xml fiddling--here is an example of a configuration taken from the useful Java EE samples repository on GitHub: image of sample arquillian configuration from java ee samples repository github

Configuring JBoss involves some additional actions to unpack files and prepare the deployments, but it’s not a dramatic difference from what the GlassFish configuration looks like.

TomEE also enjoys Arquillian love, and being an Apache project it naturally has support for other open-source technologies. To use an Arquillian adapter for TomEE, just specify another dependency in the pom.xml.


You can also configure which ports your TomEE instance should bind with another XML snippet:

<container qualifier="tomee" default="true">
         <property name="httpPort">9090</property>
         <property name="stopPort">9099</property> 

Other frameworks that manage servers have also probably thought about integrations with different application servers, but as you can see with GlassFish, JBoss or TomEE, Arquillian got it covered.

If you are undergoing or planning a migration, we recommend that you create at least some acceptance tests to run in both application servers. Such minimal test coverage cannot catch all the bugs, but it will show you if things will blow up in your new app server environment.

Hopefully this brief introduction to getting your repositories, IDEs, CI servers and frameworks up and running with your new application server was helpful. Now time for closing thoughts :-)

Chapter V: Summary, Conclusion and Goodbye Comic ;-)

Looking for a recommendation on whether to use TomEE+ or JBoss? Well, you won’t find one here--both options are good depending on your needs--but this summary may help consolidate your thoughts...

What to expect When Migrating to TomEE+

Bolstered with the long-term market and community spirit of Tomcat, and given some new life with the young, ambitious Tomitribe for providing commercial support, TomEE is a promising choice for development continuing with Java EE 6 backed by an array of Apache implementations. We’ve heard that Java EE 7 certification is in the plans for 2014, but it shouldn’t be hard to get a hold of someone at Tomitribe to ask more questions.  Source:

Migrating Application, DB and Datasource

Installing and configuring TomEE+ is a simple thing, from .zip download to JDBC driver installation, JNDI name changes and datasource config. Some minor naming conventions are to be changed.

Java EE specifications EJB, CDI, JSF and JPA

TomEE benefits from long-standing Tomcat reference points, using OpenEJB effectively but requiring OpenWebBeans and MyFaces in place of the GlassFish’s own Weld and Mojarra implementations, shared by JBoss. GlassFish’s EclipseLink JPA implementation makes it an ugly migration regardless of app server.

Regarding repos, IDEs, CI servers and frameworks

Most of this is easy, as your repositories, CI server and frameworks don’t need to be “migrated” in a way, but connecting everything and ensuring it’s all working is another story. For CI servers, we recommend Apache Cargo, and using Arquillian to run integration tests to ensure that your frameworks aren’t breaking your code is a great idea.

Regarding IDEs, configuring Eclipse with TomEE requires Tomcat 7’s connector, IntelliJ IDEA is a piece of cake once the TomEE server directory is specified, and NetBeans is a bit trickier, requiring Java EE Base plugin to be installed and needs more info than the others.

What to Expect When Migrating to JBoss

Both WildFly and JBoss EAP have a well-established history of providing commercial support on top of excellent products. For development teams looking to use the latest Java EE 7 features, WildFly is the only certified implementation at the time of this writing. With an enormous community and wide installation base, Red Hat is the poster-child in enterprise open source solutions.

Migrating Application, DB and Datasource

Migration to JBoss is more or less as simple as it is with TomEE, with only minor differences emerging when it comes single vs. clustered instances of JBoss EAP or WildFly for your environment.

Java EE specifications EJB, CDI, JSF and JPA

JBoss uses its own EJB implementation, relying on the EJB TCK for interoperability. Regarding CDI and JSF, JBoss shares Weld with GlassFish, and now contains a handy multi-JSF feature that let’s it work from Mojarra (Java EE’s JSF implementation) or MyFaces equally. JBoss uses Hibernate as it’s JPA implementation, which being different from GlassFish’s can lead to difficulties.

Regarding repos, IDEs, CI servers and frameworks

As with TomEE, we gave the source code for setting up your repositories, and with Apache Cargo and a bit extra code, your CI server will be hooked up. Arquillian is literally built by Red Hat, so this is a breeze too. IDE support with Eclipse is handled by JBoss Tools, which is an excellent umbrella group of plugins. IntelliJ IDEA has first class support as well, and set up is simply pointing to your home directory. NetBeans 8.0 doesn’t support JBoss out of the box, so it needs some extra installation, and also that Java EE Base plugin.

Final Thoughts

Looking for a quick answer? Sorry, this report isn’t designed for that! The decision to migrate at all is still probably being discussed in most organizations--perhaps some of you were not even aware that Oracle has planned to discontinue commercial support for GlassFish! Regardless, this is a decision that requires planning and the ability to accept that your decision will probably be unpopular with some developers. Considering these factors, we suggest that you take the path of least resistance, be it TomEE or JBoss.

Editor’s note: Many thanks to Hildeberto Mendonca and Markus Eisele, two excellent Java engineers that donated their time and brains to make this report possible. This report was brainstormed, edited and written by (in alphabetical order) Markus Eisele, Simon Maple, Hildeberto Mendonca, Oleg Shelajev and Oliver White.

Additional Resources

Want to see what the future has in store for OpenJDK? See predictions from our experts in this on-demand webinar.

Looking for additional insights into Java development? Our blog features articles on everything from microservices to the latest JEPs.

Visit the Blog