{"id":31375019,"url":"https://github.com/eclipse-ee4j/cargotracker","last_synced_at":"2025-09-28T01:02:19.195Z","repository":{"id":38050461,"uuid":"208272383","full_name":"eclipse-ee4j/cargotracker","owner":"eclipse-ee4j","description":"The project demonstrates how you can develop applications with Jakarta EE using widely adopted architectural best practices like Domain-Driven Design (DDD).","archived":false,"fork":false,"pushed_at":"2025-03-28T18:12:07.000Z","size":85042,"stargazers_count":363,"open_issues_count":11,"forks_count":162,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-08-15T00:53:43.473Z","etag":null,"topics":["ddd","domain-driven-design","jakartaee","java","javaee"],"latest_commit_sha":null,"homepage":"https://eclipse-ee4j.github.io/cargotracker/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-ee4j.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-13T13:40:45.000Z","updated_at":"2025-08-13T11:20:45.000Z","dependencies_parsed_at":"2023-02-06T09:32:07.549Z","dependency_job_id":"10986c2e-2b8a-414c-9c2d-df5c141d17d1","html_url":"https://github.com/eclipse-ee4j/cargotracker","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-ee4j/cargotracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ee4j%2Fcargotracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ee4j%2Fcargotracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ee4j%2Fcargotracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ee4j%2Fcargotracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-ee4j","download_url":"https://codeload.github.com/eclipse-ee4j/cargotracker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ee4j%2Fcargotracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277311263,"owners_count":25796892,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ddd","domain-driven-design","jakartaee","java","javaee"],"created_at":"2025-09-28T01:01:30.867Z","updated_at":"2025-09-28T01:02:19.174Z","avatar_url":"https://github.com/eclipse-ee4j.png","language":"JavaScript","readme":"# Eclipse Cargo Tracker - Applied Domain-Driven Design Blueprints for Jakarta EE\r\n\r\nThe project demonstrates how you can develop applications with Jakarta EE using widely adopted architectural best \r\npractices like Domain-Driven Design (DDD). The project is based on the well-known [Java DDD sample application](https://github.com/citerus/dddsample-core) \r\ndeveloped by DDD pioneer Eric Evans' company Domain Language and the Swedish software consulting company Citerus. \r\nThe cargo example actually comes from Eric Evans' seminal book on DDD.\r\n\r\nThe application is an end-to-end system for keeping track of shipping cargo. It\r\nhas several interfaces described in the following sections.\r\n\r\nFor further details on the project, please visit: https://eclipse-ee4j.github.io/cargotracker/.\r\n\r\nA slide deck introducing the fundamentals of the project is available on the official Eclipse\r\nFoundation [Jakarta EE SlideShare account](https://www.slideshare.net/Jakarta_EE/applied-domaindriven-design-blueprints-for-jakarta-ee). A recording of the slide deck is available on the official [Jakarta EE YouTube account](https://www.youtube.com/watch?v=pKmmZd-3mhA).\r\n\r\n![Eclipse Cargo Tracker cover](cargo_tracker_cover.png)\r\n\r\n## Getting Started\r\n\r\nThe [project website](https://eclipse-ee4j.github.io/cargotracker/) has detailed information on how to get started.\r\n\r\nThe simplest steps are the following (no IDE required):\r\n\r\n* Get the project source code.\r\n* Ensure you are running Java SE 11 or Java SE 17.\r\n* Make sure JAVA_HOME is set.\r\n* Navigate to the project source root and type:\r\n```\r\n./mvnw clean package cargo:run\r\n```\r\n* Go to http://localhost:8080/cargo-tracker\r\n\r\nThis will run the application with Payara Server by default. The project also has Maven profiles to support GlassFish \r\nand Open Liberty. For example, you can run using GlassFish using the following command: \r\n\r\n```\r\n./mvnw clean package -Pglassfish cargo:run\r\n```\r\n\r\nSimilarly, you can run using Open Liberty using the following command:\r\n\r\n```\r\n./mvnw clean package -Popenliberty liberty:run\r\n```\r\n\r\nTo set up in Visual Studio Code, follow these steps:\r\n\r\n* Set up Java SE 11, or Java SE 17, [Visual Studio Code](https://code.visualstudio.com/download) and [Payara 6](https://www.payara.fish/downloads/payara-platform-community-edition/). You will also need to set up the [Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) and [Payara Tools](https://marketplace.visualstudio.com/items?itemName=Payara.payara-vscode) in Visual Studio Code.\r\n* Make sure JAVA_HOME is set.\r\n* Open the directory that contains the code in Visual Studio Code. Visual Studio Code will do the rest for you, it should automatically configure a Maven project. Proceed with clean/building the application.\r\n* After the project is built (which will take a while the very first time as Maven downloads dependencies), simply run the generated `cargo-tracker.war` file under the `target` directory using Payara Tools.\r\n\r\nYou can similarly use GlassFish or Open Liberty in Visual Studio Code or Eclipse IDE for Enterprise and Web Developers.\r\n\r\n## Exploring the Application\r\n\r\nAfter the application runs, it will be available at:\r\nhttp://localhost:8080/cargo-tracker/. Under the hood, the application uses a\r\nnumber of Jakarta EE features including Faces, CDI, Enterprise Beans, Persistence, REST, Batch, JSON Binding, Bean Validation and Messaging.\r\n\r\nThere are several web interfaces, REST interfaces and a file system scanning\r\ninterface. It's probably best to start exploring the interfaces in the rough\r\norder below.\r\n\r\nThe tracking interface lets you track the status of cargo and is\r\nintended for the public. Try entering a tracking ID like ABC123 (the\r\napplication is pre-populated with some sample data).\r\n\r\nThe administrative interface is intended for the shipping company that manages\r\ncargo. The landing page of the interface is a dashboard providing an overall\r\nview of registered cargo. You can book cargo using the booking interface.\r\nOnce cargo is booked, you can route it. When you initiate a routing request,\r\nthe system will determine routes that might work for the cargo. Once you select\r\na route, the cargo will be ready to process handling events at the port. You can\r\nalso change the destination for cargo if needed or track cargo.\r\n\r\nThe Handling Event Logging interface is intended for port personnel registering what\r\nhappened to cargo. The interface is primarily intended for mobile devices, but\r\nyou can use it via a desktop browser. The interface is accessible at this URL: \r\nhttp://localhost:8080/cargo-tracker/event-logger/index.xhtml. For convenience, you\r\ncould use a mobile emulator instead of an actual mobile device. Generally speaking cargo\r\ngoes through these events:\r\n\r\n* It's received at the origin location.\r\n* It's loaded and unloaded onto voyages on its itinerary.\r\n* It's claimed at its destination location.\r\n* It may go through customs at arbitrary points.\r\n\r\nWhile filling out the event registration form, it's best to have the itinerary handy. You can access the itinerary for \r\nregistered cargo via the admin interface. The cargo handling is done via Messaging for scalability. While using the \r\nevent logger, note that only the load and unload events require as associated voyage.\r\n\r\nYou should also explore the file system based bulk event registration interface.\r\nIt reads files under /tmp/uploads. The files are just CSV files. A sample CSV\r\nfile is available under [src/test/sample/handling_events.csv](src/test/sample/handling_events.csv). The sample is already set up to match the remaining \r\nitinerary events for cargo ABC123. Just make sure to update the times in the first column of the sample CSV file to \r\nmatch the itinerary as well.\r\n\r\nSuccessfully processed entries are archived under /tmp/archive. Any failed records are\r\narchived under /tmp/failed.\r\n\r\nDon't worry about making mistakes. The application is intended to be fairly\r\nerror tolerant. If you do come across issues, you should [report them](https://github.com/eclipse-ee4j/cargotracker/issues).\r\n\r\nYou can simply remove ./cargo-tracker-data from the file system to restart fresh. This directory will typically be \r\nunder $your-payara-installation/glassfish/domains/domain1/config.\r\n\r\nYou can also use the soapUI scripts included in the source code to explore the\r\nREST interfaces as well as the numerous unit tests covering the code base\r\ngenerally. Some of the tests use Arquillian.\r\n\r\n## Exploring the Code\r\n\r\nAs mentioned earlier, the real point of the application is demonstrating how to\r\ncreate well architected, effective Jakarta EE applications. To that end, once you\r\nhave gotten some familiarity with the application functionality the next thing\r\nto do is to dig right into the code.\r\n\r\nDDD is a key aspect of the architecture, so it's important to get at least a\r\nworking understanding of DDD. As the name implies, Domain-Driven Design is an\r\napproach to software design and development that focuses on the core domain and\r\ndomain logic.\r\n\r\nFor the most part, it's fine if you are new to Jakarta EE. As long as you have a\r\nbasic understanding of server-side applications, the code should be good enough to get started. For learning Jakarta EE \r\nfurther, we have recommended a few links in the resources section of the project site. Of\r\ncourse, the ideal user of the project is someone who has a basic working\r\nunderstanding of both Jakarta EE and DDD. Though it's not our goal to become a kitchen\r\nsink example for demonstrating the vast amount of APIs and features in Jakarta EE,\r\nwe do use a very representative set. You'll find that you'll learn a fair amount\r\nby simply digging into the code to see how things are implemented.\r\n\r\n## Cloud Demo\r\nCargo Tracker is deployed to Kubernetes on the cloud using GitHub Actions workflows. You can find the demo deployment on \r\nthe Scaleforce cloud (https://cargo-tracker.j.scaleforce.net). This project is very thankful to our sponsors [Jelastic](https://jelastic.com) \r\nand [Scaleforce](https://www.scaleforce.net) for hosting the demo! The deployment and all the data is refreshed nightly. On the cloud Cargo Tracker \r\nuses PostgreSQL as the database. The [GitHub Container Registry](https://ghcr.io/eclipse-ee4j/cargo-tracker) is used to publish Docker images.\r\n\r\n## Jakarta EE 8\r\nA Jakarta EE 8, Java SE 8, Payara 5 version of Cargo Tracker is available under the ['jakartaee8' branch](https://github.com/eclipse-ee4j/cargotracker/tree/jakartaee8).\r\n\r\n## Java EE 7\r\nA Java EE 7, Java SE 8, Payara 4.1 version of Cargo Tracker is available under the ['javaee7' branch](https://github.com/eclipse-ee4j/cargotracker/tree/javaee7).\r\n\r\n## Contributing\r\nThis project complies with the Google Style Guides for [Java](https://google.github.io/styleguide/javaguide.html), [JavaScript](https://google.github.io/styleguide/jsguide.html), and [HTML/CSS](https://google.github.io/styleguide/htmlcssguide.html). \r\nYou can use the [google-java-format](https://github.com/google/google-java-format) tool to help you comply with the Google Java Style Guide. You can use the \r\ntool with most major IDEs such as Eclipse, Visual Studio Code, and IntelliJ.\r\n\r\nIn general for all files we use a column/line width of 80 whenever possible, and we use 2 spaces for indentation. \r\nAll files must end with a new line. Please adjust the formatting settings of your IDE accordingly. You are encouraged \r\nbut not required to use HTML Tidy and CSS Tidy to help format your code.\r\n\r\nFor further guidance on contributing including the project roadmap, please look [here](CONTRIBUTING.md).\r\n\r\n## Known Issues\r\n* When using Visual Studio Code, please make sure that the JAVA_HOME environment variable is correctly set up. If it is not configured properly, you will be unable to select a domain when adding a Payara Server instance in Visual Studio Code.\r\n* When using Visual Studio Code, please make sure that Payara is not installed in a path with a space (for example: C:\\Program Files\\payara6). Payara will fail to start with the Payara Tools extension. Install Payara on a path without spaces (for example: C:\\payara6).\r\n* You may get a log message stating that Payara SSL certificates have expired. This won't get in the way of functionality, but it will\r\n  stop log messages from being printed to the IDE console. You can solve this issue by manually removing the expired certificates from the Payara domain, as\r\n  explained [here](https://github.com/payara/Payara/issues/3038).\r\n* If you restart the application a few times, you will run into a bug causing a spurious deployment failure. While the problem can be annoying, it's harmless. Just re-run the application (make sure to completely un-deploy the application and shut down Payara first).\r\n* Sometimes when the server is not shut down correctly or there is a locking/permissions issue, the H2 database that\r\n  the application uses gets corrupted, resulting in strange database errors. If\r\n  this occurs, you will need to stop the application and clean the database. You\r\n  can do this by simply removing the cargo-tracker-data directory from the file\r\n  system and restarting the application. This directory will typically be under $your-payara-installation/glassfish/domains/domain1/config.\r\n* While using GlassFish, if tests fail with a `CIRCULAR REFERENCE` error, it means GlassFish start up timed out. The default timeout is 60 seconds. This may not be\r\n  enough on some systems, especially if virus scanners like Windows Defender are delaying GlassFish start up. You can increase GlassFish start up timeout\r\n  by setting the `AS_START_TIMEOUT` environment variable. For example, you can set it to 180000 for a 3 minute timeout.\r\n* While running with Open Liberty, you will notice a number of spurious errors. You will see shrinkwrap features warnings, message-driven bean warnings, the AggregateObjectMapping nested foreign key warning, I/O errors, etc. You can safely ignore these. They don't affect the application functionality.\r\n","funding_links":[],"categories":["Jakarta EE Examples"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-ee4j%2Fcargotracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-ee4j%2Fcargotracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-ee4j%2Fcargotracker/lists"}