back to all blogsSee all blog posts

Try out Eclipse Cargo Tracker, an enterprise-level Jakarta EE application, with Open Liberty

image of author
Chanun Ong on Aug 24, 2022
Post available in languages:

As one of the top Java framework choices for enterprise-level applications, Jakarta EE is at the center of projects all over the globe. The Eclipse Cargo Tracker open-source application was designed to replicate a complex enterprise application by using core Jakarta EE features with professional development standards. Now, you can get a taste of Open Liberty in an industrial environment by running Cargo Tracker with an Open Liberty server, all on your own computer.

The Cargo Tracker application

Cargo Tracker simulates an industrially-developed freight tracking web application built with Jakarta EE 8 and domain-driven design principles. The application uses key Jakarta EE features, including Faces, CDI, Enterprise Beans, Bean Validation, RESTful Web Services, and JSON Binding. It also uses Persistence, along with Batch and Messaging.

Cargo Tracker books, tracks, updates, and routes cargo objects. Messaging events are logged to update cargo locations, while persistence ensures that cargo status is not changed or removed when the application is shut down. Each portion of Cargo Tracker represents a step in a real-life shipment process: the customer tracks their cargo using the Public Tracking interface, the shipping company schedules and routes deliveries using the Administration interface, and port handlers log arriving and departing cargo using the Mobile Event Logger.

Cargo Tracker Home Page
Cargo Tracker Map

Try out Cargo Tracker with Open Liberty

Feel free to give Cargo Tracker with Open Liberty a try on your own! Cargo Tracker supports Java SE 8, 11, and 17. IBM Semeru Runtime is the preferred Java runtime when using Open Liberty. Before you clone the application to your machine, install any required JDKs and ensure that your JAVA_HOME system variable is set to a compatible version. To access the repository remotely you’ll need to install Git if you haven’t already. Finally, you will need to install Maven to build and run the application.

You can clone the Open Liberty branch of the Cargo Tracker project to your local machine by running:

git clone https://github.com/eclipse-ee4j/cargotracker.git -b liberty-experimental

You can also visit the Git repository for the Open Liberty branch of the Cargo Tracker project to take a peek at the code.

To get started, choose one of the following setup methods:

Maven command line setup

After cloning the project, you can quickly start Cargo Tracker through the command line with Maven. Navigate to the project base directory (where the pom.xml file is located) and run:

mvn -P openliberty liberty:dev

The application should start without any thrown exceptions. Startup messages, such as the message-driven bean activation warnings, are cosmetic and can be safely ignored.

Cargo Tracker Maven Output

Eclipse IDE setup

You’ll need Eclipse IDE version 2022-03 or later to run the application. Either the "Eclipse IDE for Java Developers" or "Eclipse IDE for Enterprise Java and Web Developers" package will work.

After you clone the project, import it into Eclipse by selecting the File menu and then Import. Choose the Existing Maven Projects option inside the Import menu.

Cargo Tracker Eclipse Import

In the next step, select the repository base folder as the root directory and check the pom.xml under the Maven Projects tab. Select Finish to complete the import process.

Cargo Tracker Eclipse Configuration

If you’re working inside the Eclipse IDE, you’ll need to install IBM’s Liberty Tools feature. Follow the steps in the installation guide to access some convenient new resources and operations that are specific to Liberty. This blog post covers the feature’s capabilities in more detail, but for now we’ll focus on the Liberty Dashboard.

To run Cargo Tracker, right-click the cargo-tracker project and select the Start…​ option, which is second in the list.

Cargo Tracker Eclipse Start

You can then run dev mode with the Open Liberty profile active by typing in -Popenliberty.

Cargo Tracker Eclipse Parameters

After starting with the custom parameters for the Open Liberty profile, the application should start inside the Eclipse terminal.

Avoid trouble - set environment variables

Since the Liberty Tools feature uses the well-known environment variables: PATH and JAVA_HOME, you will encounter problems if these variables are not set within your Eclipse IDE process, e.g. the mvn executable might not be found.

One tip to address this on Mac OS in particular is to restart Eclipse through Finder by right-clicking your Eclipse application and choosing Show Package Contents. Enter the newly displayed Contents folder, select MacOS, and then run Eclipse by clicking the executable.

Cargo Tracker Eclipse MacOS

Access the application

Once the application is running, you can access it through a browser of your choice at http://localhost:8080/cargo-tracker/ and start experimenting with it. You can track routed cargo through the Public Tracking interface, book and route cargo through the Administration interface (shown in the following image), and update cargo object events using the Mobile Event Logger. You can stop the server at any time by using CTRL-C.

Cargo Tracker Dashboard

For more information about of each of the interfaces, can check out the Exploring the Application section of the project README.

The README.md also contains step by step instructions for starting the application along with detailed explanations for each of the interface options on the home page.

Nice work! Where to next?

You’ve just set up Cargo Tracker and experienced Open Liberty with an enterprise-level application on your own machine! Check out the Open Liberty guides for more information on using Jakarta EE and MicroProfile with Open Liberty.