Move your Java application into a hybrid cloud using Bluemix, Part 1

Migrate Tomcat to the Bluemix Cloud Foundry runtime


This tutorial was written using a previous version of the IBM Bluemix® interface. Given the rapid evolution of technology, some steps and illustrations may have changed.

Are you interested in running your Java™ applications "in the cloud?" But, considering the realities of an enterprise application, you're not even sure where to begin? In this series, we discuss different options in tiering a hybrid application, guiding you step by step through several examples. We explain how to migrate parts of your Java application, while connecting back components best left within your enterprise. In addition, we discuss different options for the Java runtime, the services, and the tooling.

This series focuses on both the Java application and the services it uses, and how you can move both the Java application and the relational database tier to a Cloud Foundry–based platform. We also cover the scenarios where services are left on-premise as well as changes that might be required to your application for session management, scaling, and logging as you move to the cloud.

Java application

In evaluating an application to migrate to the cloud, the natural starting point is the application itself. Throughout this process, you will need to understand the following:

  • What Java capabilities does your application use?
  • What external services and dependencies does it require?
  • Is your application cloud ready?
  • How much investment are you willing to make to update your application for the cloud?
  • How much investment are you willing to make to update administrative procedures?

Simple, Tomcat-style servlet and jsp applications are typically straightforward to migrate to the cloud, and you'll be able to choose among different runtime and service options. However, even simple applications might require you to consider how to handle such services as databases, and if you need scaling, how to handle session affinity. Our first example is a step-by-step migration for a Tomcat application, including the database. We then examine the problem of running Java worker processes in the cloud. In later tutorials, we'll examine the issues of scaling and session affinity in the cloud.

If your application uses capabilities such as Remote EJB, 2-phase commit processing, and other more advanced features, your migration options are more restricted (or more costly). We'll discuss different options available when your application falls into that bucket.

If you are not sure exactly what your application uses and needs, the step-by-step directions take you through a migration tool to analyze it. (This tool is recommended even if you think you know!)

This first tutorial in the series explains how to migrate an example Java application to the cloud and connect to a cloud-based SQL database.

Java runtime

There are multiple choices for running a Java application in the cloud. One option is to use a Java runtime that is provided by the Platform-as-a-Service (PaaS), such as the Liberty for Java Runtime in IBM Bluemix™. This is an easy path, as all you need to worry about is your application. With this option, you just deploy your application, without needing to install or maintain your Java runtime. IBM Bluemix supports the Liberty for Java buildpack, which includes Java EE 7 and the Liberty profile. Cloud Foundry's Java buildpack, which includes Tomcat 8.0.21, is also available on Bluemix. This tutorial includes step-by-step directions using both buildpacks.

If you want more control over the Java runtime, or if your application needs capabilities that are not currently supported by the Liberty for Java Bluemix runtime, you can select from different infrastructure-as-a-service options, where you control and manage the version of the Java language installed. In IBM Bluemix, you can choose a Docker container or a virtual machine for your Java runtime. These approaches give you more control over the runtime and the versions. However, with that control comes a bit more work for you in installation and management.

For more information on the three runtimes and their unique capabilities, see "Bluemix Instant Runtimes, Containers, or Virtual Machines."


Beyond the runtime, other critical decisions to consider include how to handle external dependencies such as database, messaging systems, and LDAP identity managers. You can choose to use cloud resources for these dependencies (for example, using a Database as Service in the cloud, like SQL Database on IBM Bluemix). Or you might choose to keep your external resources on-premise and connect from your application to the same dependencies you use today using the Secure Gateway Service. This series includes step-by-step directions for both alternatives.

Cloud application consideration

