Added more JavaDocs to fix tracking code

java/com.sap.sailing.domain.racelogtrackingadapter/src/com/sap/sailing/domain/racelogtracking/impl/fixtracker/RaceLogFixTrackerManager.java

@@ -20,8 +20,8 @@ import com.sap.sailing.domain.tracking.impl.AbstractRaceChangeListener;
  * This class manages the lifecycle of the {@link RaceLogFixTracker} by listening to
  * {@link RaceLogDenoteForTrackingEvent}, race log attached and stop tracking race changes.
  * 
- * Once the race is stopped, it notifies its own {@link Owner}.
- * 
+ * Once the race is stopped, it notifies its own {@link Owner} so that all reference to this instance can be cleanly
+ * removed to prevent memory leaks.
  */
 public class RaceLogFixTrackerManager implements TrackingDataLoader {
     private static final Logger logger = Logger.getLogger(RaceLogFixTrackerManager.class.getName());

java/com.sap.sailing.domain.racelogtrackingadapter/src/com/sap/sailing/domain/racelogtracking/impl/fixtracker/RegattaLogFixTrackerRaceListener.java

@@ -10,7 +10,16 @@ import com.sap.sailing.domain.tracking.DynamicTrackedRace;
 import com.sap.sailing.domain.tracking.DynamicTrackedRegatta;
 import com.sap.sailing.domain.tracking.RaceListener;
 import com.sap.sailing.domain.tracking.TrackedRace;
+import com.sap.sailing.domain.tracking.TrackedRegatta;
 
+/**
+ * An instance of this class is created for every {@link TrackedRegatta} by {@link RegattaLogFixTrackerRegattaListener}.
+ * This observes the given {@link TrackedRegatta} to get to know about every {@link TrackedRace} of the
+ * {@link TrackedRegatta}.
+ * 
+ * An instance of {@link RaceLogFixTrackerManager} is created for every {@link TrackedRace}. It is ensured that
+ * {@link RaceLogFixTrackerManager} are stopped when a {@link TrackedRace} is removed from the {@link TrackedRegatta}.
+ */
 public class RegattaLogFixTrackerRaceListener {
     private final Map<RegattaAndRaceIdentifier, DynamicTrackedRace> knownTrackedRaces = new ConcurrentHashMap<>();
     private final Map<RegattaAndRaceIdentifier, RaceLogFixTrackerManager> dataTrackers = new ConcurrentHashMap<>();
@@ -60,6 +69,10 @@ public class RegattaLogFixTrackerRaceListener {
         dataTrackers.remove(raceIdentifier, trackerManager);
     }
 
+    /**
+     * Called by {@link RegattaLogFixTrackerRegattaListener} when the {@link TrackedRegatta} was removed or the
+     * {@link TrackedRegatta} shouldn't be tracked anymore (this is e.g. the case in replication state.
+     */
     public synchronized void stop() {
         trackedRegatta.removeRaceListener(raceListener);
         knownTrackedRaces.keySet().forEach(this::removeRaceLogSensorDataTracker);

java/com.sap.sailing.domain.racelogtrackingadapter/src/com/sap/sailing/domain/racelogtracking/impl/fixtracker/RegattaLogFixTrackerRegattaListener.java

@@ -16,6 +16,7 @@ import java.util.logging.Logger;
 
 import org.osgi.util.tracker.ServiceTracker;
 
+import com.sap.sailing.domain.racelog.tracking.SensorFixStore;
 import com.sap.sailing.domain.racelogsensortracking.SensorFixMapperFactory;
 import com.sap.sailing.domain.tracking.DynamicTrackedRegatta;
 import com.sap.sailing.domain.tracking.TrackedRegatta;
@@ -27,6 +28,18 @@ import com.sap.sse.replication.ReplicationMasterDescriptor;
 import com.sap.sse.replication.impl.OperationWithResultWithIdWrapper;
 import com.sap.sse.replication.impl.ReplicableWithObjectInputStream;
 
+/**
+ * This is the main entry point of the {@link SensorFixStore} based fix tracking.
+ * 
+ * This listener is informed about every {@link TrackedRegatta} by {@link RacingEventService} via the implemented
+ * {@link TrackedRegattaListener}. For every known {@link TrackedRegatta}, a {@link RegattaLogFixTrackerRaceListener} is
+ * started.
+ * 
+ * In addition this is a {@link ReplicableWithObjectInputStream} because we need to know if the current node is a
+ * replica. Replicas must not do any fix tracking because fixes are being loaded on the master and transferred to the
+ * replicas through the replication mechanism. That's why in replication state, no
+ * {@link RegattaLogFixTrackerRaceListener} instances are created at all.
+ */
 public class RegattaLogFixTrackerRegattaListener implements TrackedRegattaListener,
         ReplicableWithObjectInputStream<RegattaLogFixTrackerRegattaListener, OperationWithResult<RegattaLogFixTrackerRegattaListener, ?>> {
     

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

@@ -1,5 +1,13 @@
 package com.sap.sailing.domain.tracking;
 
+/**
+ * Listener to be informed about new {@link TrackedRegatta}s or ones that are removed.
+ * 
+ * This listener can not directly be registered on RacingEventService because this would potentially lead to OSGi
+ * bundles that could not be stopped/updated. Instead you must publish your listener instance to the OSGi service
+ * registry as {@link TrackedRegattaListener} to make it obtainable by RacingEventService. Your published listener will
+ * automatically be called on {@link TrackedRegatta} changes.
+ */
 public interface TrackedRegattaListener {
     void regattaAdded(TrackedRegatta trackedRegatta);