Added JavaDocs to RaceLogMappingWrapper

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

@@ -13,33 +13,67 @@ import java.util.function.Consumer;
 
 import com.sap.sailing.domain.common.racelog.tracking.DoesNotHaveRegattaLogException;
 import com.sap.sailing.domain.racelogtracking.DeviceIdentifier;
+import com.sap.sailing.domain.racelogtracking.DeviceMapping;
 import com.sap.sailing.domain.racelogtracking.DeviceMappingWithRegattaLogEvent;
 import com.sap.sailing.domain.tracking.DynamicTrack;
 import com.sap.sse.common.TimePoint;
 import com.sap.sse.common.Timed;
 import com.sap.sse.common.WithID;
 
+/**
+ * Holds DeviceMappings to make it possible to track changes. This makes it possible to only process mappings that
+ * weren't processed before.
+ *
+ * @param <ItemT> The type of items the DeviceMappings are mapped to
+ */
 public abstract class RaceLogMappingWrapper<ItemT extends WithID> {
 
     private final Map<ItemT, List<DeviceMappingWithRegattaLogEvent<ItemT>>> mappings = new HashMap<>();
     private final Map<DeviceIdentifier, List<DeviceMappingWithRegattaLogEvent<ItemT>>> mappingsByDevice = new HashMap<>();
     
+    /**
+     * Used internally to access {@link #mappings} with a defensive copy to not run into concurrency issues if this is
+     * called while an update is done.
+     * 
+     * @return the mappings
+     */
     private synchronized Map<ItemT, List<DeviceMappingWithRegattaLogEvent<ItemT>>> getMappings() {
         return new HashMap<>(mappings);
     }
     
+    /**
+     * Used internally to access {@link #mappingsByDevice} with a defensive copy to not run into concurrency issues if
+     * this is called while an update is done.
+     * 
+     * @return the mappings
+     */
     private synchronized Map<DeviceIdentifier, List<DeviceMappingWithRegattaLogEvent<ItemT>>> getMappingsByDevice() {
         return new HashMap<>(mappingsByDevice);
     }
 
+    /**
+     * Calls the given callback for every known mapping that's currently known.
+     * 
+     * @param callback the callback to call for every known mapping
+     */
     public void forEachMapping(Consumer<DeviceMappingWithRegattaLogEvent<ItemT>> callback) {
         forEachMapping((item, mapping) -> callback.accept(mapping));
     }
     
+    /**
+     * Calls the given callback for every device mapped by at least one of the known mappings.
+     * 
+     * @param callback the callback to call for every mapped device
+     */
     public void forEachDevice(Consumer<DeviceIdentifier> callback) {
         getMappingsByDevice().keySet().forEach(callback::accept);
     }
     
+    /**
+     * Calls the given callback for every known mapping that's currently known.
+     * 
+     * @param callback the callback to call for every known mapping
+     */
     public void forEachMapping(BiConsumer<ItemT, DeviceMappingWithRegattaLogEvent<ItemT>> callback) {
         for (Map.Entry<ItemT, List<DeviceMappingWithRegattaLogEvent<ItemT>>> entry : getMappings().entrySet()) {
             ItemT item = entry.getKey();
@@ -49,6 +83,18 @@ public abstract class RaceLogMappingWrapper<ItemT extends WithID> {
         }
     }
     
+    /**
+     * Calls the given callback for every DeviceMapping that is known for the given {@link DeviceIdentifier} that
+     * includes the given {@link TimePoint}.
+     * 
+     * @param device
+     *            the device to get the mappings for
+     * @param timePoint
+     *            the TimePoint to check DeviceMappings for
+     * @param callback
+     *            the callback to call for every known mapping of the given {@link DeviceIdentifier} that includes the
+     *            given {@link TimePoint}.
+     */
     public void forEachMappingOfDeviceIncludingTimePoint(DeviceIdentifier device, TimePoint timePoint,
             Consumer<DeviceMappingWithRegattaLogEvent<ItemT>> callback) {
         List<DeviceMappingWithRegattaLogEvent<ItemT>> mappingsForDevice;
@@ -64,6 +110,11 @@ public abstract class RaceLogMappingWrapper<ItemT extends WithID> {
         }
     }
     
+    /**
+     * To be implemented by subclasses to calculate the current {@link DeviceMapping}s.
+     * 
+     * @return All currently known DeviceMappings
+     */
     protected abstract Map<ItemT, List<DeviceMappingWithRegattaLogEvent<ItemT>>> calculateMappings();
 
     /**
@@ -84,6 +135,13 @@ public abstract class RaceLogMappingWrapper<ItemT extends WithID> {
         updateMappings(newMappings, loadIfNotCovered);
     }
     
+    /**
+     * Used internally to update the internal set of mappings to the state of the new mappings.
+     * This ensures that the internal state is updated and all new and changed mappings are correctly processed.
+     * 
+     * @param newMappings the new mappings
+     * @param loadIfNotCovered true to inform about new/changed/remoded mappings
+     */
     private synchronized void updateMappings(Map<ItemT, List<DeviceMappingWithRegattaLogEvent<ItemT>>> newMappings,
             boolean loadIfNotCovered) {
         if (loadIfNotCovered) {
@@ -125,10 +183,26 @@ public abstract class RaceLogMappingWrapper<ItemT extends WithID> {
         }
     }
     
+    /**
+     * Called when a {@link DeviceMapping} was removed.
+     * 
+     * @param mapping the removed mapping
+     */
     protected abstract void mappingRemoved(DeviceMappingWithRegattaLogEvent<ItemT> mapping);
 
+    /**
+     * Called when a {@link DeviceMapping} was added.
+     * 
+     * @param mapping the new mapping
+     */
     protected abstract void mappingAdded(DeviceMappingWithRegattaLogEvent<ItemT> mapping);
 
+    /**
+     * Called when a {@link DeviceMapping} was changed regarding its mapped time range.
+     * 
+     * @param oldMapping the old mapping
+     * @param newMapping the new mapping
+     */
     protected abstract void mappingChanged(DeviceMappingWithRegattaLogEvent<ItemT> oldMapping,
             DeviceMappingWithRegattaLogEvent<ItemT> newMapping);