Merge pull request #21 from naviqore/review/NAV-52-define-interfaces-…

…for-service

REFACTOR: NAV-52 - Remove redundancy in public transit service interface

.mvn/wrapper/MavenWrapperDownloader.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 import java.net.*;
 import java.io.*;
 import java.nio.channels.*;
@@ -24,21 +25,18 @@ public class MavenWrapperDownloader {
     /**
      * Default URL to download the maven-wrapper.jar from, if no 'downloadUrl' is provided.
      */
-    private static final String DEFAULT_DOWNLOAD_URL = "https://repo.maven.apache.org/maven2/io/takari/maven-wrapper/"
-        + WRAPPER_VERSION + "/maven-wrapper-" + WRAPPER_VERSION + ".jar";
+    private static final String DEFAULT_DOWNLOAD_URL = "https://repo.maven.apache.org/maven2/io/takari/maven-wrapper/" + WRAPPER_VERSION + "/maven-wrapper-" + WRAPPER_VERSION + ".jar";
 
     /**
-     * Path to the maven-wrapper.properties file, which might contain a downloadUrl property to
-     * use instead of the default one.
+     * Path to the maven-wrapper.properties file, which might contain a downloadUrl property to use instead of the
+     * default one.
      */
-    private static final String MAVEN_WRAPPER_PROPERTIES_PATH =
-            ".mvn/wrapper/maven-wrapper.properties";
+    private static final String MAVEN_WRAPPER_PROPERTIES_PATH = ".mvn/wrapper/maven-wrapper.properties";
 
     /**
      * Path where the maven-wrapper.jar will be saved to.
      */
-    private static final String MAVEN_WRAPPER_JAR_PATH =
-            ".mvn/wrapper/maven-wrapper.jar";
+    private static final String MAVEN_WRAPPER_JAR_PATH = ".mvn/wrapper/maven-wrapper.jar";
 
     /**
      * Name of the property which should be used to override the default download url for the wrapper.
@@ -54,7 +52,7 @@ public static void main(String args[]) {
         // wrapperUrl parameter.
         File mavenWrapperPropertyFile = new File(baseDirectory, MAVEN_WRAPPER_PROPERTIES_PATH);
         String url = DEFAULT_DOWNLOAD_URL;
-        if(mavenWrapperPropertyFile.exists()) {
+        if (mavenWrapperPropertyFile.exists()) {
             FileInputStream mavenWrapperPropertyFileInputStream = null;
             try {
                 mavenWrapperPropertyFileInputStream = new FileInputStream(mavenWrapperPropertyFile);
@@ -65,7 +63,7 @@ public static void main(String args[]) {
                 System.out.println("- ERROR loading '" + MAVEN_WRAPPER_PROPERTIES_PATH + "'");
             } finally {
                 try {
-                    if(mavenWrapperPropertyFileInputStream != null) {
+                    if (mavenWrapperPropertyFileInputStream != null) {
                         mavenWrapperPropertyFileInputStream.close();
                     }
                 } catch (IOException e) {
@@ -76,8 +74,8 @@ public static void main(String args[]) {
         System.out.println("- Downloading from: " + url);
 
         File outputFile = new File(baseDirectory.getAbsolutePath(), MAVEN_WRAPPER_JAR_PATH);
-        if(!outputFile.getParentFile().exists()) {
-            if(!outputFile.getParentFile().mkdirs()) {
+        if (!outputFile.getParentFile().exists()) {
+            if (!outputFile.getParentFile().mkdirs()) {
                 System.out.println(
                         "- ERROR creating output directory '" + outputFile.getParentFile().getAbsolutePath() + "'");
             }

pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xmlns="http://maven.apache.org/POM/4.0.0"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 

src/main/java/ch/naviqore/service/Connection.java

@@ -1,30 +1,12 @@
 package ch.naviqore.service;
 
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-
 import java.util.List;
 
+/**
+ * A connection in a public transit schedule, consisting of multiple public transit legs and walks.
+ */
 public interface Connection {
-    @NotNull List<Leg> getLegs();
-
-    @NotNull Location getStartLocation();
-
-    @NotNull Location getEndLocation();
-
-    @Nullable Stop getStartStop();
-
-    @Nullable Stop getEndStop();
-
-    @NotNull ArrivalTime getArrivalTime();
-
-    @NotNull DepartureTime getDepartureTime();
-
-    int getDuration();
-
-    int getBeeLineDistance();
 
-    int getNumTransfers();
+    List<Leg> getLegs();
 
-    int getWalkingDistance();
 }

src/main/java/ch/naviqore/service/Leg.java

@@ -1,22 +1,38 @@
 package ch.naviqore.service;
 
-import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.time.LocalDateTime;
+
+/**
+ * Represents a leg of a connection, including its order, distance, and duration.
+ */
 public interface Leg {
-    @NotNull Location getDepartureLocation();
 
-    @NotNull Location getArrivalLocation();
+    LegType getLegType();
+
+    Location getSourceLocation();
+
+    Location getTargetLocation();
+
+    LocalDateTime getArrivalTime();
 
-    @Nullable Stop getDepartureStop();
+    LocalDateTime getDepartureTime();
 
-    @Nullable Stop getArrivalStop();
+    int getDistance();
 
-    @NotNull DepartureTime getDepartureTime();
+    int getDuration();
 
-    @NotNull ArrivalTime getArrivalTime();
+    /**
+     * The target public transit stop, if walk starts at a stop.
+     */
+    @Nullable
+    Stop getSourceStop();
 
-    @Nullable Trip getTrip();
+    /**
+     * The target public transit stop, if walk ends at a stop.
+     */
+    @Nullable
+    Stop getTargetStop();
 
-    @Nullable Walk getWalk();
 }

src/main/java/ch/naviqore/service/LegType.java

@@ -0,0 +1,6 @@
+package ch.naviqore.service;
+
+public enum LegType {
+    PUBLIC_TRANSIT,
+    WALK
+}

src/main/java/ch/naviqore/service/Location.java

@@ -1,7 +1,9 @@
 package ch.naviqore.service;
 
 public interface Location {
+
     double getLatitude();
 
     double getLongitude();
+
 }

src/main/java/ch/naviqore/service/PublicTransitLeg.java

@@ -0,0 +1,19 @@
+package ch.naviqore.service;
+
+import org.jetbrains.annotations.NotNull;
+
+public interface PublicTransitLeg extends Leg {
+
+    StopTime getArrival();
+
+    StopTime getDeparture();
+
+    @Override
+    @NotNull
+    Stop getSourceStop();
+
+    @Override
+    @NotNull
+    Stop getTargetStop();
+
+}

src/main/java/ch/naviqore/service/PublicTransitService.java

@@ -0,0 +1,109 @@
+package ch.naviqore.service;
+
+import ch.naviqore.service.config.ConnectionQueryConfig;
+import ch.naviqore.service.exception.RouteNotFoundException;
+import ch.naviqore.service.exception.StopNotFoundException;
+import ch.naviqore.service.exception.TripNotFoundException;
+import org.jetbrains.annotations.Nullable;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Public transit service with methods to retrieve stops, trips, routes, and connections.
+ */
+public interface PublicTransitService {
+
+    /**
+     * Searches for stops by name.
+     *
+     * @param like       the search term to match against stop names
+     * @param searchType the type of search to perform (STARTS_WITH, ENDS_WITH, CONTAINS, EXACT)
+     * @return a list of stops matching the search criteria
+     */
+    List<Stop> getStops(String like, SearchType searchType);
+
+    /**
+     * Retrieves the nearest stop to a given location.
+     *
+     * @param location the location to search around
+     * @return the nearest stop to the specified location, or null if no stop is found
+     */
+    @Nullable
+    Stop getNearestStop(Location location);
+
+    /**
+     * Retrieves the nearest stops to a given location within a specified radius.
+     *
+     * @param location the location to search around
+     * @param radius   the radius to search within, in meters
+     * @param limit    the maximum number of stops to retrieve
+     * @return a list of the nearest stops to the specified location within the given radius
+     */
+    List<Stop> getNearestStops(Location location, int radius, int limit);
+
+    /**
+     * Retrieves the next departures from a specific stop within a given date range.
+     *
+     * @param stop  the stop for which to retrieve departures
+     * @param from  the start date for the departures
+     * @param until the end date for the departures (nullable)
+     * @param limit the maximum number of departures to retrieve
+     * @return a list of upcoming departures from the specified stop
+     */
+    List<StopTime> getNextDepartures(Stop stop, LocalDate from, @Nullable LocalDate until, int limit);
+
+    /**
+     * Retrieves possible connections between two locations at a specified time.
+     *
+     * @param source   the starting location
+     * @param target   the destination location
+     * @param time     the time of departure or arrival
+     * @param timeType the type of time specified (departure or arrival)
+     * @param config   additional configuration for the query
+     * @return a list of possible connections between the source and target locations
+     */
+    List<Connection> getConnections(Location source, Location target, LocalDateTime time, TimeType timeType,
+                                    ConnectionQueryConfig config);
+
+    /**
+     * Retrieves the shortest possible connection to each stop from a given departure location and time  within a given
+     * time budget or a maximum number of transfers.
+     *
+     * @param source        the location to start the journey from
+     * @param departureTime the time of departure
+     * @param config        additional configuration for the query
+     * @return a map of stops to the shortest possible connection to each stop from the departure location
+     */
+    Map<Stop, Connection> isoline(Location source, LocalDateTime departureTime, ConnectionQueryConfig config);
+
+    /**
+     * Retrieves a stop by its ID.
+     *
+     * @param stopId the ID of the stop to retrieve
+     * @return the stop with the specified ID
+     * @throws StopNotFoundException if no stop with the specified ID is found
+     */
+    Stop getStopById(String stopId) throws StopNotFoundException;
+
+    /**
+     * Retrieves a trip by its ID.
+     *
+     * @param tripId the ID of the trip to retrieve
+     * @return the trip with the specified ID
+     * @throws TripNotFoundException if no trip with the specified ID is found
+     */
+    Trip getTripById(String tripId) throws TripNotFoundException;
+
+    /**
+     * Retrieves a route by its ID.
+     *
+     * @param routeId the ID of the route to retrieve
+     * @return the route with the specified ID
+     * @throws RouteNotFoundException if no route with the specified ID is found
+     */
+    Route getRouteById(String routeId) throws RouteNotFoundException;
+
+}

src/main/java/ch/naviqore/service/Route.java

@@ -1,12 +1,20 @@
 package ch.naviqore.service;
 
-import org.jetbrains.annotations.NotNull;
-
+/**
+ * A public transit route (also called transit line).
+ */
 public interface Route {
-    @NotNull String getRouteId();
-    @NotNull String getRouteName();
-    @NotNull String getRouteShortName();
-    @NotNull String getRouteDescription();
-    @NotNull String getRouteType();
-    @NotNull String getAgency();
+
+    String getId();
+
+    String getName();
+
+    String getShortName();
+
+    String getDescription();
+
+    String getRouteType();
+
+    String getAgency();
+
 }