As an application moves into the cloud, you also need to understand if its design is at least "cloud ready," if not cloud-centric. The migration tool that we discuss scans for potential trouble areas when migrating to the cloud, including state management and logging, as well as other common items that need to be considered. In our example, we walk through the migration scenario for our application, which uses an HTTP session. However, we do not dive too deeply into designing for the cloud, and we recommend that you also look at best-practice articles that are dedicated to that topic, such as "Top 9 rules for Cloud Applications" and the 12-factor apps in plain English.


IBM Bluemix supports deployment of applications through Cloud Foundry, Docker, and virtual machines, so regardless of how you are developing your Java application or the deployment runtime path you select, you can push your application to the cloud programmatically. Our first example uses the command line to Cloud Foundry.

If you use Eclipse, there are a number of plugins to help with migrating and deploying applications on Bluemix. The migration toolkit plugin analyzes your application source and provide you with a report and suggestions for migrating to Bluemix. There is also a plugin for deploying to Bluemix. After the first example, which uses only the command line, all of our work is done in Eclipse, from importing and analyzing the application to making changes and deploying. Though Eclipse is not necessary, we recommend it for working with your Java application.

Migrating a Tomcat application to the Bluemix Java runtimes

Let's get started. We are using a sample application, RedbookLibrary, that runs on Tomcat. This application comes from the WebSphere Application Server v8.5 Migration Guide, where considerations involved in migrating from WebSphere Full Profile, Tomcat, JBOSS, or WebLogic to the Liberty profile are covered in detail. We made some modifications to the database access practices of the Redbook version, and we have set it up to use a local Apache Derby database, so be sure to use the version of the application that pertains to this tutorial.

After some initial setup, we start by running the migration analysis tooling. We then migrate the application to the Liberty for Java runtime on Bluemix, using the SQL Database service in Bluemix for the database, as shown in the following figure.

Image showing migration steps
Image showing migration steps

What you'll need to build your application

Run the appGet the code

Step 1. Download the application

Throughout this series, we provide sample applications to use, and we recommend using them to get comfortable with the steps and the tooling. You can then follow these same steps for your own application.

  1. The sample Tomcat application code, RedbookLibrary code (with our enhancements), is available as a GitHub repository.
  2. From the command line, perform a git clone of this repository. We'll work within the directory that is created:
    git clone

Step 2. Install the Cloud Foundry API tooling

IBM Bluemix supports the Cloud Foundry API. Therefore, you have complete flexibility in how you develop your Java application. In this tutorial, we show you how to use the command line. (For those of you who already use Eclipse, or are looking for a more integrated IDE experience, Part 2 will describe how to use Eclipse and will cover the Liberty for Java Bluemix Migration plugin and the Bluemix deployment plugin.)

  1. Download and install the Cloud Foundry command-line interface from the GitHub website.

Step 3. Install and run the command-line migration analysis tooling

IBM provides migration analysis tools to help determine how easily an application will port to Bluemix. The first tool is a binary assessment tool, which we will run here from the command line. The second tool provides more in-depth analysis, but requires the source code and Eclipse. It will be covered in Part 2.

  1. Download the binary assessment tool.
  2. Install the tool by entering java -jar binaryAppScannerInstaller.jar.
  3. After the tool is installed, go to the wamt subdirectory.
  4. Run the analysis from the wamt subdirectory by entering:
    java -jar binaryAppScanner.jar \directory-containing-war-file.

    The directory will be <git_clone_location>\RedbookLibrary, such as c:\\users\ibm_admin\RedbookLibrary.

    Screen shot of command line running     analysis program
    Screen shot of command line running analysis program
  5. The previous command gives you the high-level technology analysis results (in HTML).Screenshot showing application evaluation report
    Screenshot showing application evaluation report
  6. Next, you can run a detailed analysis report in HTML, which highlights potential issues as you move to the cloud, files, and line numbers. It also includes reference material for handling these problems. From the wamt subdirectory, enter:
    java -jar binaryAppScanner.jar \directory-containing-war-file --analyzeMigrationDetails --targetAppServer=bluemixScreenshot of command line     showing running detailed analysis report
    Screenshot of command line showing running detailed analysis report

