added some Javadoc in the trackfiles import stuff

java/com.sap.sailing.domain.persistence/src/com/sap/sailing/domain/persistence/racelog/tracking/impl/MongoGPSFixStoreImpl.java

@@ -124,12 +124,9 @@ public class MongoGPSFixStoreImpl implements MongoGPSFixStore {
         try {
             Object dbDeviceId = MongoObjectFactoryImpl.storeDeviceId(deviceServiceFinder, device);
             String type = fix.getClass().getName();
-
             Object fixObject = fixServiceFinder.findService(type).transformForth(fix);
-            DBObject entry = new BasicDBObjectBuilder()
-            .add(FieldNames.DEVICE_ID.name(), dbDeviceId)
-            .add(FieldNames.GPSFIX_TYPE.name(), type)
-            .add(FieldNames.GPSFIX.name(), fixObject).get();
+            DBObject entry = new BasicDBObjectBuilder().add(FieldNames.DEVICE_ID.name(), dbDeviceId)
+                    .add(FieldNames.GPSFIX_TYPE.name(), type).add(FieldNames.GPSFIX.name(), fixObject).get();
             mongoOF.storeTimed(fix, entry);
 
             collection.insert(entry);
@@ -137,7 +134,6 @@ public class MongoGPSFixStoreImpl implements MongoGPSFixStore {
             logger.log(Level.WARNING, "Could not store fix in MongoDB");
             e.printStackTrace();
         }
-
         notifyListeners(device, fix);
     }
 

java/com.sap.sailing.domain.racelogtrackingadapter/src/com/sap/sailing/domain/racelogtracking/impl/RaceLogRaceTracker.java

@@ -428,9 +428,11 @@ public class RaceLogRaceTracker extends BaseRaceLogEventVisitor implements RaceT
                     if (fix instanceof GPSFixMoving) {
                         trackedRace.recordFix(comp, (GPSFixMoving) fix);
                     } else {
-                        logger.log(Level.WARNING, String.format(
-                                "Could not add fix for competitor (%s) in race (%s), as it is no GPSFixMoving", comp,
-                                params.getRaceLog()));
+                        logger.log(
+                                Level.WARNING,
+                                String.format(
+                                        "Could not add fix for competitor (%s) in race (%s), as it is no GPSFixMoving, meaning it is missing COG/SOG values",
+                                        comp, params.getRaceLog()));
                     }
                 }
             }

java/com.sap.sailing.domain/src/com/sap/sailing/domain/trackimport/GPSFixImporter.java

@@ -4,15 +4,30 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.Map;
 
