Merged changes from 1.0 branch back to trunk

dddsample/pom.xml

@@ -1,13 +1,10 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>se.citerus</groupId>
   <artifactId>dddsample</artifactId>
   <packaging>war</packaging>
   <name>DDDSample</name>
-  <version>1.0-SNAPSHOT</version>
+  <version>1.1-SNAPSHOT</version>
   <description>This application shows a few key concepts of
     Domain Driven Design implemented in Enterprise Java.
   </description>
@@ -18,7 +15,7 @@
       <url>scp://shell.sf.net/home/groups/d/dd/dddsample/htdocs</url>
     </site>
   </distributionManagement>
-  <ciManagement/>
+  <ciManagement />
   <repositories>
     <repository>
       <id>maven2-repository.dev.java.net</id>

dddsample/src/main/java/se/citerus/dddsample/application/messaging/HandlingEventMessageDelegate.java

@@ -2,6 +2,7 @@ package se.citerus.dddsample.application.messaging;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.transaction.annotation.Transactional;
 import se.citerus.dddsample.domain.model.cargo.TrackingId;
 import se.citerus.dddsample.domain.service.TrackingService;
 
@@ -22,6 +23,7 @@ public class HandlingEventMessageDelegate implements MessageListener {
   private TrackingService trackingService;
   private final Log logger = LogFactory.getLog(getClass());
 
+  @Transactional(readOnly = true)  
   public void onMessage(final Message message) {
     if (logger.isDebugEnabled()) {
       logger.debug("Received message " + message);

dddsample/src/main/java/se/citerus/dddsample/application/messaging/JmsDomainEventNotifierImpl.java

@@ -18,7 +18,6 @@ public final class JmsDomainEventNotifierImpl implements DomainEventNotifier {
 
   public void cargoWasHandled(final HandlingEvent event) {
     jmsOperations.send(destination, new MessageCreator() {
-      // TODO: richer message type
       public Message createMessage(final Session session) throws JMSException {
         final MapMessage message = session.createMapMessage();
         message.setStringProperty(TRACKING_ID_KEY, event.cargo().trackingId().idString());

dddsample/src/main/java/se/citerus/dddsample/application/remoting/BookingServiceFacadeImpl.java

@@ -1,5 +1,6 @@
 package se.citerus.dddsample.application.remoting;
 
+import org.springframework.transaction.annotation.Transactional;
 import se.citerus.dddsample.application.remoting.dto.CargoRoutingDTO;
 import se.citerus.dddsample.application.remoting.dto.ItineraryCandidateDTO;
 import se.citerus.dddsample.application.remoting.dto.LocationDTO;
@@ -35,30 +36,33 @@ public class BookingServiceFacadeImpl implements BookingServiceFacade {
   private CargoRepository cargoRepository;
   private CarrierMovementRepository carrierMovementRepository;
 
+  @Transactional(readOnly = true)
   public List<LocationDTO> listShippingLocations() {
     final List<Location> allLocations = locationRepository.findAll();
     final LocationDTOAssembler assembler = new LocationDTOAssembler();
     return assembler.toDTOList(allLocations);
   }
 
+  @Transactional(readOnly = false)
   public String registerNewCargo(String origin, String destination) {
     TrackingId trackingId = bookingService.bookNewCargo(new UnLocode(origin), new UnLocode(destination));
     return trackingId.idString();
   }
 
+  @Transactional(readOnly = true)
   public CargoRoutingDTO loadCargoForRouting(String trackingId) {
-    // TODO lock
     final Cargo cargo = cargoRepository.find(new TrackingId(trackingId));
     final CargoRoutingDTOAssembler assembler = new CargoRoutingDTOAssembler();
     return assembler.toDTO(cargo);
   }
 
+  @Transactional(readOnly = false)
   public void assignCargoToRoute(String trackingId, ItineraryCandidateDTO itineraryCandidateDTO) {
     final Itinerary itinerary = new ItineraryCandidateDTOAssembler().fromDTO(itineraryCandidateDTO, carrierMovementRepository, locationRepository);
     bookingService.assignCargoToRoute(new TrackingId(trackingId), itinerary);
-    // TODO unlock
   }
 
+  @Transactional(readOnly = true)
   public List<CargoRoutingDTO> listAllCargos() {
     final List<Cargo> cargoList = cargoRepository.findAll();
     final List<CargoRoutingDTO> dtoList = new ArrayList<CargoRoutingDTO>(cargoList.size());
@@ -69,6 +73,7 @@ public class BookingServiceFacadeImpl implements BookingServiceFacade {
     return dtoList;
   }
 
+  @Transactional(readOnly = true)
   public List<ItineraryCandidateDTO> requestPossibleRoutesForCargo(String trackingId) throws RemoteException {
     final List<Itinerary> itineraries = bookingService.requestPossibleRoutesForCargo(new TrackingId(trackingId));
 

dddsample/src/main/java/se/citerus/dddsample/application/remoting/dto/assembler/CargoRoutingDTOAssembler.java

@@ -12,14 +12,14 @@ public class CargoRoutingDTOAssembler {
   public CargoRoutingDTO toDTO(final Cargo cargo) {
     final CargoRoutingDTO dto = new CargoRoutingDTO(
       cargo.trackingId().idString(),
-      cargo.origin().toString(),
-      cargo.destination().toString()
+      cargo.origin().unLocode().idString(),
+      cargo.destination().unLocode().idString()
     );
     for (Leg leg : cargo.itinerary().legs()) {
       dto.addLeg(
         leg.carrierMovement().carrierMovementId().idString(),
-        leg.from().toString(),
-        leg.to().toString()
+        leg.from().unLocode().idString(),
+        leg.to().unLocode().idString()
       );
     }
     return dto;

dddsample/src/main/java/se/citerus/dddsample/application/ws/HandlingEventServiceEndpointImpl.java

@@ -3,12 +3,17 @@ package se.citerus.dddsample.application.ws;
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionStatus;
+import org.springframework.transaction.support.TransactionCallbackWithoutResult;
+import org.springframework.transaction.support.TransactionTemplate;
 import se.citerus.dddsample.domain.model.cargo.TrackingId;
 import se.citerus.dddsample.domain.model.carrier.CarrierMovementId;
 import se.citerus.dddsample.domain.model.handling.HandlingEvent;
 import se.citerus.dddsample.domain.model.location.UnLocode;
 import se.citerus.dddsample.domain.service.HandlingEventService;
 import se.citerus.dddsample.domain.service.UnknownCarrierMovementIdException;
+import se.citerus.dddsample.domain.service.UnknownLocationException;
 import se.citerus.dddsample.domain.service.UnknownTrackingIdException;
 
 import javax.jws.WebService;
@@ -20,41 +25,49 @@ import java.util.Date;
 public class HandlingEventServiceEndpointImpl implements HandlingEventServiceEndpoint {
 
   private HandlingEventService handlingEventService;
+  private TransactionTemplate transactionTemplate;
   private final Log logger = LogFactory.getLog(getClass());
   protected static final String ISO_8601_FORMAT = "yyyy-mm-dd HH:MM:SS.SSS";
 
   public void register(final String completionTime, final String trackingId, final String carrierMovementId,
                        final String unlocode, final String eventType) {
     try {
-      Date date = parseIso8601Date(completionTime);
-      TrackingId tid = new TrackingId(trackingId);
-      CarrierMovementId cid;
+      final Date date = parseIso8601Date(completionTime);
+      final TrackingId tid = new TrackingId(trackingId);
+      final CarrierMovementId cid;
       if (StringUtils.isNotEmpty(carrierMovementId)) {
         cid = new CarrierMovementId(carrierMovementId);
       } else {
         cid = null;
       }
-      HandlingEvent.Type type = parseEventType(eventType);
+      final HandlingEvent.Type type = parseEventType(eventType);
 
-      UnLocode ul = new UnLocode(unlocode);
+      final UnLocode ul = new UnLocode(unlocode);
 
-      handlingEventService.register(date, tid, cid, ul, type);
+      // Using programmatic demarcation here due to weaving conflicts
+      // between jax-ws and Spring transaction annotations
+      transactionTemplate.execute(new TransactionCallbackWithoutResult() {
+          protected void doInTransactionWithoutResult(TransactionStatus status) {
+              try {
+
+                  handlingEventService.register(date, tid, cid, ul, type);
+
+              } catch (UnknownCarrierMovementIdException e) {
+                  handleUnknownCarrierMovementId(e);
+              } catch (UnknownTrackingIdException e) {
+                  handleUnknownTrackingId(e);
+              } catch (UnknownLocationException e) {
+                  handleOtherError(e);
+              }
+          }
+      });
 
     } catch (IllegalArgumentException iae) {
       handleIllegalArgument(iae);
-
     } catch (ParseException pe) {
       handleInvalidDateFormat(completionTime);
-
-    } catch (UnknownTrackingIdException utid) {
-      handleUnknownTrackingId(utid);
-
-    } catch (UnknownCarrierMovementIdException ucmi) {
-      handleUnknownCarrierMovementId(ucmi);
-
     } catch (InvalidEventTypeException iete) {
       handleInvalidEventType(iete);
-
     } catch (Exception e) {
       handleOtherError(e);
     }
@@ -99,4 +112,9 @@ public class HandlingEventServiceEndpointImpl implements HandlingEventServiceEnd
   public void setHandlingEventService(final HandlingEventService handlingEventService) {
     this.handlingEventService = handlingEventService;
   }
+
+  public void setTransactionManager(PlatformTransactionManager transactionManager) {
+      transactionTemplate = new TransactionTemplate(transactionManager);
+  }
+
 }

dddsample/src/main/java/se/citerus/dddsample/domain/model/Specification.java

@@ -1,6 +1,7 @@
 package se.citerus.dddsample.domain.model;
 
 public interface Specification<T> {
-  // TODO replace with Specification project dependency
+
   boolean isSatisfiedBy(T t);
+    
 }

dddsample/src/main/java/se/citerus/dddsample/domain/model/handling/HandlingEventRepository.java

@@ -17,7 +17,6 @@ public interface HandlingEventRepository {
   void save(final HandlingEvent event);
 
 
-  // TODO: remove this in 1.0 branch, it's not used anywhere
   /**
    * @param trackingId cargo tracking id
    * @return All handling events for this cargo, ordered by completion time.

dddsample/src/main/java/se/citerus/dddsample/domain/model/location/Location.java

@@ -80,16 +80,6 @@ public final class Location implements Entity<Location> {
     return unLocode.hashCode();
   }
 
-  /**
-   * @return Unlocode and name, on the format "SESTO (Stockholm)"
-   */
-  @Override
-  public String toString() {
-    // TODO: this feels like presentation logic and is very inconsistent, move to DTO assembler
-    return unLocode.idString() + " (" + name + ")";
-  }
-
-
   Location() {
     // Needed by Hibernate
   }

dddsample/src/main/java/se/citerus/dddsample/domain/service/impl/BookingServiceImpl.java

@@ -3,7 +3,6 @@ package se.citerus.dddsample.domain.service.impl;
 import org.apache.commons.lang.Validate;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-import org.springframework.transaction.annotation.Transactional;
 import se.citerus.dddsample.domain.model.cargo.*;
 import se.citerus.dddsample.domain.model.location.Location;
 import se.citerus.dddsample.domain.model.location.LocationRepository;
@@ -22,7 +21,6 @@ public final class BookingServiceImpl implements BookingService {
 
   private final Log logger = LogFactory.getLog(getClass());
 
-  @Transactional(readOnly = false)
   public TrackingId bookNewCargo(final UnLocode originUnLocode, final UnLocode destinationUnLocode) {
     Validate.notNull(originUnLocode);
     Validate.notNull(destinationUnLocode);
@@ -38,7 +36,6 @@ public final class BookingServiceImpl implements BookingService {
     return cargo.trackingId();
   }
 
-  @Transactional(readOnly = true)
   public List<Itinerary> requestPossibleRoutesForCargo(TrackingId trackingId) {
     Validate.notNull(trackingId);
     
@@ -48,7 +45,6 @@ public final class BookingServiceImpl implements BookingService {
     return routingService.fetchRoutesForSpecification(routeSpecification);
   }
 
-  @Transactional(readOnly = false)
   public void assignCargoToRoute(final TrackingId trackingId, final Itinerary newItinerary) {
     Validate.notNull(trackingId);
     Validate.notNull(newItinerary);

dddsample/src/main/java/se/citerus/dddsample/domain/service/impl/HandlingEventServiceImpl.java

@@ -1,7 +1,6 @@
 package se.citerus.dddsample.domain.service.impl;
 
 import org.apache.commons.lang.Validate;
-import org.springframework.transaction.annotation.Transactional;
 import se.citerus.dddsample.domain.model.cargo.Cargo;
 import se.citerus.dddsample.domain.model.cargo.CargoRepository;
 import se.citerus.dddsample.domain.model.cargo.TrackingId;
@@ -24,7 +23,6 @@ public final class HandlingEventServiceImpl implements HandlingEventService {
   private LocationRepository locationRepository;
   private DomainEventNotifier domainEventNotifier;
 
-  @Transactional(readOnly = false)
   public void register(final Date completionTime, final TrackingId trackingId, final CarrierMovementId carrierMovementId,
                        final UnLocode unlocode, final HandlingEvent.Type type)
     throws UnknownCarrierMovementIdException, UnknownTrackingIdException, UnknownLocationException {

dddsample/src/main/java/se/citerus/dddsample/domain/service/impl/TrackingServiceImpl.java

@@ -3,7 +3,6 @@ package se.citerus.dddsample.domain.service.impl;
 import org.apache.commons.lang.Validate;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-import org.springframework.transaction.annotation.Transactional;
 import se.citerus.dddsample.domain.model.cargo.Cargo;
 import se.citerus.dddsample.domain.model.cargo.CargoRepository;
 import se.citerus.dddsample.domain.model.cargo.TrackingId;
@@ -15,20 +14,18 @@ public class TrackingServiceImpl implements TrackingService {
 
   private final Log logger = LogFactory.getLog(getClass());
 
-  @Transactional(readOnly = true)
   public Cargo track(final TrackingId trackingId) {
     Validate.notNull(trackingId);
 
     return cargoRepository.find(trackingId);
   }
 
-  @Transactional(readOnly = true)
   public void inspectCargo(final TrackingId trackingId) {
     Validate.notNull(trackingId);
 
     final Cargo cargo = cargoRepository.find(trackingId);
     if (cargo == null) {
-      logger.warn("Can't notify listeners for non-existing cargo " + trackingId);
+      logger.warn("Can't inspect non-existing cargo " + trackingId);
       return;
     }
 
@@ -41,14 +38,13 @@ public class TrackingServiceImpl implements TrackingService {
   }
 
   private void notifyCustomerOfAvailability(Cargo cargo) {
-    // TODO: more elaborate notifications
     logger.info("Cargo " + cargo.trackingId() + " has been unloaded " +
-      "at its final destination " + cargo.destination());
+                "at its final destination " + cargo.destination());
   }
 
   private void handleMisdirectedCargo(Cargo cargo) {
     logger.info("Cargo " + cargo.trackingId() + " has been misdirected. " +
-      "Last event was " + cargo.deliveryHistory().lastEvent());
+                "Last event was " + cargo.deliveryHistory().lastEvent());
   }
 
   public void setCargoRepository(CargoRepository cargoRepository) {

dddsample/src/main/resources/context-remote.xml

@@ -4,16 +4,13 @@
        xmlns:ws="http://jax-ws.dev.java.net/spring/core"
        xmlns:wss="http://jax-ws.dev.java.net/spring/servlet"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xmlns:aop="http://www.springframework.org/schema/aop"
        xsi:schemaLocation="
         http://jax-ws.dev.java.net/spring/core https://jax-ws.dev.java.net/spring/core.xsd
         http://jax-ws.dev.java.net/spring/servlet https://jax-ws.dev.java.net/spring/servlet.xsd
-        http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
 
 
   <!-- Handling event registration web service -->
-
   
   <wss:bindings id="jax-ws.http">
     <wss:bindings>
@@ -27,51 +24,11 @@
 
   <bean id="handlingEventServiceEndpoint" class="se.citerus.dddsample.application.ws.HandlingEventServiceEndpointImpl">
     <property name="handlingEventService" ref="handlingEventService"/>
+    <property name="transactionManager" ref="transactionManager"/>
   </bean>
 
 
-  <!-- Booking service facade -->
-
-  
-  <!-- Hibernate interceptor -->
-  <bean id="hibernateInterceptor" class="org.springframework.orm.hibernate3.HibernateInterceptor">
-    <property name="sessionFactory" ref="sessionFactory"/>
-  </bean>
-
-  <!-- Facade wrapped with Hibernate interceptor -->
-  <bean id="bookingServiceFacade" class="org.springframework.aop.framework.ProxyFactoryBean">
-    <property name="interceptorNames">
-      <list>
-        <value>hibernateInterceptor</value>
-      </list>
-    </property>
-    <property name="target">
-      <bean class="se.citerus.dddsample.application.remoting.BookingServiceFacadeImpl">
-        <property name="bookingService" ref="bookingService"/>
-        <property name="cargoRepository" ref="cargoRepository"/>
-        <property name="locationRepository" ref="locationRepository"/>
-        <property name="carrierMovementRepository" ref="carrierMovementRepository"/>
-      </bean>
-    </property>
-  </bean>
-
-  <!-- Wrap all methods with Hibernate interceptor
-  TODO: add necessary aspectj deps and replace config above with this
-  
-  <bean id="bookingServiceFacade" class="se.citerus.dddsample.application.remote.BookingServiceFacadeImpl">
-    <property name="bookingService" ref="bookingService"/>
-    <property name="cargoRepository" ref="cargoRepository"/>
-    <property name="locationRepository" ref="locationRepository"/>
-    <property name="carrierMovementRepository" ref="carrierMovementRepository"/>
-  </bean>
-
-  <aop:config>
-    <aop:advisor advice-ref="hibernateInterceptor"
-                 pointcut="execution (* se.citerus.dddsample.application.remote.BookingServiceFacadeImpl(..))"/>
-  </aop:config>
-  -->
-
-  <!-- RMI exposure -->
+  <!-- RMI exposed booking service facade -->
   <bean id="rmiBookingServiceFacade" class="org.springframework.remoting.rmi.RmiServiceExporter">
     <property name="serviceInterface" value="se.citerus.dddsample.application.remoting.BookingServiceFacade"/>
     <property name="service" ref="bookingServiceFacade"/>

dddsample/src/main/resources/context-service.xml

@@ -33,4 +33,11 @@
     <property name="graphTraversalService" ref="graphTraversalService"/>
   </bean>
 
+  <bean id="bookingServiceFacade" class="se.citerus.dddsample.application.remoting.BookingServiceFacadeImpl">
+    <property name="bookingService" ref="bookingService"/>
+    <property name="cargoRepository" ref="cargoRepository"/>
+    <property name="locationRepository" ref="locationRepository"/>
+    <property name="carrierMovementRepository" ref="carrierMovementRepository"/>
+  </bean>
+  
 </beans>

dddsample/src/main/resources/log4j.properties

@@ -1,4 +1,4 @@
-log4j.rootLogger=info, stdout, logfile
+log4j.rootLogger=info, stdout
 
 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

dddsample/src/main/webapp/WEB-INF/jsp/cargo/track.jsp

@@ -29,6 +29,9 @@
     </table>
   </form:form>
   </div>
+  <c:if test="${cargo == null}">
+    <p><em>Hint: try tracking "XYZ" or "JKL".</em></p>  
+  </c:if>
 
   <c:if test="${cargo != null}">
     <div id="result">

dddsample/src/main/webapp/style.css

@@ -130,9 +130,9 @@ textarea,
 select {
   padding: 1px;
   font: 400 1em verdana, sans-serif;
-  color: #999;
+  color: black;
   background: #EEE;
-  border: 1px solid #CCC;
+  border: 1px solid #555;
 }
 
 input:focus,

dddsample/src/site/apt/characterization.apt

@@ -29,7 +29,15 @@
 
 {Aggregates}
 
-    In real life most things are connected, directly or indirectly. Mimicking this approach when building large software systems tend to bring unnecessary complexity and poor performance. DDD provides tactics to help you sort these things out, aggregates being one of the most important ones. Aggregates help with decoupling of large structures by setting rules for relations between entities. Aggregates can also have properties, methods, and invariants that doesn't fit within one single class. Java and other OO-languages typically miss specific language constructs to handle aggregates and in the sample application responsibilities that belong to an aggregate is most often implemented in the aggregate root.

    <<<{{{xref/se/citerus/dddsample/domain/model/cargo/package-summary.html}cargo}}>>>: cargo is the central aggregate in the sample application. <<<Cargo>>> is the aggregate root and the aggregate also contains the <Value Objects> <<<DeliveryHistory>>>, <<<Itinereray>>>, <<<Leg>>> and a few more classes. 

    <<<{{{xref/se/citerus/dddsample/domain/model/handling/package-summary.html}handling}}>>>: handling is another important aggregate. It contains the HandlingEvents that are registered throughout a cargo's progress from <<<RECEIVED>>> to <<<CLAIMED>>>. The <<<HandlingEvent>>>s have a relation to the <<<Cargo>>> for which the event belongs, this is allowed since <<<HandlingEvent>>> is an aggregate root and so is <<<Cargo>>>. 

    The main reason for not making <<<HandlingEvent>>> part of the cargo aggregate is performance. <<<HandlingEvent>>>s are received from external parties and systems, e.g. warehouse management systems, port handling systems, that call our <<<{{{xref/se/citerus/dddsample/domain/service/HandlingEventService.html}HandlingEventService}}>>> webservice. The number of events can be very high and it is important that our webservice can dispatch the remote calls quickly. To be able to support this use case we need to handle the remote webservice calls asynchronously, i.e. we do not want to load the big cargo structure for each received <<<HandlingEvent>>>. Since all relationships in an aggregate must be handled synchronously we put the <<<HandlingEvent>>> in an aggregate of its own and we are able processes the events quickly and at the same time eliminate dead-locking situations in the system.

    <Editors note: We are aware that this example may need a little more work to drive the full benefits of aggregates home. This is one of the problems with a small sample app, real-world complexity is hard to simulate.>
+    In real life most things are connected, directly or indirectly. Mimicking this approach when building large software systems tend to bring unnecessary complexity and poor performance. DDD provides tactics to help you sort these things out, aggregates being one of the most important ones. Aggregates help with decoupling of large structures by setting rules for relations between entities. Aggregates can also have properties, methods, and invariants that doesn't fit within one single class. Java and other OO-languages typically miss specific language constructs to handle aggregates and in the sample application responsibilities that belong to an aggregate is most often implemented in the aggregate root.
+
+    <<<{{{xref/se/citerus/dddsample/domain/model/cargo/package-summary.html}cargo}}>>>: cargo is the central aggregate in the sample application. <<<Cargo>>> is the aggregate root and the aggregate also contains the <Value Objects> <<<DeliveryHistory>>>, <<<Itinereray>>>, <<<Leg>>> and a few more classes. 
+
+    <<<{{{xref/se/citerus/dddsample/domain/model/handling/package-summary.html}handling}}>>>: handling is another important aggregate. It contains the HandlingEvents that are registered throughout a cargo's progress from <<<RECEIVED>>> to <<<CLAIMED>>>. The <<<HandlingEvent>>>s have a relation to the <<<Cargo>>> for which the event belongs, this is allowed since <<<HandlingEvent>>> is an aggregate root and so is <<<Cargo>>>. 
+
+    The main reason for not making <<<HandlingEvent>>> part of the cargo aggregate is performance. <<<HandlingEvent>>>s are received from external parties and systems, e.g. warehouse management systems, port handling systems, that call our <<<{{{xref/se/citerus/dddsample/domain/service/HandlingEventService.html}HandlingEventService}}>>> webservice. The number of events can be very high and it is important that our webservice can dispatch the remote calls quickly. To be able to support this use case we need to handle the remote webservice calls asynchronously, i.e. we do not want to load the big cargo structure for each received <<<HandlingEvent>>>. Since all relationships in an aggregate must be handled synchronously we put the <<<HandlingEvent>>> in an aggregate of its own and we are able processes the events quickly and at the same time eliminate dead-locking situations in the system.
+
+    <Editors note: We are aware that this example may need a little more work to drive the full benefits of aggregates home. This is one of the problems with a small sample app, real-world complexity is hard to simulate.>
     
 [images/aggregates.gif]
 
@@ -47,10 +55,31 @@
 
 *Domain services
 
-    Domain services are a natural part of the domain and provide services such as message forwarding etc. In the sample application the <<<{{{xref/se/citerus/dddsample/domain/service/RoutingService.html}RoutingService}}>>> provides access to the routing system and is used to find possible routes for a give specification.
+    Domain services are expressed in terms of the ubiquitous language and the domain types, i.e.
+    the method arguments and the return values are proper domain classes. Sometimes, only the service
+    interface (<what> the service does) is part of the domain layer, but the implementation (<how> the service does it)
+    is part of the application layer. This is analogous to how repository interfaces are part of the domain layer, but the
+    Hibernate implementations are not.
 
-*Application services
+    A good example of that is the <<<{{{xref/se/citerus/dddsample/domain/service/RoutingService.html}RoutingService}}>>>,
+    which provides access to the routing system and is used to find possible routes for a give specification.
+    The {{{xref/se/citerus/dddsample/application/routing/ExternalRoutingService.html}implementation}} communicates with
+    another team's context and translates to and from an external API and data model.
+
+    On the other hand, if the service is possible to implement strictly using the domain layer,
+    both the interface and the implementation are part of the domain layer. That is the case for the
+    <<<{{{xref/se/citerus/dddsample/domain/service/impl/BookingServiceImpl.html}BookingService}}>>>, for example.
 
-    The application services in the sample application are responsible for driving workflow and coordinating transaction management (by use of the declarative transaction management support in Spring). They also provide a high-level abstraction for clients to use when interacting with the domain. These services are typically designed to support specific use cases or stories. The <<<{{{xref/se/citerus/dddsample/domain/service/TrackingService.html}TrackingService}}>>> is used by the public web application for tracking cargo and the <<<{{{xref/se/citerus/dddsample/domain/service/BookingService.html}BookingService}}>>> is used by the internal administration application for booking new cargo.
+*Application services
 
-    The services are all defined in types of the domain, i.e. the method arguments and the return values are proper domain classes. In some situation, e.g. when dealing with graphs of lazy-loaded domain objects or when passing services' return values over network boundaries, the services are wrapped in facades. The facades handle ORM session management issues and/or convert the domain objects to more portable {{{http://martinfowler.com/eaaCatalog/dataTransferObject.html}Data Transfer Objects}}) that can be tailored to specific use cases. See <<<{{{xref/se/citerus/dddsample/application/remoting/BookingServiceFacadeImpl.html}BookingServiceFacadeImpl}}>>> for an example.
+    The application services in the sample application are responsible for driving workflow and coordinating
+    transaction management (by use of the declarative transaction management support in Spring).
+    They also provide a high-level abstraction for clients to use when interacting with the domain.
+    These services are typically designed to support specific use cases or fulfill technical requirements (web services, etc).
+
+    In some situations, e.g. when dealing with graphs of lazy-loaded
+    domain objects or when passing services' return values over network boundaries, the services are wrapped in facades.
+    The facades handle ORM session management issues and/or convert the domain objects to more portable
+    {{{http://martinfowler.com/eaaCatalog/dataTransferObject.html}Data Transfer Objects}}) that can be tailored
+    to specific use cases.
+    See <<<{{{xref/se/citerus/dddsample/application/remoting/BookingServiceFacadeImpl.html}BookingServiceFacadeImpl}}>>> for an example.

dddsample/src/site/apt/download.apt

@@ -2,17 +2,120 @@
   Download
   --------
 
-Deployable WAR archive of main application
+Prerequisites
 
-  <<COMING SOON>> - for now, use source archive and run <<<mvn package>>> to build
+  * Java 5 or later
 
-Source code for main application
+  []
 
-  {{{http://downloads.sourceforge.net/dddsample/dddsample-1.0-SNAPSHOT-src.zip?use_mirror=osdn} Download from Sourceforge}}
+  Optional:
 
-  Also, you can {{{source-repository.html}track Subversion}} directly.
+  * {{{http://maven.apache.org}Maven}} 2.0.9 or later (for development)
 
-Incident logging application
+  * A servlet container, such as {{{http://tomcat.apache.org}Tomcat}} (for deploying the web archive)
 
-  <<COMING SOON>>
+Downloads
 
+    There are three different {{{http://sourceforge.net/project/showfiles.php?group_id=210606}downloads}} available:
+    the {{{http://downloads.sourceforge.net/dddsample/dddsample-1.0-src.zip?use_mirror=osdn} source package}},
+    the {{{http://downloads.sourceforge.net/dddsample/IncidentLoggingApplication.zip?use_mirror=osdn} Incident Logging Application}}
+    and the {{{http://downloads.sourceforge.net/dddsample/dddsample-1.0.war?use_mirror=osdn} pre-built web archive}}.
+
+    The project uses Maven for build and management.
+
+* Source package
+
+    Download {{{http://downloads.sourceforge.net/dddsample/dddsample-1.0-src.zip?use_mirror=osdn} here}}.
+
+    This is a complete checkout of the core application source code.
+
+    To build a web archive from scratch (to be found in the target directory):
+
+-----------------
+mvn clean package
+-----------------
+
+    To build and run the application in an embedded Jetty:
+
+-------------
+mvn jetty:run
+-------------
+
+    The public tracking interface is available at {{http://localhost:8080/dddsample}} (try tracking cargos XYZ and JKL, for example)
+    and the booking and routing administration interface can be found at {{http://localhost:8080/dddsample/admin/list.html}}.
+    The administration interface is used for booking and routing cargo.
+
+    An RMI registry will be started on port <<<1099>>>, in addition to the Jetty container on port <<<8080>>>, so those ports
+    need to be available or you have to reconfigure the application.
+
+    <<NOTE>>: running some Maven targets (<<<jetty:run>>> for example) currently do not work in IntelliJ with the embedded Maven runner.
+    Workaround: either run Maven from command line, or swich to external Maven runner in IntelliJ.
+
+    <<NOTE>>: the application currently can't be run offline, due to an unresolved problem with XSD validation.
+    Workaround: run application online.
+
+    Also, you can {{{source-repository.html}track Subversion}} directly.
+    Use the {{{http://svnbook.red-bean.com/en/1.0/re27.html}<<<svn switch>>>}} command on the source package to start tracking trunk or a stable branch.
+
+* Incident Logging Application
+
+    Download {{{http://downloads.sourceforge.net/dddsample/IncidentLoggingApplication.zip?use_mirror=osdn} here}}.
+
+    This is a simple, standalone Swing client that's used for registering handling events. It communicates with the core
+    application via a Web Service interface. Unpack and run:
+
+----------------------------------------
+cd IncidentLoggingApplication
+
+java -jar IncidentLoggingApplication.jar
+----------------------------------------
+
+    <<NOTE>>: before you start the Incident Logging Application, the core application must be running on the
+    WSDL URL host in the file <<<app.properties>>>, which defaults to <<<localhost:8080>>>.
+    Edit this file to point at the host where the core application is running.
+
+    The source code for this application is currently only available {{{source-repository.html}in Subversion}}.
+
+* Pre-built web archive 
+
+    Download {{{http://downloads.sourceforge.net/dddsample/dddsample-1.0.war?use_mirror=osdn} here}}
+
+    This is a pre-built standard .war, ready to be deployed in a standard servlet container such as Tomcat. It is
+    offered as a convenience if you want a simple way to run the application without bothering with the build
+    environment. Developers who are interested in how DDD is applied in the application should download the source
+    archive instead.
+
+    The same caveats for running the application that are listed in the source package section above apply to this package as well.
+
+IDE Setup
+
+    * IntelliJ 7 or later:
+
+      Maven support is integrated - simply open project using the <<<pom.xml>>>.
+
+    * Netbeans 6 or later:
+
+      Install the Maven plugin (Tools -> Plugins -> Available Plugins), then open project.
+
+    * Eclipse
+
+      Either install a Maven integration plugin ({{{http://code.google.com/p/q4e/} q4e}} recommended), or
+      use standalone Maven to {{{http://maven.apache.org/plugins/maven-eclipse-plugin/}generate project descriptor files}}.
+
+    * Other
+
+      Use standalone Maven to generate project descriptor files for your IDE.
+
+About Maven
+
+    Maven downloads all external library dependencies and plugins separately, which can amount to quite a large number of
+    small files that are downloaded sequentially. These are all cached locally, but the first time you run it you should
+    be prepared to wait 5-10 minutes for the build to complete, depending on your network conditions.
+
+    A good way to get going is to execute the following command, and then go grab a cup of coffee:
+
+---------------------------
+mvn clean package jetty:run
+---------------------------
+
+    That will fill your local cache with most of what you need for development, in a one shot.

dddsample/src/site/apt/index.apt

@@ -31,8 +31,13 @@
 
     There's a lot of interest in new tools or frameworks for DDD.
 
-  Reimplementing the sample app using a new platform will give a side-by-side comparison
-  with the "conventional" implementation, which can demonstrate the value of the new platform
-  and provide validation or other feedback to the developers of the platform.
+    Reimplementing the sample app using a new platform will give a side-by-side comparison
+    with the "conventional" implementation, which can demonstrate the value of the new platform
+    and provide validation or other feedback to the developers of the platform.
+
+  []
+  
+  <This project is a joint effort by Eric Evans' company {{{http://www.domainlanguage.com}Domain Language}}
+  and Swedish software consulting company {{{http://www.citerus.se}Citerus}}.>
 
 

dddsample/src/site/apt/roadmap.apt

@@ -4,9 +4,12 @@
 
 Roadmap
 
-  This application is a work of progress.
+  This application is a work of progress, and these are some ideas for continued development:
 
-* 1.1
+  * Remodel Cargo-HandlingEvent aggregates to make boundaries
+    and asynchronous updates more explicit
+
+  * Make handling event registration completely asynchronous
 
   * Next expected event, for tracking
 
@@ -14,16 +17,9 @@ Roadmap
 
   * Departure/arrival time for carrier movements, ETA for itineraries
 
-  * Make handling event registration asynchronous
-
   * Improve web service interface
 
-* 2.0
-
-  * Remodel Cargo-HandlingEvent aggregates to make boundaries
-    and asynchronous updates more explicit
-
-  * Diversify interfaces
+  * Diversify user interfaces
 
   * More ways to register handing events (FTP CSV file upload etc)
 
@@ -31,4 +27,4 @@ Roadmap
 
   * Port to TimeAndMoney
 
-  * Notify on delay
+  * Notify on delayed delivery

dddsample/src/site/site.xml

@@ -10,15 +10,15 @@
   </poweredBy>
   <body>
     <links>
-      <item name="Domain Language" href="http://www.domainlanguage.org/" />
+      <item name="Domain Language" href="http://www.domainlanguage.com/" />
       <item name="Citerus" href="http://www.citerus.se/"/>
       <item name="DomainDrivenDesign.org" href="http://www.domaindrivendesign.org/"/>
     </links>
     <menu name="About the application">
       <item name="Introduction" href="index.html"/>
+      <item name="Download" href="download.html"/>
       <item name="Characterization" href="characterization.html"/>
       <item name="Patterns Reference" href="patterns-reference.html"/>
-      <item name="Download" href="download.html"/>
       <item name="Roadmap" href="roadmap.html" />
     </menu>
     <menu ref="reports"/>

dddsample/src/test/java/se/citerus/dddsample/application/service/dto/assembler/CargoRoutingDTOAssemblerTest.java

@@ -42,13 +42,13 @@ public class CargoRoutingDTOAssemblerTest extends TestCase {
 
     LegDTO legDTO = dto.getLegs().get(0);
     assertEquals("ABC", legDTO.getCarrierMovementId());
-    assertEquals("SESTO (Stockholm)", legDTO.getFrom());
-    assertEquals("CNSHA (Shanghai)", legDTO.getTo());
+    assertEquals("SESTO", legDTO.getFrom());
+    assertEquals("CNSHA", legDTO.getTo());
 
     legDTO = dto.getLegs().get(1);
     assertEquals("ABC", legDTO.getCarrierMovementId());
-    assertEquals("NLRTM (Rotterdam)", legDTO.getFrom());
-    assertEquals("AUMEL (Melbourne)", legDTO.getTo());
+    assertEquals("NLRTM", legDTO.getFrom());
+    assertEquals("AUMEL", legDTO.getTo());
   }
 
   public void testToDTO_NoItinerary() throws Exception {
@@ -58,8 +58,8 @@ public class CargoRoutingDTOAssemblerTest extends TestCase {
     final CargoRoutingDTO dto = assembler.toDTO(cargo);
 
     assertEquals("XYZ", dto.getTrackingId());
-    assertEquals("SESTO (Stockholm)", dto.getOrigin());
-    assertEquals("AUMEL (Melbourne)", dto.getFinalDestination());
+    assertEquals("SESTO", dto.getOrigin());
+    assertEquals("AUMEL", dto.getFinalDestination());
     assertTrue(dto.getLegs().isEmpty());
   }
 }

dddsample/src/test/java/se/citerus/dddsample/application/ws/HandlinEventServiceEndpointTest.java

@@ -2,6 +2,7 @@ package se.citerus.dddsample.application.ws;
 
 import junit.framework.TestCase;
 import static org.easymock.EasyMock.*;
+import se.citerus.dddsample.application.service.InMemTransactionManager;
 import se.citerus.dddsample.domain.model.cargo.TrackingId;
 import se.citerus.dddsample.domain.model.carrier.CarrierMovementId;
 import se.citerus.dddsample.domain.model.handling.HandlingEvent;
@@ -24,6 +25,7 @@ public class HandlinEventServiceEndpointTest extends TestCase {
     handlingEventService = createMock(HandlingEventService.class);
     endpoint.setHandlingEventService(handlingEventService);
     sdf = new SimpleDateFormat(HandlingEventServiceEndpointImpl.ISO_8601_FORMAT);
+    endpoint.setTransactionManager(new InMemTransactionManager());
   }
 
   public void testRegisterValidEvent() throws Exception {

dddsample/src/test/java/se/citerus/dddsample/domain/service/RoutingScenarioTest.java

@@ -1,74 +0,0 @@
-package se.citerus.dddsample.domain.service;
-
-import junit.framework.TestCase;
-import se.citerus.dddsample.domain.model.cargo.*;
-import se.citerus.dddsample.domain.model.carrier.CarrierMovementId;
-import se.citerus.dddsample.domain.model.location.UnLocode;
-
-import java.util.Date;
-import java.util.List;
-
-public class RoutingScenarioTest extends TestCase {
-
-  RoutingService routingService;
-  CargoRepository cargoRepository;
-  HandlingEventService handlingEventService;
-
-  // TODO work on this
-  public void xtestCalculateRoute() throws Exception {
-
-    TrackingId trackingId = new TrackingId("XYZ123");
-    Cargo cargo = cargoRepository.find(trackingId);
-
-    Date twoWeeksFromNow = new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 24 * 14);
-
-    RouteSpecification routeSpecification = RouteSpecification.forCargo(cargo, twoWeeksFromNow);
-
-    /*
-      The routing service calculates a number of possible routes that
-      satisfy the given specification (must arrive in three days, must not
-      cost more than $10,000 etc).
-     */
-    List<Itinerary> itineraryCandidates = routingService.fetchRoutesForSpecification(routeSpecification);
-
-    /*
-      Someone, or something, selects the most appropriate itinerary and
-      assigns that itinerary to the cargo.
-     */
-    Itinerary itinerary = stubbedItinerarySelection(itineraryCandidates);
-    cargo.attachItinerary(itinerary);
-
-    /*
-      A number of events occur, all of which are according to plan
-     */
-    handlingEventService.register(new Date(), trackingId, new CarrierMovementId("A001"), new UnLocode("SESTO"), null);
-    handlingEventService.register(new Date(), trackingId, new CarrierMovementId("B002"), null, null);
-    handlingEventService.register(new Date(), trackingId, new CarrierMovementId("C003"), null, null);
-
-    /*
-      Cargo should not be misdirected at this point.
-     */
-    assertFalse(cargo.isMisdirected());
-
-    /*
-      An unexpected event occur.
-     */
-    handlingEventService.register(null, null, null, null, null);
-
-    /*
-      Now the cargo is misdirected.
-     */
-    assertTrue(cargo.isMisdirected());
-  }
-
-  public void testRun() throws Exception
-  {
-    
-  }
-
-
-  private Itinerary stubbedItinerarySelection(List<Itinerary> itineraryCandidates) {
-    return itineraryCandidates.get(0);
-  }
-
-}