Step 4. Analyze results to choose your deployment topology

The tech preview of the binary scanner provides important analysis information for our application.

  1. In the Application Evaluation Report (shown above), under "Web application technologies," we see that this application uses Servlet and JSP. This is, of course, not surprising for a Tomcat application. All the technologies will migrate to the Liberty for Java on Bluemix, as shown in column 1.
  2. Under "Java EE-related specifications in Java SE," we see that the application uses Java Database Connectivity (JDBC). This application will also run in Liberty for Java on IBM Bluemix. However, this high-level analysis showing that the application uses JDBC indicates we will need to decide how to handle the database.
  3. The detailed analysis gives us even more information. (See the next few figures.) In fact, this report might be a little scary when you first look at it. Fortunately, most of the areas flagged are from the local Derby database we used with Tomcat and don't apply when we move to the cloud. You can easily see the rules that are flagged from Derby files by looking at the File name detail.Screenshot showing example of file name detail
    Screenshot showing example of file name detail
  4. After we eliminate the issues coming from the files with Derby, the rules that we need to pay attention to for our cloud migration are Capture log information, HTTP session persistence, and Use SQL Database service. Screenshot of detailed results by rule
    Screenshot of detailed results by rule
  5. For the database, we recommend using the SQL Database service in Bluemix (see the following figure). Here in Part 1 that is exactly what we will do. We show you how to use a database in the cloud, using the SQL Database Service in Bluemix. Later in the series, we show how to use the Secure Gateway capabilities to connect to your existing database.Screenshot showing recommendation to use SQL Database Service
    Screenshot showing recommendation to use SQL Database Service
  6. The report also flags Capture Log Information as something to check for our application. When we look at the help, we see:

    "Applications can log to System.err/System.out so that Cloud Foundry's Loggregator component picks up the log entries. Using Loggregator, you can tail application logs and dump a recent set of application logs."

    In our application, we're using the standard Java logging facility and also logging to the default location, which is System.out. So log entries are automatically picked up by the Loggregator.

    Screenshot showing Capture Log     Information
    Screenshot showing Capture Log Information
  7. Finally, the report flags session persistence in the cloud. This one we do need to pay attention to, but not here in Part 1 where we aren't doing any clustering. A later tutorial in this series will incorporate session caching and clustering.

Step 5. Create your database service

We are choosing to use a database in the cloud, so next we need to create the database service to use. This can be done through the IBM Bluemix dashboard or through the command line. We'll continue to use the command line in this tutorial. After the database is created, we deploy the application and bind to the database. But before we create the database, we first need to talk about how the application will be deployed and how it will use the database.

A best practice in Cloud Foundry is to use what's called a manifest.yml file when deploying your applications. A manifest.yml file is similar to the idea of a manifest file in a Java JAR or WAR file. It is information that helps the Cloud Foundry tooling understand how your application is constructed.

Manifests are written in YAML. You need to know only two aspects of YAML to read this file:

  • Keys are separated from values by a colon and a space.
  • A new element in a list is indicated by a hyphen and a space.

Let's look at the manifest.yml file that is provided with the sample application.

  1. In your RedbookLibrary directory, open the manifest.yml file.
    - name: redbooklibrary
      memory: 512M
      path: RedbookLibrary.war
      host: redbook-library
      buildpack: liberty-for-java 
      - library_db
  2. The manifest says that there is a single service in the services: list, named library_db. There are two steps in Cloud Foundry to using a service in an application: (1) create a service instance (which happens only once per space) and (2) bind that service instance to the application (which needs to happen for each application in the space). So, for this application, we need to create a service that is called "library_db." We can create this service from the Cloud Foundry command line. From the command line, type:
    cf login
  3. The database service that we will use is sqldb. We create a service instance to use the free trial plan, and name the service that the application needs "library_db."
    cf create-service sqldb sqldb_free library_db
  4. Now that the service is created (but not yet bound), if you wanted to, you could either go look in the Bluemix GUI and validate that it is available inside your space, or you could type
    cf services
    and validate that "library_db" is inside the list of services that are defined for your space.

