Archived | Refactor existing monolithic applications to microservices one bite at a time, Part 1: Migrating the Liberty version

Archived content

Archive date: 2019-05-22

This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.


For most new applications, microservices is the architecture of choice of many organizations. These organizations are starting to examine how they can refactor their existing monolithic Java applications into microservices to make them more flexible and agile without starting from scratch. Monoliths were designed not just for single tasks, but also to perform every step that is needed to complete a particular function. The size and complexity of monolithic applications are the result of numerous inter-related pieces of code and data models, which can be overwhelming to developers when they start refactoring. They might dive straight into changing code, where one monolith becomes 10 or 20 smaller monoliths. As a result, the developer can’t be sure whether the issues in testing are related to the migration to the cloud or the refactoring process.

This article series breaks down the complex problem of refactoring monoliths into microservices step-by-step. You learn how to implement a systematic approach to refactor your monolithic applications and how to use the tools and techniques to help you along that journey. You see how to migrate the monolith to microservices and then run that monolith in the cloud. The target cloud platforms are Docker Containers in IBM Cloud Private on-premises and Cloud Foundry in the IBM Cloud Public.

In Part 1 of this series, you migrate the Daytrader3 application from IBM® WebSphere® Application Server Liberty to Liberty After you migrate the application, you then deploy and run it on premises. This step is important to ensure that your application is at the latest version before you move it to the cloud. During this step, you might also want to eliminate other areas of technical debt, such as upgrading your open source libraries or upgrading your Java Enterprise Edition (Java EE) specification levels. Keep these changes to a minimum so that you do not introduce too much risk. By doing so, you can move your workloads to the cloud and benefit from cloud economics sooner, rather than later.


Set up the development environment

To set up the development environment, you must complete the following steps:

  1. Download and install the Liberty kernel.
  2. Download and install the Daytrader3 application.
  3. Configure Eclipse IDE for Java EE Developers.

Download and install the Liberty kernel

The Liberty server process comprises a single Java virtual machine (JVM)–the Liberty kernel–and various optional features. The kernel does not provide any features by itself, but you can add features to it. By using the installUtility command of the Liberty kernel, you can use the bin/installUtility command to create your own server from the kernel with the features that you need.

  1. Download the Liberty kernel.
  2. Extract the Liberty kernel into a local folder. We refer to this path as %HOMEPATH%.

Download and install the Daytrader3 application

IBM provides a packaged Liberty server that contains everything that is required to run the Daytrader3 application. In this step, you download the packaged server and then extract it.

  1. Download the Daytrader3Sample.jar file, and place it in the Liberty bin folder, for example: %HOMEPATH%\wlp\bin.

    The Daytrader3Sample.jar file is a packaged Liberty server. The following figure shows the structure of the Java archive (JAR) file.

    Structure of the Daytrader3Sample.jar file

    The Daytrader3Sample.jar file contains the Daytrader3Sample server that is configured with the features that are required to run the Daytrader3 application. The JAR file also contains the Daytrader3 application (daytrader3-ee6.ear file), which includes the source code. In addition, the JAR file includes the externaldependencies.xml file, which is used to download the Derby database that the application uses.

  2. Install the Daytrader3Sample.jar file from the command line by using the installUtility command.

    1. At a command prompt, go to the Liberty/bin directory, for example: %HOMEPATH%\wlp\bin.
    2. Enter the following command:

      installUtility install DayTrader3Sample

    3. When prompted, accept the terms of the license agreement, and click Yes to download the Derby prerequisite dependencies.

      The following figure shows the artifacts that this process generates.

      Artifacts generated by the installUtility command

