docs(routing): javadoc

fed/mosaic-application/src/main/java/org/eclipse/mosaic/fed/application/ambassador/simulation/navigation/CentralNavigationComponent.java

@@ -90,7 +90,7 @@ public class CentralNavigationComponent {
 
 
     /**
-     * Public Transport routing
+     * Access to Public Transport routing.
      */
     private PtRouting ptRouting;
 

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/MultiModalLeg.java

@@ -17,28 +17,54 @@
 
 import org.eclipse.mosaic.lib.objects.vehicle.VehicleDeparture;
 
+/**
+ * A leg of a multi-modal-journey consists of a planned departure and planned arrival time, and
+ * details about the transport mode, such as the walking path or the public transport route.
+ */
 public class MultiModalLeg {
 
     public enum Type {
-        WALKING, VEHICLE_SHARED, VEHICLE_PRIVATE, PUBLIC_TRANSPORT
+        /**
+         * For legs which uses public transport.
+         */
+        PUBLIC_TRANSPORT,
+        /**
+         * For legs which will require foot work.
+         */
+        WALKING,
+        /**
+         * For legs which require to spawn a new vehicle.
+         */
+        VEHICLE_PRIVATE,
+        /**
+         * For legs which uses a shared vehicle which already exists in the simulation.
+         */
+        VEHICLE_SHARED
     }
 
     private final Type legType;
+    private final long departureTime;
+    private final long arrivalTime;
 
-    // For legs where a vehicle needs to be spawned
-    private VehicleDeparture vehicleLeg = null;
-
-    // For public transport legs
+    /**
+     * For legs which uses public transport.
+     */
     private PtLeg publicTransportationLeg = null;
 
-    // For walk legs
+    /**
+     * For legs which will require foot work.
+     */
     private WalkLeg walkLeg = null;
 
-    // For legs where a vehicle already exists
-    private String sharedVehicleId = null;
+    /**
+     * For legs which require to spawn a new vehicle.
+     */
+    private VehicleDeparture vehicleLeg = null;
 
-    public long departureTime;
-    public long arrivalTime;
+    /**
+     * For legs which uses a shared vehicle which already exists in the simulation.
+     */
+    private String sharedVehicleId = null;
 
     /**
      * Creates a new leg in which a new vehicle must be spawned.
@@ -84,6 +110,18 @@ public MultiModalLeg(String vehicleId, long departureTime, long arrivalTime) {
         this.arrivalTime = arrivalTime;
     }
 
+    public long getArrivalTime() {
+        return arrivalTime;
+    }
+
+    public long getDepartureTime() {
+        return departureTime;
+    }
+
+    public Type getLegType() {
+        return legType;
+    }
+
     public Object getLeg() {
         return switch (legType) {
             case VEHICLE_PRIVATE -> vehicleLeg;
@@ -92,8 +130,4 @@ public Object getLeg() {
             case WALKING -> walkLeg;
         };
     }
-
-    public Type getLegType() {
-        return legType;
-    }
 }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/MultiModalRoute.java

@@ -18,6 +18,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A multi-modal route which consists of multiple legs.
+ */
 public class MultiModalRoute {
 
     private final List<MultiModalLeg> legs = new ArrayList<>();
@@ -26,6 +29,9 @@ public MultiModalRoute(List<MultiModalLeg> legs) {
         this.legs.addAll(legs);
     }
 
+    /**
+     * Returns the individual legs of this multi-modal route.
+     */
     public List<MultiModalLeg> getLegs() {
         return this.legs;
     }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/PtLeg.java

@@ -20,16 +20,29 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A public transport leg contains all pt stops of the route.
+ */
 public class PtLeg {
 
-    public record PtStop(GeoPoint location, Long departureTime, Long arrivalTime) {}
+    /**
+     * Each public transport stop consists of its geo-location and the planned arrival and departure time at this stop.
+     *
+     * @param location The geographic location of the stop.
+     * @param arrivalTime The time when arriving at this stop. {@code null} for the first stop of the leg.
+     * @param departureTime The time when leaving this stop. {@code null} for the last stop of the leg.
+     */
+    public record PtStop(GeoPoint location, Long arrivalTime, Long departureTime) {}
 
     private final List<PtStop> stops = new ArrayList<>();
 
     public PtLeg(List<PtStop> stops) {
         this.stops.addAll(stops);
     }
 
+    /**
+     * Returns the list of stops along the public transport route.
+     */
     public List<PtStop> getStops() {
         return stops;
     }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/PtRouting.java

@@ -17,6 +17,7 @@
 
 import org.eclipse.mosaic.lib.geo.GeoPoint;
 import org.eclipse.mosaic.lib.routing.config.CPublicTransportRouting;
+import org.eclipse.mosaic.rti.UNITS;
 
 import com.google.common.collect.Iterables;
 import com.graphhopper.GHResponse;
@@ -130,7 +131,7 @@ public PtRoutingResponse findPtRoute(PtRoutingRequest request) {
         );
         // ghRequest.setBlockedRouteTypes(request.getRoutingParameters().excludedPtModes);//FIXME generalize this
         ghRequest.setEarliestDepartureTime(departureTime);
-        ghRequest.setWalkSpeedKmH(request.getRoutingParameters().getWalkingSpeedMps() * 3.6);
+        ghRequest.setWalkSpeedKmH(request.getRoutingParameters().getWalkingSpeedMps() / UNITS.KMH);
 
         final Future<GHResponse> responseFuture = routingExecution.submit(() -> ptRouter.route(ghRequest));
         final GHResponse route;
@@ -160,8 +161,8 @@ private List<MultiModalLeg> convertToMultiModalLegs(ResponsePath ghBestRoute) {
                 for (Trip.Stop stop : ptLeg.stops) {
                     newStops.add(new PtLeg.PtStop(
                             GeoPoint.lonLat(stop.geometry.getX(), stop.geometry.getY()),
-                            fromScheduleTime(stop.departureTime),
-                            fromScheduleTime(stop.arrivalTime)
+                            fromScheduleTime(stop.arrivalTime),
+                            fromScheduleTime(stop.departureTime)
                     ));
                 }
                 legs.add(new MultiModalLeg(

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/PtRoutingParameters.java

@@ -15,12 +15,14 @@
 
 package org.eclipse.mosaic.lib.routing.pt;
 
+import org.eclipse.mosaic.rti.UNITS;
+
 public class PtRoutingParameters {
 
-    private double walkingSpeedMps = 5 / 3.6;
+    private double walkingSpeedMps = 5 * UNITS.KILOMETER_PER_HOUR;
 
     public PtRoutingParameters walkingSpeedKmh(double kmh) {
-        walkingSpeedMps = kmh / 3.6;
+        walkingSpeedMps = kmh * UNITS.KILOMETER_PER_HOUR;
         return this;
     }
 

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/PtRoutingRequest.java

@@ -25,10 +25,25 @@ public class PtRoutingRequest {
 
     private final PtRoutingParameters routingParameters;
 
+    /**
+     * Constructs a request for calculating a public transport route.
+     *
+     * @param requestTime The earliest time to start the journey.
+     * @param from The geographic location to start the journey.
+     * @param to The geographic location to end the journey.
+     */
     public PtRoutingRequest(long requestTime, GeoPoint from, GeoPoint to) {
         this(requestTime, from, to, new PtRoutingParameters());
     }
 
+    /**
+     * Constructs a request for calculating a public transport route.
+     *
+     * @param requestTime The earliest time to start the journey.
+     * @param from The geographic location to start the journey.
+     * @param to The geographic location to end the journey.
+     * @param additionalParameters Additional parameters, such as walking speed.
+     */
     public PtRoutingRequest(long requestTime, GeoPoint from, GeoPoint to, PtRoutingParameters additionalParameters) {
         this.requestTime = requestTime;
         this.startingGeoPoint = from;

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/PtRoutingResponse.java

@@ -15,6 +15,10 @@
 
 package org.eclipse.mosaic.lib.routing.pt;
 
+/**
+ * The result of the routing request. Contains the multi-modal route which
+ * matches the routing request at best.
+ */
 public class PtRoutingResponse {
 
     private final MultiModalRoute bestRoute;
@@ -23,7 +27,10 @@ public PtRoutingResponse(MultiModalRoute bestRoute) {
         this.bestRoute = bestRoute;
     }
 
-    public MultiModalRoute getBestRoute() {
+    /**
+     * Returns the best multi-modal route of the route calculation.
+     */
+    public final MultiModalRoute getBestRoute() {
         return bestRoute;
     }
 }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/pt/WalkLeg.java

@@ -20,6 +20,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A walking leg contains a linestring of geographical points which form the walking route.
+ */
 public class WalkLeg {
 
     private final List<GeoPoint> waypoints = new ArrayList<>();
@@ -28,7 +31,10 @@ public WalkLeg(List<GeoPoint> waypoints) {
         this.waypoints.addAll(waypoints);
     }
 
-    public List<GeoPoint> getWaypoints() {
+    /**
+     * Returns the list of geographical positions which form the walking route.
+     */
+    public final List<GeoPoint> getWaypoints() {
         return waypoints;
     }
 }