Step 6. Deploy your application in the cloud

The reason that manifests are important is that the elements we just covered are all things that you would need to have defined through command-line parameters or other commands to the Cloud Foundry command-line tool. By placing all of this information in the manifest, you're not writing a long command of the full form with all the parameters to cf push each time you deploy. Instead, you're just putting the information in the manifest.yml once, and reusing it for each deployment.

We want our application to use our newly created library_db service on Bluemix, which means that our application needs to be properly configured. One of the nice capabilities of the Liberty for Java Buildpack is that it includes capabilities to automatically configure bound services. This makes porting an application to the Liberty for Java Buildpack on Bluemix much easier.

We are deliberately setting up our application to take advantage of the automatic configuration capabilities. One of the things that makes it a challenge to follow some Java examples that are written for Bluemix is that many examples deviate from JEE coding best practices and don't use the automatic technique. Instead, they take advantage of the fact that programs in Bluemix can receive services information (URLs, users, and passwords) about bound services through the VCAP_SERVICES environment variables that Cloud Foundry passes into each runtime. Many Java programs, therefore, contain IF statements that look for those environment variables and then, from the values in those variables, set the appropriate parameters to the necessary service invocation code (such as Database drivers). That, however, defeats the purpose of the way that JEE was designed.

JEE externalizes that kind of detail into an external application server configuration file (such as the server.xml file that is used in WebSphere Liberty Profile) so that the program code needs only an abstract reference to the service through JNDI. For instance, let's say that we have a servlet that wants to access JDBC DataSource. In JEE, that's commonly done by using a Resource annotation of the form:
@Resource(name = "jdbc/library_db")

In classes that are not JEE objects (for example, servlets or EJBs), you can use standard JNDI lookups to obtain references:
(DataSource) ic.lookup("java:comp/env/jdbc/library_db");

Now, where this meets up with the Liberty Profile is that the Liberty Profile Buildpack for Bluemix automatically configures these by writing a server.xml file for the Liberty server it creates for you. That server.xml file contains the appropriate stanzas to do the binding, automatically creating a JNDI binding of the form:
<type, e.g. "jdbc">/service_name
for each service that is bound to your Liberty application. Because we bound an SQL Database service instance named "library_db" to our application with the manifest file, the Liberty Buildpack automatically binds that instance to any @Resource statement or JNDI lookup of the type above looking for that particular JDNI name.

There's an entire list of services that the Liberty Buildpack automatically makes this connection for. Those services include the SQL Database (which we use in this example), MYSQL, PostreSQL, MQLight, Cloudant, and many other databases and services. For the full list, see the Liberty Buildpack documentation.

So the good news is that you don't have to worry about binding in the services for most programs you write in Java code! That drastically simplifies the set of things you must do to make your programs run.

To see how Bluemix creates the server.xml file for Liberty, select a Java Liberty application that is deployed in Bluemix, select Files and Logs in the dashboard, and then navigate to app/wlp/usr/servers/defaultServer/server.xml