Configure Eclipse IDE for Java EE Developers

  1. Open Eclipse, and create a workspace with the name daytrader3-wtp.
  2. Install WebSphere Developer Tools from WASdev. Then, follow the prompts to complete the installation.
  3. Install WebSphere Application Server Migration Toolkit from WASdev. Then, follow the prompts to complete the installation.
  4. Create a Liberty runtime environment:

    1. In Eclipse, click Window -> Preferences -> Server -> Runtime Environment.
    2. Add a server. Click Add, and then select IBM -> WebSphere Application Server Liberty.
    3. In the Specify the runtime environment creation and JRE window, enter the name (WLP-, and select an existing installation (%HOMEPATH%\wlp).

      Configuring the Liberty runtime environment

  5. In the next window, click Finish, and then click OK.
  6. Create the Liberty Server:

    1. In Eclipse, click File -> New -> Other -> Server -> Server.
    2. Select the server type (WebSphere Application Server Liberty).
    3. In Choose the type of server to create, enter the server name (Daytrader3Sample), and select a server runtime environment (WLP-
    4. Click Next.

      Configuring the Daytrader3Sample server

  7. In the Liberty Server pane, select the Daytrader3Sample Liberty Server that you extracted earlier. Click Finish.

    Validating the Daytrader3Sample server

Import the code into the Web Tools Platform (Eclipse) projects

The daytrader3-ee6.ear file contains the source and binary files for the application. To import it into Eclipse to establish the application projects:

  1. In Eclipse, click File -> Import -> Java EE -> EAR file.
  2. Enter the daytrader3-ee6.ear file. You can find the file in the %HOMEPATH%\wlp\usr\servers\Daytrader3Sample\dropins directory. Then, click Finish.

By having an enterprise archive (EAR) file with source code, you can easily import the code into Web Tools Platform projects. If you don’t have this file, you can modify your build system to create this EAR file. Alternatively, you can import the code from your source code repository that was used to create the EAR file.

Resolve Java problems

Now that you imported the source for the DayTrader application, you must resolve Java problems so that you can compile the application as ready for deployment.

  1. In Eclipse, select Project -> Clean -> Clean all projects.
  2. Open the Markers view, and expand Java problems.

    The web project uses types and interfaces from the dt-ejb project, which results in several “The import XXX cannot be resolved” Java problems. You can find the important problems to fix by searching for “The import XXX cannot be resolved.”

The following sections examine two of the problems and their solutions.

The import cannot be resolved

To resolve this Java problem, add the dt-ejb project to the Java build path of the web project:

  1. In Eclipse, right-click the web project, and select Properties -> Java Build Path.
  2. On the Projects tab, add the dt-ejb project to the Java Build Path. Then, click OK.

    Setting the Java build path for the web project

The import org.apache.commons cannot be resolved

The dt-ejb project uses classes and interfaces from the Apache commons logging library (apache.commons.logging V1.0.3). The application does not provide this library. Although this same library is available in Liberty, it is not visible to the application. Regardless, an application should not rely on open source libraries from the application server.

The following steps explain how to solve this problem:

  1. Download the file, and extract it to the %HOMEPATH%\downloads directory.
  2. In Eclipse, right-click daytrader3-ee6, and select New -> Folder.
  3. Enter the folder name as lib, and click OK.
  4. Right-click daytrader3-ee6, and select File -> Import -> General -> File System.
  5. Set the From directory to %HOMEPATH%\downloads\commons-logging-1.0.3.
  6. Select the commons-logging.jar file to import.
  7. Set the Into folder to daytrader3-ee6\lib.
  8. Click Finish.

    Importing the commons-logging.jar file

  9. The Apache commons logging library has dependencies on the Log4J file, which create runtime issues if not resolved. You will find these dependencies in the file that is inside the commons-logging.jar file. To resolve this problem, download the log4j-1.2.6.jar and log4j-core-2.8.2.jar files to the %HOMEPATH%\downloads directory.
  10. Rename the log4j-1.2.6.jar file to log4j.jar.
  11. Rename the log4j-core-2.8.2.jar file to log4j-core.jar.

    Renamed log4j JAR files

  12. Copy the log4j.jar and log4j-core.jar files into the daytrader3-ee6\lib directory.

    The daytrader3-ee6 directory with three third-party JAR files

Run the WebSphere Application Server Migration Toolkit

The WebSphere Application Server Migration Toolkit Eclipse plug-in analyzes source code and configuration files for known migration issues. In this step, you use the Migration Toolkit to look for known issues when you migrate from Liberty that is running Java 6 to Liberty that is running Java 8.

  1. In Eclipse, run the WebSphere Application Server Migration Toolkit. Click Run -> Analysis. In the left pane, click Software Analyzer, and then click New.
  2. In the Create, manage, and configurations window:

    1. Enter a suitable name for the configuration.
    2. On the Scope tab, select Analyze entire workspace.
    3. On the Rules tab, for Rule Sets, select WebSphere Application Server Version Migration.
    4. Click Set.

      WebSphere Migration Toolkit configuration page

  3. In the Rule set configuration window, for Source application server, select Liberty, and for Target Java version, select IBM Java 8. Click OK to confirm.

    Rule set configuration

  4. Click Apply, and then click Analyze to begin the code analysis.

The Software Analyzer Results view shows the results. As Figure 12 shows, no additional problems are detected. Therefore, you can now move to the next step to deploy the application.

Software Analyzer Results showing no problems are detected

Deploy the DayTrader application on-premises

  1. In the Enterprise Explorer view, right-click the daytrader3-ee6 file, and select Export -> EAR File.
  2. Click Browse, go to the %HOMEPATH%\wlp\usr\servers\Daytrader3Sample\dropins directory, and select the existing daytrader3-ee6.ear file. Select Overwrite existing file, and click Finish. This step replaces the provided EAR file with the file that you just created.

    Export EAR window

  3. In the Server view, right-click the Daytrader3Sample Liberty Server, and then click Start.

  4. Confirm that the application has started. In the Console view, look for the following message:

    CWWKZ0001I: Application daytrader3 started in XX.XX seconds.

    If the application has not started, resolve any deployment problems, and then redeploy it on-premises.

Run the DayTrader application on-premises

With the application deployed and started (starts by default when you deploy it), populate the sample data and log in to the application to do some trading. To run the application on-premises:

  1. Access the application. Point your browser to http://localhost:9080/daytrader. The following figure shows the home page of the application.

    DayTrader Home page

  2. Click the Configuration tab.

    DayTrader Configuration tab

    1. Click the (Re)-create DayTrader Database Tables and Indexes link. A window opens that shows the progress. When the database is created successfully, close the window, and return to the DayTrader Configuration page.
    2. Click the (Re)-populate DayTrader Database link to generate the sample data. A window opens that shows the progress. In this example, you see that the DayTrader Database is populated with 15,000 user accounts and 10,000 stock quotes. You can update these values by using the Configure DayTrader run-time parameters link on the Configuration tab. When the database is populated, close the window, and return to the DayTrader Configuration page.
    3. Click the Trading & Portfolios link. Accept the default user ID and password, and click Login. You now see a window like the following example that you can use to begin trading.

      DayTrader trading and portfolios

You can download a completed Eclipse workspace for Part 1 from GitHub.


You now migrated the Daytrader3 application from Liberty to Liberty and are ready for Part 2.

The following resources also provide information about refactoring monoliths to microservices, but they do not define a systematic approach nor show how to do it as this series shows: