bug6241: clarify that runWhenPolarLoadingFinishedFor waits for a global drain

The Javadoc on PolarDataService.runWhenPolarLoadingFinishedFor (interface),
PolarDataMiner (impl) and the RacingEventServiceImpl.scheduleWindEstimationInstallation
caller all read as if the callback fired once the fixes belonging to the given
race had drained. In reality the loading pipeline (preFilteringProcessorForLoadedFixes)
is shared across all races and has no per-race completion tracking, so the
callback fires only on a global drain: when the fixes of every race ingested so
far have been processed.

The race parameter does not scope the wait; it only gates WHEN the callback may
attach to the shared drain, via two conditions that must both hold: (1) the
race's own fixes have been ingested (so the callback can't fire on a pipeline
that is merely momentarily idle before this race was queued), and (2)
markLoadingOfAllRacesToRestoreStarted() has been signalled (so an idle window
between two startup races' ingestion bursts isn't mistaken for a real drain).

This global-wait behavior is deliberate: we want the polar model to reflect all
loaded data before any maneuver-based wind estimation is installed, and we accept
the resulting startup sequentiality (an early race's estimator install waits
behind the whole loaded-fix backlog). Documentation only; no behavior change.
The method name is kept as-is.

java/com.sap.sailing.domain/src/com/sap/sailing/domain/polars/PolarDataService.java

