JSpecify

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-01-02
+
+### Added
+
+- JSpecify `@NonNull` annotations to public API methods and classes for improved nullability contracts.
+- `org.jspecify:jspecify:1.0.0` dependency for nullability annotations.
+
 ## [3.0.4] - 2025-12-30
 
 ### Changed
@@ -41,14 +48,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- A new type `UpcomingBusArrival` representing upcoming bus arrival information.
-- A new type `BusCoordinates` representing bus coordinates (latitude, longitude, heading).
-- An `arrivals` field of type `List<UpcomingBusArrival>` has been added to the `Bus` class to provide information about upcoming bus arrivals.
+- A new type `UpcomingBusArrival` representing upcoming vehicle arrival information.
+- A new type `BusCoordinates` representing vehicle coordinates (latitude, longitude, heading).
+- An `arrivals` field of type `List<UpcomingBusArrival>` has been added to the `Bus` class to provide information about upcoming vehicle arrivals.
 
 ### Changed
 
 - BREAKING CHANGE: Organized classes into packages by functionality:
-  - `com.cta4j.bus` for bus-related classes
+  - `com.cta4j.vehicle` for vehicle-related classes
   - `com.cta4j.train` for train-related classes
   - `com.cta4j.common` for shared/common classes
 - BREAKING CHANGE: Public concrete client classes replaced by interfaces with a fluent `Builder` API (e.g. `BusClient`, `TrainClient`)
@@ -129,7 +136,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Vehicle` class and `getVehicle` method in `BusClient` class.
 - `parseString` method from `BusPredictionType` enum.
 - `fromExternal` method from `Detour` class.
-- `fromExternal` method from bus `Route` class.
+- `fromExternal` method from vehicle `Route` class.
 - `fromExternal` method from `Stop` class.
 - `fromExternal` method from `StopArrival` class.
 - `parseString` method from train `Route` enum.
@@ -146,7 +153,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `TrainClient` class with methods to interact with CTA Train API.
 - `BusClient` class with methods to interact with CTA Bus API.
 
-[Unreleased]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v3.0.4...HEAD
+[Unreleased]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v3.0.4...v4.0.0
 [3.0.4]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v3.0.3...v3.0.4
 [3.0.3]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v3.0.2...v3.0.3
 [3.0.2]: https://github.com/lbkulinski/cta4j-java-sdk/compare/v3.0.1...v3.0.2

README.md

@@ -54,7 +54,7 @@ implementation("com.cta4j:cta4j-java-sdk:3.0.4")
 import com.cta4j.train.client.TrainClient;
 
 public final class Application {
-    public static void main(String[] args) {
+    static void main(String[] args) {
         TrainClient trainClient = TrainClient.builder()
                                              .apiKey("TRAIN_API_KEY")
                                              .build();
@@ -79,30 +79,30 @@ public final class Application {
 }
 ```
 
-### Fetch upcoming bus arrivals for a stop
+### Fetch upcoming vehicle arrivals for a stop
 
 ```java
-import com.cta4j.bus.client.BusClient;
+import com.cta4j.vehicle.client.BusClient;
 
 public final class Application {
-    public static void main(String[] args) {
+    static void main(String[] args) {
         BusClient busClient = BusClient.builder()
                                        .apiKey("BUS_API_KEY")
                                        .build();
 
-        busClient.getStopArrivals("22", "1828")
+        busClient.findArrivalsByRouteIdAndStopId("22", "1828")
                  .stream()
                  .map(arrival -> String.format(
-                     "%s-bound bus is arriving at %s in %d minutes",
+                     "%s-bound vehicle is arriving at %s in %d minutes",
                      arrival.destination(),
                      arrival.stopName(),
                      arrival.etaMinutes()
                  ))
                  .forEach(System.out::println);
 
         // Example output:
-        // Harrison-bound bus is arriving at Clark & Belmont in 1 minutes
-        // Harrison-bound bus is arriving at Clark & Belmont in 26 minutes
+        // Harrison-bound vehicle is arriving at Clark & Belmont in 1 minutes
+        // Harrison-bound vehicle is arriving at Clark & Belmont in 26 minutes
     }
 }
 ```

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.cta4j</groupId>
     <artifactId>cta4j-java-sdk</artifactId>
-    <version>3.0.4</version>
+    <version>4.0.0</version>
     <properties>
         <maven.compiler.source>21</maven.compiler.source>
         <maven.compiler.target>21</maven.compiler.target>
@@ -45,7 +45,7 @@
         </dependency>
         <dependency>
             <groupId>org.apache.httpcomponents.client5</groupId>
-            <artifactId>httpclient5</artifactId>
+            <artifactId>httpclient5-fluent</artifactId>
             <version>5.6</version>
         </dependency>
         <dependency>
@@ -54,9 +54,33 @@
             <version>26.0.2-1</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+            <version>1.0.0</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mapstruct</groupId>
+            <artifactId>mapstruct</artifactId>
+            <version>1.6.3</version>
+        </dependency>
     </dependencies>
     <build>
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.mapstruct</groupId>
+                            <artifactId>mapstruct-processor</artifactId>
+                            <version>1.6.3</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-source-plugin</artifactId>
@@ -68,9 +92,9 @@
                         <goals><goal>jar</goal></goals>
                         <configuration>
                             <excludes>
