In September, the comprehensive Eclipse Cargo Tracker exemplar application was updated to target Jakarta EE 10 and to support for key runtimes, including Open Liberty. This means you can now learn about Jakarta EE by running Cargo Tracker with Open Liberty, all on your local machine.
As one of the top Java framework choices for cloud-native enterprise Java applications, Jakarta EE is at the center of projects all over the globe. The open-source Cargo Tracker application was designed to replicate a complex enterprise application by using core Jakarta EE features with professional development standards.
Cargo Tracker simulates an industrially-developed freight tracking web application built with Jakarta EE 10 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.
Run Cargo Tracker with Open Liberty
Cargo Tracker supports Java SE 11 and 17. When working with Open Liberty, you can make use of the IBM Semeru Runtime as your chosen Java runtime. This runtime offers performance benefits from deep technology investment in projects such as Eclipse OpenJ9 and is available across a wide variety of hardware and software platforms. To find out more about IBM Semeru Runtime, see Open Liberty and Semeru Runtimes, cloud-native performance that matters.
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 Cargo Tracker project to your local machine by running:
git clone https://github.com/eclipse-ee4j/cargotracker.git
You can also visit the Git repository the Cargo Tracker project to take a peek at the code.
To get started, choose one of the following setup methods:
Liberty dev mode is used in both setups. Dev mode provides the following three key features, enabling you to quickly and easily develop your experience with Jakarta EE through the Cargo Tracker application:
Automatically detect, recompile, and deploy code changes in your running Liberty.
Unit and integration tests are run on demand when you press
Enterin the command terminal.
Finally, you can attach a debugger to the running Liberty to step through the code.
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 -Popenliberty liberty:dev
The application should start without any thrown exceptions. You can safely ignore the shrinkwrap features warning, message-driven bean warning, and the AggregateObjectMapping nested foreign key warning, as they don’t affect the application functionality.
Visual Studio Code IDE setup
We’d also recommend installing the Liberty Tools for Visual Studio Code extension in your IDE to benefit from the fast and iterative development features it offers directly within the IDE. You can download this extension directly from the VS Code marketplace.
After you start VSCode IDE, open the Cargo Tracker project by selecting Explorer > Open Folder. Select the
cargo-tracker project appears under the
LIBERTY DASHBOARD extension in the Explorer sidebar. To run Cargo Tracker, right-click the
cargo-tracker project and select the Start… option.
You can then run dev mode with the Open Liberty profile active by typing in
-Popenliberty in the pop-up entry field and then press the
After starting with the custom parameter for the Open Liberty profile, a terminal window in the IDE opens and the Liberty Maven plug-in starts the application. Liberty is now running in dev mode. You can safely ignore the shrinkwrap features warning, message-driven bean warning, and the AggregateObjectMapping nested foreign key warning, as they don’t affect the application functionality.
Run unit tests
To ensure the Cargo Tracker application has started successfully, you can run the tests by pressing the
enter/return key from the command-line session where you started dev mode. If the tests pass, you should see a similar output to the following example:
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, and update cargo object events using the Event Logger. You can stop Liberty at any time by pressing
CTRL-C from the command-line session where you started dev mode.
For more information about of each of the interfaces, can check out the Exploring the Application section of the Cargo Tracker project README.
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! To understand the Cargo Tracker application in further detail, you can update the source code or use the debugger to step through the code.
Check out the Open Liberty guides for more information and interactive tutorials that walk you through using more Jakarta EE and MicroProfile APIs with Open Liberty.