@@ -157,14 +157,37 @@ public interface PolarDataService {
     void raceFinishedLoading(TrackedRace race, Runnable callbackWhenRaceChangingToTrackingOfFinishedStatus);
 
     /**
-     * Registers {@code callback} to fire once the polar-data loading pipeline has fully drained
-     * the fixes belonging to {@code race}. Unlike
-     * {@link #raceFinishedLoading(TrackedRace, Runnable)}, this method does <em>not</em> ingest
-     * the race's fixes; it only observes the pipeline. It is safe to call multiple times for the
-     * same race, and before or after {@link #raceFinishedLoading} has been called for it. If
-     * ingestion for the race hasn't started yet, the callback is parked until it does, so that
-     * the callback never fires prematurely on a pipeline that happens to be momentarily idle
-     * before this race's fixes were queued. See bug6241.
+     * Registers {@code callback} to fire once the polar-data loading pipeline has fully drained.
+     * <p>
+     *
+     * IMPORTANT — this waits for a <em>global</em> drain, not a per-race one. The loading pipeline
+     * is shared across all races, so the callback fires only when the fixes of <em>every</em>
+     * race ingested so far (not just {@code race}) have been processed. The {@code race} parameter
+     * does <em>not</em> scope the wait to that race; it only gates <em>when</em> the callback is
+     * allowed to start observing the drain, via two conditions that both must hold before the
+     * callback is attached to the pipeline's drain:
+     * <ol>
+     *   <li>{@code race}'s fixes have actually been ingested into the pipeline (i.e.
+     *   {@link #raceFinishedLoading(TrackedRace, Runnable)} has run for it). Without this gate the
+     *   callback could fire on a pipeline that is merely momentarily idle because this race's
+     *   fixes haven't been queued yet, producing an incomplete polar model for {@code race}.</li>
+     *   <li>{@link #markLoadingOfAllRacesToRestoreStarted()} has been signalled, so a transient
+     *   idle window between two startup races' ingestion bursts is not mistaken for a real
+     *   drain.</li>
+     * </ol>
+     * The consequence is intended: a caller waiting on {@code race} effectively waits for the
+     * whole loaded-fix backlog to be processed, which on a cold start of a large archive can be
+     * substantial (the estimator install for an early race waits behind every other race's polar
+     * ingestion). This "wait for everything" behavior is deliberate — we want the polar model to
+     * reflect all loaded data before any maneuver-based wind estimation is installed — and the
+     * mild sequentiality it implies is accepted. It is <em>not</em> a per-race isolation
+     * guarantee; do not rely on this firing as soon as only {@code race}'s own fixes are done.
+     * <p>
+     *
+     * Unlike {@link #raceFinishedLoading(TrackedRace, Runnable)}, this method does <em>not</em>
+     * ingest the race's fixes; it only observes the pipeline. It is safe to call multiple times
+     * for the same race, and before or after {@link #raceFinishedLoading} has been called for it.
+     * See bug6241.
      *
      * @param callback
      *            must not be {@code null}

java/com.sap.sailing.polars/src/com/sap/sailing/polars/mining/PolarDataMiner.java

@@ -670,11 +670,18 @@ public class PolarDataMiner {
 
     /**
      * Registers {@code callback} to fire once the {@link #preFilteringProcessorForLoadedFixes
-     * loading pipeline} has fully drained the fixes belonging to {@code race} <em>and</em> the
-     * caller has announced (via {@link #markLoadingOfAllRacesToRestoreStarted()}) that no further
-     * startup races will be added. Unlike {@link #raceFinishedLoading(TrackedRace, Runnable)},
-     * this method does <em>not</em> ingest the race's fixes into the pipeline; it only observes
-     * the pipeline. It may be called any number of times for the same race, before or after
+     * loading pipeline} has fully drained <em>globally</em> (i.e. the fixes of <em>every</em>
+     * race ingested so far, not only {@code race}) <em>and</em> the caller has announced (via
+     * {@link #markLoadingOfAllRacesToRestoreStarted()}) that no further startup races will be
+     * added. The {@code race} parameter does not scope the wait to that race's fixes -- the
+     * terminal processors are shared and there is no per-race completion tracking; it only gates
+     * <em>when</em> the callback is allowed onto the shared drain (see the two conditions below).
+     * Waiting on {@code race} therefore effectively waits for the whole loaded-fix backlog; this
+     * "wait for everything" behavior is intended (we want the polar model complete before any
+     * maneuver-based wind estimation is installed) even though it introduces some sequentiality
+     * on a large cold start. Unlike {@link #raceFinishedLoading(TrackedRace, Runnable)}, this
+     * method does <em>not</em> ingest the race's fixes into the pipeline; it only observes the
+     * pipeline. It may be called any number of times for the same race, before or after
      * {@code raceFinishedLoading} has been called for that race, and before or after the
      * "loading started" signal has flipped.
      * <p>

java/com.sap.sailing.selenium.test/ci-test-environment.xml

@@ -27,7 +27,7 @@
   
   <!--
     In this section necessary system properties for the different web drivers can be provided if needed. For more
-    information about available properties see the following sites:
+    informations about available properties see the following sides:
     
     - http://code.google.com/p/selenium/wiki/ChromeDriver
     - http://code.google.com/p/selenium/wiki/FirefoxDriver
@@ -36,9 +36,8 @@
     - http://code.google.com/p/selenium/wiki/SafariDriver
     - http://code.google.com/p/selenium/wiki/RemoteWebDriverServer
     
-        
-    Note: For the Chrome and the Internet Explorer driver an additional "server", which acts as a bridge between the
-    browser and the driver, is needed.
+    NOTE: For the Chrome and the InternetExplorer driver an additional "server", which acts as a bridge between the
+          browser and the driver, is needed.
   -->
   <system-properties>
      <system-property>

java/com.sap.sailing.server/src/com/sap/sailing/server/impl/RacingEventServiceImpl.java

@@ -4824,13 +4824,16 @@ Replicator {
      *       used by, e.g., RaceLogRaceTracker-tracked races without loadable data. If the
      *       race is removed from its regatta before the transition, the install is silently
      *       cancelled.</li>
-     *   <li>the polar-data mining pipeline has drained this race's loaded fixes (see
+     *   <li>the polar-data mining pipeline has drained (see
      *       {@link PolarDataService#runWhenPolarLoadingFinishedFor(TrackedRace, Runnable)}).
-     *       This is essential because the estimator captures the polar service at
-     *       construction time and uses it for classification and wind-speed inference; if
-     *       we installed the estimator before the polars for this race had been fed to the
-     *       polar-data service, the estimator would be permanently using a polar model that
-     *       reflects an incomplete data set.</li>
+     *       Note that this is a <em>global</em> drain of the shared loading pipeline, gated so
+     *       it does not fire before this race's own fixes have been ingested; it waits for the
+     *       fixes of all races loaded so far, not just this one. That is essential because the
+     *       estimator captures the polar service at construction time and uses it for
+     *       classification and wind-speed inference; installing the estimator before the polars
+     *       had been fully mined would leave it permanently using a polar model that reflects an
+     *       incomplete data set. Waiting for the global drain is deliberate and accepts some
+     *       startup sequentiality in exchange for a complete polar model.</li>
      * </ul>
      * <p>
      *