refactor: Improve TimetableSnapshotUpdateListener documentation and parameter naming

Author: t2gran

application/src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/mappers/RealTimeRaptorTransitDataUpdater.java

@@ -19,7 +19,7 @@
 import org.opentripplanner.transit.model.framework.FeedScopedId;
 import org.opentripplanner.transit.model.network.TripPattern;
 import org.opentripplanner.transit.model.timetable.Timetable;
-import org.opentripplanner.transit.model.timetable.TimetableSnapshotUpdateSucessListener;
+import org.opentripplanner.transit.model.timetable.TimetableSnapshotUpdateListener;
 import org.opentripplanner.transit.model.timetable.TripIdAndServiceDate;
 import org.opentripplanner.transit.model.timetable.TripTimes;
 import org.opentripplanner.transit.service.TimetableRepository;
@@ -38,7 +38,7 @@
  * incremental changes are applied to both the TimetableSnapshot and the RaptorTransitData and they are
  * published together.
  */
-public class RealTimeRaptorTransitDataUpdater implements TimetableSnapshotUpdateSucessListener {
+public class RealTimeRaptorTransitDataUpdater implements TimetableSnapshotUpdateListener {
 
   private static final Logger LOG = LoggerFactory.getLogger(RealTimeRaptorTransitDataUpdater.class);
 
@@ -91,9 +91,6 @@ public RealTimeRaptorTransitDataUpdater(TimetableRepository timetableRepository)
   ///       was for a scheduled trip, then the schedule should be restored.
   /// 3. Remove the `oldTripPatternsForDate` and add the `newTripPatternsForDate` to the
   ///    [RaptorTransitData].
-  ///
-  /// @param updatedTimetables that changed with the current snapshot
-  /// @param timetables which are affected by real-time updates
   @Override
   public void update(
     Collection<Timetable> updatedTimetables,

application/src/main/java/org/opentripplanner/transit/model/timetable/TimetableSnapshot.java

@@ -301,8 +301,6 @@ public Collection<? extends TripOnServiceDate> listRealTimeAddedTripOnServiceDat
    * does not exist yet in the Timetable, add it. This method will make a protective copy of the
    * Timetable if such a copy has not already been made while building up this snapshot, handling
    * both cases where patterns were pre-existing in static data or created by realtime data.
-   *
-   * @return whether the update was actually applied
    */
   public void update(RealTimeTripUpdate realTimeTripUpdate) {
     validateNotReadOnly();
@@ -368,7 +366,7 @@ public TimetableSnapshot commit() {
   }
 
   public TimetableSnapshot commit(
-    TimetableSnapshotUpdateSucessListener updatesEventListener,
+    @Nullable TimetableSnapshotUpdateListener updatesEventListener,
     boolean force
   ) {
     validateNotReadOnly();

application/src/main/java/org/opentripplanner/transit/model/timetable/TimetableSnapshotUpdateListener.java

@@ -0,0 +1,28 @@
+package org.opentripplanner.transit.model.timetable;
+
+import java.util.Collection;
+import java.util.SortedSet;
+import java.util.function.Function;
+import org.opentripplanner.transit.model.framework.FeedScopedId;
+
+/**
+ * Listener interface for receiving notifications when a {@link TimetableSnapshot}
+ * is updated with new real-time information.
+ * <p>
+ * Implement this interface and inject the listener into {@link TimetableSnapshot}
+ * to receive events after the snapshot is updated.
+ */
+public interface TimetableSnapshotUpdateListener {
+  /**
+   * Called after the {@link TimetableSnapshot} has been updated and the commit method has completed.
+   * <p>
+   * This event allows the implementer to update its own state using the newly updated timetables.
+   *
+   * @param updatedTimetables a collection of timetables that have been updated
+   * @param timetablesForTripPatternId a function to retrieve all timetables for a given trip pattern
+   */
+  void update(
+    Collection<Timetable> updatedTimetables,
+    Function<FeedScopedId, SortedSet<Timetable>> timetablesForTripPatternId
+  );
+}

application/src/main/java/org/opentripplanner/transit/model/timetable/TimetableSnapshotUpdateSucessListener.java

@@ -84,7 +84,7 @@ void testUniqueDirtyTimetablesAfterMultipleUpdates() {
 
     AtomicBoolean updateIsCalled = new AtomicBoolean();
 
-    var updateListener = new TimetableSnapshotUpdateSucessListener() {
+    var updateListener = new TimetableSnapshotUpdateListener() {
       @Override
       public void update(
         Collection<Timetable> updatedTimetables,