javaee / cargotracker Goto Github PK

Applied domain-driven design blueprints for Java EE

License: Other

Java 77.50% HTML 20.45% CSS 2.05%

cargotracker's Introduction

================================================================================                            
                              Cargo Tracker
            Applied Domain-Driven Design Blue Prints for Java EE
================================================================================

Overview
========
The project demonstrates how you can develop applications with the Java EE 
platform using widely adopted architectural best practices like Domain-Driven 
Design (DDD), TDD and agile. The project is directly based on the well known 
original Java DDD sample (http://dddsample.sourceforge.net) application 
developed by DDD pioneer Eric Evans' company Domain Language and the Swedish 
software consulting company Citerus. The cargo example actually comes from 
Eric Evans' seminal book on DDD. The original application is written in Spring,
Hibernate and Jetty whereas the application is build entirely on Java EE 7 and
GlassFish 4.  It also supports WildFly 8.

The application is an end-to-end system for keeping track of shipping cargo. It 
has several interfaces described in the following sections.

For further details on the project, please visit:
https://github.com/javaee/cargotracker

Getting Started
===============
The project site has detailed information on how to get started: 
https://java.net/projects/cargotracker/pages/Home, especially with NetBeans:
https://java.net/projects/cargotracker/pages/NetBeans.

The simplest steps are the following (no IDE required):

* Get the project source code: https://java.net/projects/cargotracker/downloads
* As long as you have Maven set up, navigate to the project source root and 
  type: mvn package cargo:run
* To run with WildFly 8x, type: mvn -Pwildfly package cargo:run
* Go to http://localhost:8080/cargo-tracker

To set up in NetBeans, follow these steps:

* Set up JDK 7+, NetBeans 7.3+ and GlassFish 4+ 
  (preferably GlassFish 4.1+ and NetBeans 8.0.1+).
* Open the source code directory in NetBeans - it's just a Maven project, 
  NetBeans will do the rest for you. As noted in the site instructions on
  NetBeans, you may get a few spurious errors due to reported NetBeans bugs.
  Just ignore them and proceed with clean/building the application.
* After the project is built (which will take a while the very first time as 
  Maven downloads dependencies), simply run it via GlassFish 4.
  
It's best to use Chrome for the application since it has the best support for 
HTML 5 forms, but any HTML 5 capable browser is fine. There are some known 
issues due to reported GlassFish 4 bugs - please read the Known Issues section 
below.

Exploring the Application
=========================
After the application runs, it will be available at: 
http://localhost:8080/cargo-tracker/. Under the hood, the application uses a 
number of Java EE (and Java EE 7) features including JSF 2.2, CDI, EJB 3.2, 
JPA 2.1, JAX-RS 2, WebSocket, JSON-P, Bean Validation 1.1 and JMS 2.

There are several web interfaces, REST interfaces and a file system scanning
interface. It's probably best to start exploring the interfaces in the rough
order below.

The tracking interface let's you track the status of cargo and is
intended for the general public. Try entering a tracking ID like ABC123 (the 
application is pre-populated with some sample data).

The administrative interface is intended for the shipping company that manages
cargo. The landing page of the interface is a dashboard providing an overall 
view of registered cargo. The dashboard will update automatically when cargo
is handled (described below). You can book cargo using the booking interface.
One cargo is booked, you can route it. When you initiate a routing request,
the system will determine routes that might work for the cargo. Once you select
a route, the cargo will be ready to process handling events at the port. You can
also change the destination for cargo if needed or track cargo.

The Incident Logging interface is intended for port personnel registering what 
happened to cargo. The interface is primarily intended for mobile devices, but
you can use it via a desktop browser. The interface is accessible at:
http://localhost:8080/cargo-tracker/incident-logger/. For convenience, you
could use a mobile emulator instead of an actual mobile device. On Windows,
you can use Microsoft WebMatrix for device emulation. Generally speaking cargo
goes though these events:

* It's received at the origin port.
* It's loaded and unloaded onto voyages on it's itinerary.
* It's claimed at it's destination port.
* It may go through customs at arbitrary points.

While filling out the event registration form, it's best to have the itinerary 
handy. You can access the itinerary for registered cargo via the admin interface.
As you register handling events, the administrative dashboard will be 
automatically updated in real time without a page refresh in addition to cargo 
state. The cargo handling is done via JMS for scalability and the event 
notification to the system happens via the CDI event bus and WebSocket, so you 
will see a visible delay of a few seconds after registering the event for the
dashboard to update. While using the incident logger, note that only the load 
and unload events require as associated voyage (entering an unnecessary voyage 
for other events will result in an  error).

You should also explore the file system based bulk event registration interface. 
It reads files under /tmp/uploads. The files are just CSV files. A sample CSV
file is available under src/main/resources/handling_events.csv. Sucessfully 
processed entries are archived under /tmp/archive. Any failed records are 
archived under /tmp/failed. Just like the mobile interface, processing events
in bulk will also cause the dashboard to automatically update.

Don't worry about making mistakes. The application is intended to be fairly 
error tolerant. If you do come across issues, you should report them. Please
see the Getting Involved section on how to do so.

NOTE: All data entered is wiped upon application restart, so you can start from 
a blank slate easily if needed.

You can also use the soapUI scripts included in the source code to explore the 
REST interfaces as well as the numerous unit tests covering the code base 
generally.

Exploring the Code
==================
As mentioned earlier, the real point of the application is demonstrating how to 
create well architected, effective Java EE applications. To that end, once you 
have gotten some familiarity with the application functionality the next thing 
to do is to dig right into the code.

DDD is a key aspect of the architecture, so it's important to get at least a 
working understanding of DDD. As the name implies, Domain-Driven Design is an 
approach to software design and development that focuses on the core domain and 
domain logic.

We have a brief overview of DDD specifically as it relates to Java EE on the 
project site: https://java.net/projects/cargotracker/pages/Home. There's also a 
resources page that you should take a look at: 
https://java.net/projects/cargotracker/pages/Resources. The project site has 
pages dedicated to explaining the core constructs of DDD and how they are 
implemented in the application using Java EE: 
https://java.net/projects/cargotracker/pages/Characterization as well as the DDD
layers in the application: https://java.net/projects/cargotracker/pages/Layers.

For the most part, it's fine if you are new to Java EE. As long as you have a
basic understanding of server-side applications, the resources referenced above
and the code should be good enough to get started. For learning Java EE further,
we have recommended a few links in the resources section of the project site. Of 
course, the ideal user of the project is someone who has a basic working 
understanding both Java EE and DDD. Though it's not our goal to become a kitchen 
sink example for demonstrating the vast amount of APIs and features in Java EE,
we do use a very representative set. You'll find that you'll learn a fair amount
by simply digging into the code to see how things are implemented.

Known Issues
============
There are no known issues while running on GlassFish 4.1. For previous versions
you might run into the following issues:

* If you restart the application a few times, you will run into a GlassFish 4 
  bug (https://java.net/jira/browse/GLASSFISH-20616) causing a spurious 
  deployment failure. While the problem can be annoying, it's harmless. Just re-
  run the application (make sure to completely shut down GlassFish first).
* You will see some spurious JSF warnings on some pages due to a GlassFish 
  4/Mojarra bug (https://java.net/jira/browse/GLASSFISH-20244). The error is 
  harmless and can be ignored.
* Sometimes when GlassFish is not shutdown correctly, the Derby database that 
  the application uses get's corrupted, resulting is strange JDBC errors. If 
  this occurs, you will need to stop the application and clean the database. You 
  can do this by simply removing \temp\cargo-tracker-database from the file 
  system and restarting the application.

Getting Involved
================
Cargo Tracker is an open source project hosted on java.net. We would welcome any 
and all contributions.

The project mailing lists are here: https://java.net/projects/cargotracker/lists
The JIRA issue tracker is here: http://java.net/jira/browse/CARGOTRACKER

You can also send an email to [email protected] with any questions, 
concerns or suggestions.

cargotracker's People

Contributors

Stargazers

Watchers

Forkers

ondrejm-demonstrations alexdiazco andeemarks pastorenue jory1110 tkocjan payara coderade keilw danielalejandrohc xinshoushangdao marc-bouvier-forks cosmic-chichu rstrazza oklimanova dario-boberek brbousnguar vivek0739 tlacuache987 tlamatiniisrael aditya86c amir-toly stefanwendelmann cybernetics adoucheali poladgm irukanji74 kelsas adekanmi123 kanmy syunchanp cdeguet abadelt abdelmuniem benh-au ldauvilaire talon1989 ahmedraaj satrapu vladlis amusa kashenfelter samrosi81 mezk lucksonk sanduds physi oleksiy sangkyunyoon oaouda unclesamtech carlos-arodrigues draom renatabk khanhphamngoc jihadbaeth sabbasbraimah dheffelfinger ktollinger jpollard-github anacdf chrissaravillo hmoriya bosseur weliff sairam00 andyglick gauravsir183 axdevelopers rdebusscher xsj24 azizollahi junior300895 yasu0129 edlc bonnibell denis554 dalavancloud pwakumara elizabeth-ts darkobill filipovspas gddimitrow t1nsky bloodydarkness paffkata1914 grimmjow2419 islamailani kirin6666 muheric tanyakoleva 160072 siralexander nagyza yoonation rahjesh ubata-mamezou salvul erik001 aida00

cargotracker's Issues

Mobile client interface should be smarter

The interface should be improved to, for example, suggest 'location codes' and 'voyage numbers' when the user has filled the tracking ID.

Make project work on latest GlassFish build

Make project work on the latest GlassFish build and file bugs as needed.

Expand functionality to add Incident Logging Application

This is a Java SE application in the original DDD sample project. Should be ported over to show Java EE - Java SE/JavaFX/JAX-RS Client integration.

The source for the original Incident Logger is here: http://dddsample.sourceforge.net/download.html

Fix data population restart weakness

Add manual deletes?

POM unloadable in NetBeans

When I open the project (from the SVN repository) in NetBeans 7.3.1, I get the following error:

Some problems were encountered while processing the POMs: [ERROR] 'dependencies.dependency.version' for org.jboss.arquillian.junit:arquillian-junit-container:jar is missing. @line 62, column 21.

This problem is resolved by adding the version number 1.1.0.Final to the arquillian-junit-container dependency element of the POM.

Environment

Windows 7, NetBeans 7.3.1

Livemap need to handle 'unknown location'

Cargo with last location set to unknown are displayed in the middle of the USA.
Either don't display them or display them in a 'parked' area (eg. bottom left)

Environment

uses consistent date format

Some dates uses dd/mm/yyyy (show.xhtml) while others are using yyyy-mm-dd (e.g. incident-logger.xhtml)

Environment

Mac OS X (english with BE local)

NullPointerException when booking a new cargo

Steps to reproduce :

Administrative landing page
Tab "Booking"
Try to book a cargo with any origin, any destination and any arrival deadline (valid one)

=> javax.faces.el.EvaluationException: java.lang.NullPointerException: Country and location may not be null

Environment

Netbeans 8.0
Glassfish 4.0
JDK 7.0

uses consistent date format

Some dates uses dd/mm/yyyy (show.xhtml) while others are using yyyy-mm-dd (e.g. incident-logger.xhtml)

Environment

Mac OS X (english with BE local)

Provide more details when 'registration failed'

When logging an event failed, the only message sent to the user is "registration failed". Is this failure due a domain issue or to a technical issue?
User need to get more useful feedback.

Create Java EE 6 version of application

Frequently requested so most folks can run it on their existing servers, incorporate into their existing applications.

Incorporate continuos integration

Add continuous integration as per DDD practices.

Validating date when booking a cargo

When booking a cargo, if the date is not valid, the application should display an nice jsf message.

Instead, it redirects on the details of the new cargo but this new cargo is not displayed in the list.

Environment

JDK 1.7
Netbeans 8.0
Glassfish 4.0

Document JSF mapping decision

In web.xml, for a Facelets index.xhtml, it is customary to list the welcome file as follows:

faces/index.xhtml

And the servlet-mapping is usually

/faces/*

not

*.xhtml

I can assign myself to this issue and make the fixes if there is no objection.

Integrate JSF 2.2/HTML 5 pass-through forms

Order lists in booking view

Go to http://localhost:8080/cargo-tracker/admin/registration.xhtml

The two lists Origin and Destination are not ordered.
They should be ordered alphabetically.

Environment

Netbeans 8.0
JDK 1.7
Glassfish 4.0

Cargotracker won't cleanly undeploy and redeploy

Usually, when I undeploy the cargotracker application, the following error appears in the server log:

SEVERE: The web application [/cargo-tracker] created a ThreadLocal with key of type [org.glassfish.pfl.dynamic.codegen.impl.CurrentClassLoader$1] (value [org.glassfish.pfl.dynamic.codegen.impl.CurrentClassLoader$1@18df5b39]) and a value of type [org.glassfish.web.loader.WebappClassLoader] (value [WebappClassLoader (delegate=true; repositories=WEB-INF/classes/)]) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak.

I can then clean the project. Rebuilding generally succeeds the first time, too. But when I try to run it, deployment fails. Here is the relevant info from the server log:

INFO: Loading sample data.
INFO: Unloading all existing data.
SEVERE: Exception while invoking class org.glassfish.ejb.startup.EjbApplication start method
javax.ejb.EJBException: javax.ejb.CreateException: Initialization failed for Singleton SampleDataGenerator
...
Caused by: java.lang.IllegalStateException: Attempting to execute an operation on a closed EntityManagerFactory.

I have to stop and restart the database and server to be able to run the app again.

Unable to set cargo as "CLAIMED" or "RECEIVED"

When I tried an end to end use-case, I was able to do event logging of "LOAD", "UNLOAD" for a route.
But, when I do "CLAIM" at the destination, the status change does not happen and the application's dashboard (admin view)
does not show the cargo-item in "claimed" category.

JSF warn message displayed on details of a cargo

Steps to reproduce :

Administrative landing page
Click on Tracking ID ABC123

=> JSF warn message : "The metadata component needs to be nested within a f:metadata tag. Suggestion: enclose the necessary components within <f:metadata>"

Environment

Netbeans 8.0
Glassfish 4.0
JDK 7

Integrate JPA second-level cache

Integrate Apache Cargo

Makes self-contained demos possible.

Design Alternatives - Anti Corruption Layer for Graph Traversal Service

The two main contexts for the CargoTracker Application are the Booking context and the Routing Context. So when the Booking context makes a call to the Routing context via the External Routing Service, it can be done via a separate facade and a translator rather than putting it all into the External Routing Service itself. This helps us change the implementation of the facade if the routing context offers a different protocol for connecting or requires certain additional features for the default protocol supplied.

This Anti Corruption Layer comprises of the Service, the Connector facade and translator and is a possible variant to the open host context relationship. Illustration provided in the attached diagram

Demonstrate solution for lazy-loading

In the application some JPA relations are one-to-many and by default lazy loaded. When fetching the aggregate-root through the repository the returned root object will be detatched. Eclipselink handles this for read operations but Hibernate would throw a LazyInitializationException.

A traditional solution would be to add methods to a DAO such as loadCargoWithLoadedLegs();
With a lot of lazy collections and many combinations this would quickly be a bloated interface.

As a developer I would like to fetch the root, access and make changes to any object in graph, then store the root and have all changes persisted.

Add Java EE Feature Recommendations Section

Add a section explaining higher level Java EE feature choices and recommendations as they pertain to the application (e.g. annotations vs. XML). Need to maintain a balance since API/feature best practices are not the primary focus (as opposed to architectural blueprints/patterns) and the application would not cover large parts of many APIs (as perhaps the samples do).

Alternatively, create API specific sub-projects (or altogether separate projects perhaps leveraging this code base) that focus on technology feature choices/best practices (e.g. best practices for WebSocket, JAX-RS, JPA, EJB, JMS, etc).

Booking with same origin and destination should display a nice jsf message instead of an javax.ejb.EJBException

When booking with same origin and destination, the application throws an error and displays it in the standard exception jsf page :

Caused by: java.lang.IllegalArgumentException: Origin and destination can't be the same: Shanghai [CNSHA]

This exception should be caught and should be display in an nice jsf error message

Environment

Netbeans 8.0
JDK 1.7
Glassfish 4.0

Add SoapUI scripts

Rerouting a Cargo to its destination raise an Exception

'Book Cargo' refuse to book a cargo that has the same Origin and Dest ("Origin and destination cannot be the same").
But this following case is not handled correctly:

"Book Cargo" : A to B
"Change Destination" : B to A (the cargo has now A as both Origin & Dest).
-> EJB Exception Caused by: java.lang.IllegalArgumentException: Origin and destination can't be the same: Chicago [USCH

Change a booked cargo destination to use the original destination fails

"Book a Cargo" (A to B)
"Change Destination" and keep B as destination, click "ok"
-> javax.ejb.EJBException "Caused by: java.lang.IllegalArgumentException: Origin and destination can't be the same: Chicago [USCHI]"

Integrate WebSocket

The current idea is to create a live dashboard with drill-down capabilities showing the location and status of cargo across the globe (and possibly voyage routes).

The problem is that this will use "SSE" only so only a partial use of WebSocket. Other ideas welcome. Chat seems a bit too artificial.

mvn cargo:run throws error on Ubuntu 12

As described in https://java.net/projects/cargotracker/pages/Home#Getting_Started all one needs to do is run the 'mvn cargo:run' command to start the application. I checked out the cargo-tracker source from SVN, and ran 'mvn cargo:run' which downloaded the dependencies, started the glassfish server, but then failed with FileNotFound exception saying that unable to find the cargo-tracker.war file.

I therefore had to run 'mvn package' to create the cargo-tracker.war. After which, 'mvn cargo:run' started the application successfully.

Would be good if we can either fix this as a doc comment or in the deployment, for folks using Ubuntu.

Thanks,
Rahul.

Environment

Ubuntu 12

The JSF pages show errors in NetBeans

The JSF pages contain red icons in the Project Browser when you open the project in NetBeans 7.3.1.

This issue is presumably fixed by using the http://xmlns.jcp.org/jsf namespace instead of the http://java.sun.com/jsf namespace.

Integrate JTA 1.2

Replace session beans?

Incorporate PrimeFaces

Adds some pizzazz, shows power of JSF component ecosystem.

Copy over/ehnance DDD documentation.

Copy over http://dddsample.sourceforge.net/characterization.html, http://dddsample.sourceforge.net/patterns-reference.html and http://dddsample.sourceforge.net/architecture.html - add clarifications/Java EE specific content where sensible.

Integrate JSON-P

Use it for WebSocket services serialization.

Incorporate Apache Commons

Good non-Java EE code integration example.

Secure application

Using Java EE security/JAAS.

Location (origin & dest) sent via WebSocket have a diff. format

Location that are updated via websocket are using a different format (City only) than the 'std' format (City + Port Code).
See last row of attached screenshot

Modularize application

Introduce ear?

Put application on cloud

Figure out a way to save data only per session (multitenacy?). Which cloud service should we use?

Support for different databases

It would be nice to be able to get the application to work with different databases. It doesn't seem to be trivial to get the application to work with Oracle XE for example.

Clean up/complete unit tests

Integrate Arquillian/GlassFish Embedded/Weld EE/Weld SE as needed.

Don't hard code root filesystem paths into web.xml

jdbc:derby:$

{webapp.databaseTempDir}

/cargo-tracker-database;create=true

When searching a cargo by trackingId, the input is not trimmed so the application throws an exception

Steps to reproduce :

On home page, go to public landing page
Search a valid tracking id with space before or after

=> javax.faces.el.EvaluationException: javax.persistence.NoResultException: getSingleResult() did not retrieve any entities.

When removing the spaces, cargo is retrieved.

Bug is also on administration.

Environment

JDK 1.7
Netbeans 8.0
Glassfish 4.0

HTML namespaces in Facelets pages need updating for Java EE 7 (JSF 2.2)

As of JavaServer Faces 2.2, the namespace URLs for Facelets pages have changed from java.sun.com to xmlns.jcp.org. To support Java EE 7, for example, the three middle namespaces in the following html element in admin/registration.xhtml need to be fixed:

The last one, which is used for the JSF 2.2 pass-through elements feature, is already correct.

The old namespaces are still supported, so you don't get errors. But EE 7 apps should use the new ones.

javaee / cargotracker Goto Github PK

cargotracker's Introduction

cargotracker's People

Contributors

Stargazers

Watchers

Forkers

cargotracker's Issues

Environment

Environment

Environment

Environment

Environment

Environment

Environment

Environment

Environment

Environment

Environment

Recommend Projects

Recommend Topics

Recommend Org