|
|
@@ -1,7 +1,7 @@
|
|
1
|
|
-# DDDSample
|
|
2
|
|
-This is the new home of the original DDD Sample app hosted at SourceForge.
|
|
|
1
|
+# CargoApp
|
|
|
2
|
+From the [DDDSample on Github](https://github.com/citerus/dddsample-core.git) This was the new home of the original DDD Sample app hosted at SourceForge. DDD == Design driven development. (It was thing a while back).
|
|
|
3
|
+
|
|
3
|
4
|
|
|
4
|
|
-Our intention is to move everything from SourceForge to GitHub in due time while starting upgrading both the technical aspects as well as the DDD aspects of the DDD Sample.
|
|
5
|
5
|
|
|
6
|
6
|
The application uses Spring Boot. To start it go to the root directory and type `mvn spring-boot:run` or run the `main` method of the `Application` class from your IDE.
|
|
7
|
7
|
|
|
|
@@ -12,3 +12,100 @@ Development blog: https://citerus.github.io/dddsample-core/
|
|
12
|
12
|
Trello board: https://trello.com/b/PTDFRyxd
|
|
13
|
13
|
|
|
14
|
14
|
[](https://travis-ci.org/citerus/dddsample-core)
|
|
|
15
|
+
|
|
|
16
|
+## Exploring the Application
|
|
|
17
|
+
|
|
|
18
|
+After the application runs, it will be available at:
|
|
|
19
|
+http://localhost:8080/cargo-tracker/. Under the hood, the application uses a
|
|
|
20
|
+number of Java EE (and Java EE 7) features including JSF 2.2, CDI, EJB 3.2,
|
|
|
21
|
+JPA 2.1, JAX-RS 2, WebSocket, JSON-P, Bean Validation 1.1 and JMS 2.
|
|
|
22
|
+
|
|
|
23
|
+There are several web interfaces, REST interfaces and a file system scanning
|
|
|
24
|
+interface. It's probably best to start exploring the interfaces in the rough
|
|
|
25
|
+order below.
|
|
|
26
|
+
|
|
|
27
|
+The tracking interface let's you track the status of cargo and is
|
|
|
28
|
+intended for the general public. Try entering a tracking ID like ABC123 (the
|
|
|
29
|
+application is pre-populated with some sample data).
|
|
|
30
|
+
|
|
|
31
|
+The administrative interface is intended for the shipping company that manages
|
|
|
32
|
+cargo. The landing page of the interface is a dashboard providing an overall
|
|
|
33
|
+view of registered cargo. The dashboard will update automatically when cargo
|
|
|
34
|
+is handled (described below). You can book cargo using the booking interface.
|
|
|
35
|
+One cargo is booked, you can route it. When you initiate a routing request,
|
|
|
36
|
+the system will determine routes that might work for the cargo. Once you select
|
|
|
37
|
+a route, the cargo will be ready to process handling events at the port. You can
|
|
|
38
|
+also change the destination for cargo if needed or track cargo.
|
|
|
39
|
+
|
|
|
40
|
+The Incident Logging interface is intended for port personnel registering what
|
|
|
41
|
+happened to cargo. The interface is primarily intended for mobile devices, but
|
|
|
42
|
+you can use it via a desktop browser. The interface is accessible at:
|
|
|
43
|
+http://localhost:8080/cargo-tracker/incident-logger/. For convenience, you
|
|
|
44
|
+could use a mobile emulator instead of an actual mobile device. On Windows,
|
|
|
45
|
+you can use Microsoft WebMatrix for device emulation. Generally speaking cargo
|
|
|
46
|
+goes though these events:
|
|
|
47
|
+
|
|
|
48
|
+* It's received at the origin port.
|
|
|
49
|
+* It's loaded and unloaded onto voyages on it's itinerary.
|
|
|
50
|
+* It's claimed at it's destination port.
|
|
|
51
|
+* It may go through customs at arbitrary points.
|
|
|
52
|
+
|
|
|
53
|
+While filling out the event registration form, it's best to have the itinerary
|
|
|
54
|
+handy. You can access the itinerary for registered cargo via the admin interface.
|
|
|
55
|
+As you register handling events, the administrative dashboard will be
|
|
|
56
|
+automatically updated in real time without a page refresh in addition to cargo
|
|
|
57
|
+state. The cargo handling is done via JMS for scalability and the event
|
|
|
58
|
+notification to the system happens via the CDI event bus and WebSocket, so you
|
|
|
59
|
+will see a visible delay of a few seconds after registering the event for the
|
|
|
60
|
+dashboard to update. While using the incident logger, note that only the load
|
|
|
61
|
+and unload events require as associated voyage (entering an unnecessary voyage
|
|
|
62
|
+for other events will result in an error).
|
|
|
63
|
+
|
|
|
64
|
+You should also explore the file system based bulk event registration interface.
|
|
|
65
|
+It reads files under /tmp/uploads. The files are just CSV files. A sample CSV
|
|
|
66
|
+file is available under src/main/resources/handling_events.csv. Sucessfully
|
|
|
67
|
+processed entries are archived under /tmp/archive. Any failed records are
|
|
|
68
|
+archived under /tmp/failed. Just like the mobile interface, processing events
|
|
|
69
|
+in bulk will also cause the dashboard to automatically update.
|
|
|
70
|
+
|
|
|
71
|
+Don't worry about making mistakes. The application is intended to be fairly
|
|
|
72
|
+error tolerant. If you do come across issues, you should report them. Please
|
|
|
73
|
+see the Getting Involved section on how to do so.
|
|
|
74
|
+
|
|
|
75
|
+NOTE: All data entered is wiped upon application restart, so you can start from
|
|
|
76
|
+a blank slate easily if needed.
|
|
|
77
|
+
|
|
|
78
|
+You can also use the soapUI scripts included in the source code to explore the
|
|
|
79
|
+REST interfaces as well as the numerous unit tests covering the code base
|
|
|
80
|
+generally.
|
|
|
81
|
+
|
|
|
82
|
+## Exploring the Code
|
|
|
83
|
+
|
|
|
84
|
+As mentioned earlier, the real point of the application is demonstrating how to
|
|
|
85
|
+create well architected, effective Java EE applications. To that end, once you
|
|
|
86
|
+have gotten some familiarity with the application functionality the next thing
|
|
|
87
|
+to do is to dig right into the code.
|
|
|
88
|
+
|
|
|
89
|
+DDD is a key aspect of the architecture, so it's important to get at least a
|
|
|
90
|
+working understanding of DDD. As the name implies, Domain-Driven Design is an
|
|
|
91
|
+approach to software design and development that focuses on the core domain and
|
|
|
92
|
+domain logic.
|
|
|
93
|
+
|
|
|
94
|
+We have a brief overview of DDD specifically as it relates to Java EE on the
|
|
|
95
|
+project site: https://java.net/projects/cargotracker/pages/Home. There's also a
|
|
|
96
|
+resources page that you should take a look at:
|
|
|
97
|
+https://java.net/projects/cargotracker/pages/Resources. The project site has
|
|
|
98
|
+pages dedicated to explaining the core constructs of DDD and how they are
|
|
|
99
|
+implemented in the application using Java EE:
|
|
|
100
|
+https://java.net/projects/cargotracker/pages/Characterization as well as the DDD
|
|
|
101
|
+layers in the application: https://java.net/projects/cargotracker/pages/Layers.
|
|
|
102
|
+
|
|
|
103
|
+For the most part, it's fine if you are new to Java EE. As long as you have a
|
|
|
104
|
+basic understanding of server-side applications, the resources referenced above
|
|
|
105
|
+and the code should be good enough to get started. For learning Java EE further,
|
|
|
106
|
+we have recommended a few links in the resources section of the project site. Of
|
|
|
107
|
+course, the ideal user of the project is someone who has a basic working
|
|
|
108
|
+understanding both Java EE and DDD. Though it's not our goal to become a kitchen
|
|
|
109
|
+sink example for demonstrating the vast amount of APIs and features in Java EE,
|
|
|
110
|
+we do use a very representative set. You'll find that you'll learn a fair amount
|
|
|
111
|
+by simply digging into the code to see how things are implemented.
|
Kristofer Younger
8 yıl önce