-                                <exclude>com/cta4j/bus/client/internal/**</exclude>
-                                <exclude>com/cta4j/bus/external/**</exclude>
-                                <exclude>com/cta4j/bus/mapper/**</exclude>
+                                <exclude>com/cta4j/vehicle/client/internal/**</exclude>
+                                <exclude>com/cta4j/vehicle/external/**</exclude>
+                                <exclude>com/cta4j/vehicle/mapper/**</exclude>
                                 <exclude>com/cta4j/train/client/internal/**</exclude>
                                 <exclude>com/cta4j/train/external/**</exclude>
                                 <exclude>com/cta4j/train/mapper/**</exclude>
@@ -92,7 +116,7 @@
                     </execution>
                 </executions>
                 <configuration>
-                    <excludePackageNames>com.cta4j.bus.client.internal.*,com.cta4j.bus.external.*,com.cta4j.bus.mapper.*,com.cta4j.train.client.internal.*,com.cta4j.train.external.*,com.cta4j.train.mapper.*,com.cta4j.util.*</excludePackageNames>
+                    <excludePackageNames>com.cta4j.vehicle.client.internal.*,com.cta4j.vehicle.external.*,com.cta4j.vehicle.mapper.*,com.cta4j.train.client.internal.*,com.cta4j.train.external.*,com.cta4j.train.mapper.*,com.cta4j.bus.internal.util.*</excludePackageNames>
                 </configuration>
             </plugin>
             <plugin>

src/main/java/com/cta4j/bus/BusApi.java

@@ -0,0 +1,126 @@
+package com.cta4j.bus;
+
+import com.cta4j.bus.detour.DetoursApi;
+import com.cta4j.bus.direction.DirectionsApi;
+import com.cta4j.bus.internal.impl.BusApiImpl;
+import com.cta4j.bus.locale.LocalesApi;
+import com.cta4j.bus.pattern.PatternsApi;
+import com.cta4j.bus.prediction.PredictionsApi;
+import com.cta4j.bus.route.RoutesApi;
+import com.cta4j.bus.stop.StopsApi;
+import com.cta4j.bus.vehicle.VehiclesApi;
+import org.jspecify.annotations.NullMarked;
+
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * Primary entry point for interacting with the CTA Bus Tracker API.
+ * <p>
+ * This interface provides access to the current system time as well as
+ * grouped sub-APIs for vehicles, routes, directions, stops, patterns,
+ * predictions, locales, and detours.
+ * <p>
+ * Instances of {@code BusApi} are immutable and thread-safe once built.
+ * Use {@link #builder(String)} to construct a configured instance.
+ */
+@NullMarked
+public interface BusApi {
+    /**
+     * Returns the current system time reported by the Bus Tracker API.
+     *
+     * @return the API system time as an {@link Instant}
+     */
+    Instant systemTime();
+
+    /**
+     * Provides access to vehicle-related endpoints.
+     *
+     * @return the {@link VehiclesApi}
+     */
+    VehiclesApi vehicles();
+
+    /**
+     * Provides access to route-related endpoints.
+     *
+     * @return the {@link RoutesApi}
+     */
+    RoutesApi routes();
+
+    /**
+     * Provides access to direction-related endpoints.
+     *
+     * @return the {@link DirectionsApi}
+     */
+    DirectionsApi directions();
+
+    /**
+     * Provides access to stop-related endpoints.
+     *
+     * @return the {@link StopsApi}
+     */
+    StopsApi stops();
+
+    /**
+     * Provides access to route pattern–related endpoints.
+     *
+     * @return the {@link PatternsApi}
+     */
+    PatternsApi patterns();
+
+    /**
+     * Provides access to prediction and arrival-related endpoints.
+     *
+     * @return the {@link PredictionsApi}
+     */
+    PredictionsApi predictions();
+
+    /**
+     * Provides access to locale and language-related endpoints.
+     *
+     * @return the {@link LocalesApi}
+     */
+    LocalesApi locales();
+
+    /**
+     * Provides access to detour-related endpoints.
+     *
+     * @return the {@link DetoursApi}
+     */
+    DetoursApi detours();
+
+    /**
+     * Builder for constructing {@link BusApi} instances.
+     */
+    interface Builder {
+        /**
+         * Sets the API host to use for requests.
+         * <p>
+         * If not specified, the default CTA Bus Tracker API host is used.
+         *
+         * @param host the API host
+         * @return this builder instance
+         */
+        Builder host(String host);
+
+        /**
+         * Builds a configured {@link BusApi} instance.
+         *
+         * @return a new {@link BusApi}
+         */
+        BusApi build();
+    }
+
+    /**
+     * Creates a new {@link Builder} for constructing a {@link BusApi}.
+     *
+     * @param apiKey the CTA Bus Tracker API key
+     * @return a new {@link Builder}
+     * @throws NullPointerException if {@code apiKey} is {@code null}
+     */
+    static Builder builder(String apiKey) {
+        Objects.requireNonNull(apiKey);
+
+        return new BusApiImpl.BuilderImpl(apiKey);
+    }
+}