Now you're ready to deploy your application. Because we're using manifests, it's simple!

  1. From the command line, type cf push -n <NEWHOST>, where <NEWHOST> is a name that you define for the "route" that the application will be available on. (A route is equivalent to a subdomain. For example, if you use redbook-library-abc, where abc are your initials, then your application will be available at         showing
    Screenshot showing
  2. Your application is deployed and automatically bound to the library_db service instance. You can access your running application through the browser at http://<NEWHOST> Your application should look like this:Screenshot         showing welcome page of app
    Screenshot showing welcome page of app

Step 7. Test your application

Ideally, you would have automated test cases that you can run to verify that your application is working. For this application, we don't have that luxury, so here are the steps to make sure it's working.

  1. With your browser, go to the home page of your application (for example, Click Build The Databases. Use your browser's back button to return to the home page.
  2. Click Populate the Database with test data. Use your browser's back button to return to the home page.
  3. Log in as user1 / password1.
  4. Check that the results look like this:Screenshot showing home page of app
    Screenshot showing home page of app
  5. Enter your choice of colors for the color scheme, and click Set. We thought black on purple looked really nice.Screenshot showing color selection
    Screenshot showing color selection
  6. You can also look at Bluemix and SQLDB through their user interfaces. Log in to
  7. In the dashboard, find your RedbookLibrary. You should see that it is using the liberty-for-java buildpack and is running. Screenshot showing Bluemix dashboard
    Screenshot showing Bluemix dashboard
  8. Click redbooklibrary. You should see that the SQL Database service is bound to the application. Click Launch to open the SQL Database UI, and click Work with Tables. You can then explore the tables and the data.Screenshot showing tables
    Screenshot showing tables

Step 8: Cleaning up after yourself

Something to remember about Bluemix is that you are charged by the gigabyte-hour! When you're deploying a sample application and trying a new procedure to learn how to apply it in your own applications, it's best to clean up after yourself.

  1. Stop the application: cf stop redbooklibrary.
  2. Unbind the service: cf unbind-service redbooklibrary library-db.
  3. Delete the service: cf delete-service library-db.
  4. Delete the application: cf delete redbooklibrary. (Note, answer y when asked if you really want to delete the app and the service.)

Step 9 (optional). Deploy your application to the Cloud Foundry Java buildpack (Tomcat)

As we mentioned earlier, IBM Bluemix supports the Liberty for Java runtime, and also includes the Cloud Foundry Java buildpack, with Tomcat 8.0.21. If you prefer to continue using Tomcat, you can easily deploy your application using the Java buildpack instead. The only change is to update the -b target buildpack in the manifest file. For your convenience, we have included a second manifest file with the appropriate changes.

  1. Log in to Bluemix from the command line: cf login.
  2. Delete your existing manifest.yml file and rename the manifest.tomcat file to manifest.yml. (Don't worry, manifest.liberty is the same as the original manifest.yml.) The Tomcat version of the manifest file is slightly different from the Liberty version we examined earlier. First, the buildpack points to the Cloud Foundry java_buildpack (which contains Tomcat). Second, the manifest does not contain a service section, because the Tomcat version uses the in-memory Derby database whose JAR file is entirely contained within the RedbookLibrary WAR file.
  3. Deploy your application to the Java buildpack. For example:
    cf push -n NEWHOST-TOMCAT
  4. Test your application as you did in Step 7. You can also use the Bluemix user interface, where you should see that the application is bound to the java_buildpack instead.Screenshot         showing Bluemix user interface
    Screenshot showing Bluemix user interface
  5. Clean up your application with the following commands:
    cf stop redbookLibrary
    cf delete redbookLibrary

If you want to use SQL Database with your Tomcat application, there are additional steps that you need to do for resource configuration. The java_buildpack does not have the automatic capabilities for database binding that we used with the Liberty for Java buildpack. This is one of the advantages to using the Liberty for Java buildpack on Bluemix. For more information on why you might choose the Liberty for Java buildpack, see "WAS classic or WAS Liberty: How to choose,," which discusses many of the features now available in Liberty.


In this tutorial, we looked at the different options available for migrating Java applications to the cloud. We covered the key considerations for the runtime services as well as tooling. Then, we showed you step by step how to use command-line tooling to analyze and migrate a Tomcat application to either the Liberty for Java runtime or the Cloud Foundry Java buildpack. The next tutorial in the series will show you how to use Eclipse to migrate a Java application.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Cloud computing, Java development
ArticleTitle=Move your Java application into a hybrid cloud using Bluemix, Part 1