Carpooling POC

application/src/ext/java/org/opentripplanner/ext/carpooling/CarpoolingRepository.java

@@ -0,0 +1,42 @@
+package org.opentripplanner.ext.carpooling;
+
+import java.util.Collection;
+import org.opentripplanner.ext.carpooling.model.CarpoolTrip;
+
+/**
+ * Repository for managing carpooling trip ({@link CarpoolTrip}) data.
+ * <p>
+ * This repository maintains an in-memory index of driver trips.
+ *
+ * @see CarpoolTrip for trip data model
+ * @see org.opentripplanner.ext.carpooling.updater.SiriETCarpoolingUpdater for real-time updates
+ */
+public interface CarpoolingRepository {
+  /**
+   * Returns all currently carpooling trips.
+   * <p>
+   * The returned collection includes all driver trips that have been added via {@link #upsertCarpoolTrip}
+   * and not yet removed or expired. The collection is typically used by the routing service to find
+   * compatible trips for passengers.
+   */
+  Collection<CarpoolTrip> getCarpoolTrips();
+
+  /**
+   * Inserts a new carpooling trip or updates an existing trip with the same ID.
+   * <p>
+   * This method is the primary mechanism for adding driver trip data to the repository. It is
+   * typically called by real-time updaters when receiving trip information from external systems,
+   * or when passenger bookings modify trip capacity.
+   *
+   * <h3>Validation</h3>
+   * <p>
+   * The method does not validate trip data beyond basic null checks. It is the caller's
+   * responsibility to ensure the trip is valid (has stops, positive capacity, etc.). Invalid
+   * trips may cause routing failures later.
+   *
+   * @param trip the carpool trip to insert or update, must not be null. If a trip with the same
+   *        ID exists, it will be completely replaced.
+   * @throws IllegalArgumentException if trip is null
+   */
+  void upsertCarpoolTrip(CarpoolTrip trip);
+}

application/src/ext/java/org/opentripplanner/ext/carpooling/CarpoolingService.java

@@ -0,0 +1,28 @@
+package org.opentripplanner.ext.carpooling;
+
+import java.util.List;
+import org.opentripplanner.model.plan.Itinerary;
+import org.opentripplanner.routing.api.request.RouteRequest;
+import org.opentripplanner.routing.error.RoutingValidationException;
+
+/**
+ * Service for finding carpooling options by matching passenger requests with available driver trips.
+ * <p>
+ * Carpooling enables passengers to join existing driver journeys by being picked up and dropped off
+ * along the driver's route. The service finds optimal insertion points for new passengers while
+ * respecting capacity constraints, time windows, and route deviation budgets.
+ */
+public interface CarpoolingService {
+  /**
+   * Finds carpooling itineraries matching the passenger's routing request.
+   * <p>
+   *
+   * @param request the routing request containing passenger origin, destination, and preferences
+   * @return list of carpool itineraries, sorted by quality (additional travel time), may be empty
+   *         if no compatible trips found. Results are limited to avoid overwhelming users.
+   * @throws RoutingValidationException if the request is invalid (missing origin/destination,
+   *         invalid coordinates, etc.)
+   * @throws IllegalArgumentException if request is null
+   */
+  List<Itinerary> route(RouteRequest request) throws RoutingValidationException;
+}