+import com.sap.sailing.domain.racelog.tracking.DeviceIdentifier;
 import com.sap.sailing.domain.tracking.GPSFix;
 
 /**
- * Importer for extracting GPS fixes from an {@link InputStream}. Importers are picked up via
- * the OSGi service registry, so make sure to register them (the {@link GPSFixImporterRegistration}
- * class can help with this).
+ * Importer for extracting GPS fixes from an {@link InputStream}. Importers are picked up via the OSGi service registry,
+ * so make sure to register them (the {@link GPSFixImporterRegistration} class can help with this).
+ * <p>
+ * 
+ * Implementers need to {@link #getType() provide a unique type name} for the importer and may
+ * {@link #getSupportedFileExtensions() specify the file name extensions} for the file types supported.
+ * The actual work is done by the implementation of {@link #importFixes(InputStream, Callback, boolean)} which
+ * receives the input stream that the importer shall analyze. When the start of a track is found, the importer must call the
+ * {@link Callback#startTrack(String, Map)} method. From that point onwards, all fixes that the importer recognizes in the
+ * stream and that it passes to {@link Callback#addFix(GPSFix)} are then assigned to that track which means that
+ * for each track an artificial {@link DeviceIdentifier} is created which can later be used to associate the track
+ * with a tracked object such as a competitor or a mark. Note that this means that all fixes of a single track need
+ * to be passed to the callback before fixes of any other track can be passed to the callback.<p>
+ * 
+ * If the data source to import from does not deliver course and speed over ground (COG/SOG) but only time-stamped
+ * latitude and longitude values, consider using <code>BaseGPSFixImporterImpl</code> which infers COG and SOG values
+ * from the positions and time stamps.
  * 
  * @author Fredrik Teschke
- *
+ * 
  */
 public interface GPSFixImporter {    
     String FILE_EXTENSION_PROPERTY = "fileExt";
@@ -25,16 +40,16 @@ public interface GPSFixImporter {
      */
     interface Callback {
         /**
-         * Is called when the beginning of a track is found. Some track file formats (e.g. GPX)
-         * can contain multiple tracks.
-         * Implementations of the {@link GPSFixImporter} are expected to call this method before
-         * calling {@link #addFix}, even if no metadata is known (and then pass {@code null} values
-         * for the {@code name} and {@code properties}).
+         * Is called when the beginning of a track is found. Some track file formats (e.g. GPX) can contain multiple
+         * tracks. Implementations of the {@link GPSFixImporter} are expected to call this method before calling
+         * {@link #addFix}, even if no metadata is known (and then pass {@code null} values for the {@code name} and
+         * {@code properties}).
          */
         void startTrack(String name, Map<String, String> properties);
+
         void addFix(GPSFix fix);
     }
-    
+
     /**
      * Retrieves the fixes from the {@code inputStream}, and calls the
      * {@code callback} with every new fix.
@@ -49,7 +64,6 @@ public interface GPSFixImporter {
     /**
      * Return the file extensions supported by this importer. If the importer is not intended
      * for file-based input, this may return an empty iterable.
-     * @return
      */
     Iterable<String> getSupportedFileExtensions();
     

java/com.sap.sailing.server.trackfiles/src/com/sap/sailing/server/trackfiles/common/BaseGPSFixImporterImpl.java

@@ -7,9 +7,18 @@ import com.sap.sailing.domain.tracking.GPSFixMoving;
 import com.sap.sailing.domain.tracking.impl.GPSFixMovingImpl;
 
 /**
- * Provide inference functionality.
+ * When an importer only provides latitude/longitude positions but no course over ground (COG) and no speed over ground
+ * (SOG) values, this class infers the COG/SOG values from the positions and timestamps of the basic fixes. Objects of this
+ * class are stateful in the sense that each call to {@link #addFixAndInfer(com.sap.sailing.domain.trackimport.GPSFixImporter.Callback, boolean, GPSFix)}
+ * remembers the fix just handled. The {@link #addFixAndInfer(com.sap.sailing.domain.trackimport.GPSFixImporter.Callback, boolean, GPSFix)} method
+ * therefore needs to be invoked with the fixes in ascending time point order.<p>
+ * 
+ * If the fixes delivered to {@link #addFixAndInfer(com.sap.sailing.domain.trackimport.GPSFixImporter.Callback, boolean, GPSFix)} are
+ * already of type {@link GPSFixMoving}, they are used as-is. Otherwise, except for the first fix which is dropped, COG/SOG values
+ * will be inferred, a {@link GPSFixMoving} will be constructed and forwarded to the callback instance.
+ * 
  * @author Fredrik Teschke
- *
+ * 
  */
 public abstract class BaseGPSFixImporterImpl implements GPSFixImporter {
     private GPSFix previousFix;
@@ -23,7 +32,6 @@ public abstract class BaseGPSFixImporterImpl implements GPSFixImporter {
             SpeedWithBearing speedWithBearing = previousFix.getSpeedAndBearingRequiredToReach(fix);
             fix = new GPSFixMovingImpl(fix.getPosition(), fix.getTimePoint(), speedWithBearing);
         }
-        
         previousFix = fix;
         callback.addFix(fix);
     }

java/com.sap.sailing.server.trackfiles/src/com/sap/sailing/server/trackfiles/common/GPSFixImporterRegistration.java

@@ -19,6 +19,12 @@ public class GPSFixImporterRegistration {
         return properties;
     }
     
+    /**
+     * Registers the <code>importer</code> as an OSGi service for the {@link GPSFixImporter} interface, once for each
+     * {@link GPSFixImporter#getSupportedFileExtensions() supported file extension} , using its
+     * {@link GPSFixImporter#getType() type} as the {@link TypeBasedServiceFinder#TYPE} property and the
+     * file extension as the {@link GPSFixImporter#FILE_EXTENSION_PROPERTY} property.
+     */
     public static Collection<ServiceRegistration<GPSFixImporter>>
         register(GPSFixImporter importer, BundleContext context) {
         List<ServiceRegistration<GPSFixImporter>> registrations = new ArrayList<>();