updated Javadocs that talk about lack of synchronization between master and tracking data

java/com.sap.sailing.domain/src/com/sap/sailing/domain/base/Event.java

@@ -12,15 +12,17 @@ import com.sap.sailing.domain.tracking.TrackedEvent;
  */
 public interface Event extends Named {
     /**
-     * Please note that the {@link RaceDefinition}s of the {@link Event} must not be synchronized {@link RaceDefinition}s
-     * of {@link TrackedEvent}. The values could be inconsistent.
-     * @return
+     * Please note that the {@link RaceDefinition}s of the {@link Event} are not necessarily in sync with the
+     * {@link TrackedRace}s of the {@link TrackedEvent} whose {@link TrackedEvent#getEvent() event} is this event.
+     * For example, it may be the case that a {@link RaceDefinition} is returned by this method for which no
+     * {@link TrackedRace} exists in the corresponding {@link TrackedEvent}. This could be the case, e.g., during
+     * the initialization of the tracker as well as during removing a race from the server.
      */
     Iterable<RaceDefinition> getAllRaces();
     
     /**
-     * Please note that the {@link RaceDefinition} of {@link Event} must not be synchronized with the 
-     * {@link RaceDefinition} of {@link TrackedEvent}. The values could be inconsistent.
+     * Please note that the set of {@link RaceDefinition}s contained by this event may not match up with the 
+     * {@link TrackedRace}s of the {@link TrackedEvent} corresponding to this event. See also {@link #getAllRaces()}.
      * 
      * @return <code>null</code>, if this event does not contain a race (see {@link #getAllRaces}) whose
      * {@link RaceDefinition#getName()} equals <code>raceName</code>

java/com.sap.sailing.domain/src/com/sap/sailing/domain/tracking/RaceTracker.java

@@ -5,8 +5,31 @@ import java.net.MalformedURLException;
 import java.util.Map;
 import java.util.Set;
 
+import com.sap.sailing.domain.base.Event;
 import com.sap.sailing.domain.base.RaceDefinition;
 
+/**
+ * Centerpiece of a tracking adapter. A tracker is responsible for receiving tracking data for one or more
+ * {@link RaceDefinition races} that are {@link Event#getAllRaces() part of} a common {@link #getEvent() Event}. Some
+ * tracker architectures may not be able to deliver all data for the {@link RaceDefinition} when created or started.
+ * Therefore, {@link #getRaces()} may return <code>null</code> if the race information hasn't been received by the
+ * tracker yet. Through the {@link RacesHandle} returned by {@link #getRacesHandle()} it is also possible to perform a
+ * {@link RacesHandle#getRaces() blocking get} for the races tracked by this tracker.
+ * <p>
+ * 
+ * The data received by the tracker is usually fed into {@link TrackedRace} objects that {@link TrackedRace#getRace()
+ * correspond} to the {@link RaceDefinition} objects for whose tracking this tracker is responsible. When the
+ * {@link TrackedRace} isn't connected to its {@link TrackedEvent#getTrackedRaces() owning} {@link TrackedEvent}, a
+ * tracker is assumed to no longer update the {@link TrackedRace} object, even if it hasn't been {@link #stop() stopped}.
+ * <p>
+ * 
+ * A tracker may be {@link #stop() stopped}. In this case, it will no longer receive any data at all. Stopping a tracker
+ * will not modify the {@link Event} and the {@link TrackedEvent} with regards to their ownership of their
+ * {@link RaceDefiniion} and {@link TrackedRace}, respectively.
+ * 
+ * @author Axel Uhl (d043530)
+ * 
+ */
 public interface RaceTracker {
     /**
      * Stops tracking the races.
@@ -16,17 +39,15 @@ public interface RaceTracker {
     com.sap.sailing.domain.base.Event getEvent();
 
     /**
-     * Returns the races currently being tracked by this tracker. Non-blocking call that returns <code>null</code> if
+     * Returns the races being tracked by this tracker. Non-blocking call that returns <code>null</code> if
      * the {@link RaceDefinition} for a TracTrac Event hasn't been created yet, e.g., because the course definition
      * hasn't been received yet or the listener for receiving course information hasn't been registered (yet).
-     * 
-     * If the {@link RacingEventService} is getting a {@link RaceDefinition}, to look up a {@link TrackedRace} 
-     * for this {@link RaceDefinition} via {@link TrackedEvent} there could a issue. The issue appears if RaceDefinition
-     * is currently changed by a tracker, either {@link SwissTimingRaceTracker} or {@link TracTacRaceTracker}.
+     * Also returns races that have been removed from containing structures which may lead this tracker to no
+     * longer update their {@link TrackedRace} with new data.
      */
     Set<RaceDefinition> getRaces();
 
-    RacesHandle getRaceHandle();
+    RacesHandle getRacesHandle();
 
     DynamicTrackedEvent getTrackedEvent();
     

java/com.sap.sailing.domain/src/com/sap/sailing/domain/tracking/TrackedEvent.java

@@ -8,9 +8,14 @@ import com.sap.sailing.domain.base.TimePoint;
 
 /**
  * Manages a set of {@link TrackedRace} objects that belong to the same {@link Event} (regatta, sailing event for a
- * single boat class). It therefore represents the entry point into the tracking-related objects for such an
- * event. Allows clients to find a {@link TrackedRace} by the {@link RaceDefinition} for which it holds the
- * tracking data.
+ * single boat class). It therefore represents the entry point into the tracking-related objects for such an event.
+ * Allows clients to find a {@link TrackedRace} by the {@link RaceDefinition} for which it holds the tracking data.
+ * <p>
+ * 
+ * Please note that the result of calling {@link #getEvent()}.{@link Event#getAllRaces() getAllRaces()} is not
+ * guaranteed to match up with the races obtained by calling {@link TrackedRace#getRace()} on all {@link TrackedRaces}
+ * resulting from {@link #getTrackedRaces()}. In other words, the processes for adding and removing races to the
+ * server do not guarantee to update the master and tracking data for races atomically.
  * 
  * @author Axel Uhl (D043530)
  * 
@@ -38,9 +43,6 @@ public interface TrackedEvent {
     /**
      * Obtains the tracked race for <code>race</code>. Blocks until the tracked race has been created
      * and added to this tracked event (see {@link #addTrackedRace(TrackedRace)}).
-     * 
-     * Please note that the {@link RaceDefinition} of the {@link Event} must not be synchronized {@link RaceDefinition}
-     * of {@link TrackedEvent}. The values could be inconsistent.
      */
     TrackedRace getTrackedRace(RaceDefinition race);