release: 0.1.0-alpha.35

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.34"
+  ".": "0.1.0-alpha.35"
 }

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0-alpha.35 (2024-12-19)
+
+Full Changelog: [v0.1.0-alpha.34...v0.1.0-alpha.35](https://github.com/OneBusAway/kotlin-sdk/compare/v0.1.0-alpha.34...v0.1.0-alpha.35)
+
+### Chores
+
+* **docs:** add example project ([#101](https://github.com/OneBusAway/kotlin-sdk/issues/101)) ([e131f17](https://github.com/OneBusAway/kotlin-sdk/commit/e131f17c22d3642876fa2207991af3eeb5d62c10))
+* **internal:** codegen related update ([#103](https://github.com/OneBusAway/kotlin-sdk/issues/103)) ([8951ac1](https://github.com/OneBusAway/kotlin-sdk/commit/8951ac1ca75e9d824bd2630ea715734c0e694b3f))
+
 ## 0.1.0-alpha.34 (2024-12-19)
 
 Full Changelog: [v0.1.0-alpha.33...v0.1.0-alpha.34](https://github.com/OneBusAway/kotlin-sdk/compare/v0.1.0-alpha.33...v0.1.0-alpha.34)

README.md

@@ -21,7 +21,7 @@ The REST API documentation can be found on [developer.onebusaway.org](https://d
 <!-- x-release-please-start-version -->
 
 ```kotlin
-implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.34")
+implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.35")
 ```
 
 #### Maven
@@ -30,7 +30,7 @@ implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.34")
 <dependency>
     <groupId>org.onebusaway</groupId>
     <artifactId>onebusaway-sdk-kotlin</artifactId>
-    <version>0.1.0-alpha.34</version>
+    <version>0.1.0-alpha.35</version>
 </dependency>
 ```
 
@@ -52,9 +52,6 @@ val client = OnebusawaySdkOkHttpClient.builder()
 Alternately, set the environment with `ONEBUSAWAY_API_KEY`, and use `OnebusawaySdkOkHttpClient.fromEnv()` to read from the environment.
 
 ```kotlin
-import org.onebusaway.client.OnebusawaySdkClient
-import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-
 val client = OnebusawaySdkOkHttpClient.fromEnv()
 
 // Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
@@ -74,7 +71,8 @@ Read the documentation for more configuration options.
 
 ### Example: creating a resource
 
-To create a new current time, first use the `CurrentTimeRetrieveParams` builder to specify attributes, then pass that to the `retrieve` method of the `currentTime` service.
+To create a new current time, first use the `CurrentTimeRetrieveParams` builder to specify attributes,
+then pass that to the `retrieve` method of the `currentTime` service.
 
 ```kotlin
 import org.onebusaway.models.CurrentTimeRetrieveParams
@@ -92,14 +90,14 @@ val currentTime = client.currentTime().retrieve(params)
 
 To make a request to the Onebusaway SDK API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `CurrentTimeRetrieveParams.builder()` to pass to the `retrieve` method of the `currentTime` service.
+In [Example: creating a resource](#example-creating-a-resource) above, we used the `CurrentTimeRetrieveParams.builder()` to pass to
+the `retrieve` method of the `currentTime` service.
 
-Sometimes, the API may support other properties that are not yet supported in the Kotlin SDK types. In that case, you can attach them using the `putAdditionalProperty` method.
+Sometimes, the API may support other properties that are not yet supported in the Kotlin SDK types. In that case,
+you can attach them using the `putAdditionalProperty` method.
 
 ```kotlin
-import org.onebusaway.core.JsonValue
-import org.onebusaway.models.CurrentTimeRetrieveParams
-
+import org.onebusaway.models.core.JsonValue
 val params = CurrentTimeRetrieveParams.builder()
     // ... normal properties
     .putAdditionalProperty("secret_param", JsonValue.from("4242"))
@@ -113,19 +111,15 @@ val params = CurrentTimeRetrieveParams.builder()
 When receiving a response, the Onebusaway SDK Kotlin SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Kotlin type. If you directly access the mistaken property, the SDK will throw an unchecked `OnebusawaySdkInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model.
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveResponse
-
 val currentTime = client.currentTime().retrieve().validate()
 ```
 
 ### Response properties as JSON
 
-In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
+In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by
+this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
 
 ```kotlin
-import java.util.Optional
-import org.onebusaway.core.JsonField
-
 val field = responseObj._field
 
 if (field.isMissing()) {
@@ -147,8 +141,6 @@ if (field.isMissing()) {
 Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method:
 
 ```kotlin
-import org.onebusaway.core.JsonValue
-
 val secret = references._additionalProperties().get("secret_field")
 ```
 
@@ -162,33 +154,31 @@ This library throws exceptions in a single hierarchy for easy handling:
 
 - **`OnebusawaySdkException`** - Base exception for all exceptions
 
-- **`OnebusawaySdkServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
+  - **`OnebusawaySdkServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
 
-  | 400    | BadRequestException           |
-  | ------ | ----------------------------- |
-  | 401    | AuthenticationException       |
-  | 403    | PermissionDeniedException     |
-  | 404    | NotFoundException             |
-  | 422    | UnprocessableEntityException  |
-  | 429    | RateLimitException            |
-  | 5xx    | InternalServerException       |
-  | others | UnexpectedStatusCodeException |
+    | 400    | BadRequestException           |
+    | ------ | ----------------------------- |
+    | 401    | AuthenticationException       |
+    | 403    | PermissionDeniedException     |
+    | 404    | NotFoundException             |
+    | 422    | UnprocessableEntityException  |
+    | 429    | RateLimitException            |
+    | 5xx    | InternalServerException       |
+    | others | UnexpectedStatusCodeException |
 
-- **`OnebusawaySdkIoException`** - I/O networking errors
-- **`OnebusawaySdkInvalidDataException`** - any other exceptions on the client side, e.g.:
-  - We failed to serialize the request body
-  - We failed to parse the response body (has access to response code and body)
+  - **`OnebusawaySdkIoException`** - I/O networking errors
+  - **`OnebusawaySdkInvalidDataException`** - any other exceptions on the client side, e.g.:
+    - We failed to serialize the request body
+    - We failed to parse the response body (has access to response code and body)
 
 ## Network options
 
 ### Retries
 
-Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a `maxRetries` on the client builder to configure this:
+Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default.
+You can provide a `maxRetries` on the client builder to configure this:
 
 ```kotlin
-import org.onebusaway.client.OnebusawaySdkClient
-import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-
 val client = OnebusawaySdkOkHttpClient.builder()
     .fromEnv()
     .maxRetries(4)
@@ -200,10 +190,6 @@ val client = OnebusawaySdkOkHttpClient.builder()
 Requests time out after 1 minute by default. You can configure this on the client builder:
 
 ```kotlin
-import java.time.Duration
-import org.onebusaway.client.OnebusawaySdkClient
-import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-
 val client = OnebusawaySdkOkHttpClient.builder()
     .fromEnv()
     .timeout(Duration.ofSeconds(30))
@@ -215,14 +201,12 @@ val client = OnebusawaySdkOkHttpClient.builder()
 Requests can be routed through a proxy. You can configure this on the client builder:
 
 ```kotlin
-import java.net.InetSocketAddress
-import java.net.Proxy
-import org.onebusaway.client.OnebusawaySdkClient
-import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-
 val client = OnebusawaySdkOkHttpClient.builder()
     .fromEnv()
-    .proxy(Proxy(Proxy.Type.HTTP, InetSocketAddress("example.com", 8080)))
+    .proxy(new Proxy(
+        Type.HTTP,
+        new InetSocketAddress("proxy.com", 8080)
+    ))
     .build()
 ```
 

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 allprojects {
     group = "org.onebusaway"
-    version = "0.1.0-alpha.34" // x-release-please-version
+    version = "0.1.0-alpha.35" // x-release-please-version
 }
 
 nexusPublishing {

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureListParamsTest.kt

@@ -12,7 +12,7 @@ class ArrivalAndDepartureListParamsTest {
     @Test
     fun createArrivalAndDepartureListParams() {
         ArrivalAndDepartureListParams.builder()
-            .stopId("1_75403")
+            .stopId("stopID")
             .minutesAfter(0L)
             .minutesBefore(0L)
             .time(OffsetDateTime.parse("2019-12-27T18:11:19.117Z"))
@@ -23,7 +23,7 @@ class ArrivalAndDepartureListParamsTest {
     fun getQueryParams() {
         val params =
             ArrivalAndDepartureListParams.builder()
-                .stopId("1_75403")
+                .stopId("stopID")
                 .minutesAfter(0L)
                 .minutesBefore(0L)
                 .time(OffsetDateTime.parse("2019-12-27T18:11:19.117Z"))
@@ -37,17 +37,17 @@ class ArrivalAndDepartureListParamsTest {
 
     @Test
     fun getQueryParamsWithoutOptionalFields() {
-        val params = ArrivalAndDepartureListParams.builder().stopId("1_75403").build()
+        val params = ArrivalAndDepartureListParams.builder().stopId("stopID").build()
         val expected = QueryParams.builder()
         assertThat(params.getQueryParams()).isEqualTo(expected.build())
     }
 
     @Test
     fun getPathParam() {
-        val params = ArrivalAndDepartureListParams.builder().stopId("1_75403").build()
+        val params = ArrivalAndDepartureListParams.builder().stopId("stopID").build()
         assertThat(params).isNotNull
         // path param "stopId"
-        assertThat(params.getPathParam(0)).isEqualTo("1_75403")
+        assertThat(params.getPathParam(0)).isEqualTo("stopID")
         // out-of-bound path param
         assertThat(params.getPathParam(1)).isEqualTo("")
     }

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureRetrieveParamsTest.kt

@@ -11,7 +11,7 @@ class ArrivalAndDepartureRetrieveParamsTest {
     @Test
     fun createArrivalAndDepartureRetrieveParams() {
         ArrivalAndDepartureRetrieveParams.builder()
-            .stopId("1_75403")
+            .stopId("stopID")
             .serviceDate(0L)
             .tripId("tripId")
             .stopSequence(0L)
@@ -24,7 +24,7 @@ class ArrivalAndDepartureRetrieveParamsTest {
     fun getQueryParams() {
         val params =
             ArrivalAndDepartureRetrieveParams.builder()
-                .stopId("1_75403")
+                .stopId("stopID")
                 .serviceDate(0L)
                 .tripId("tripId")
                 .stopSequence(0L)
@@ -44,7 +44,7 @@ class ArrivalAndDepartureRetrieveParamsTest {
     fun getQueryParamsWithoutOptionalFields() {
         val params =
             ArrivalAndDepartureRetrieveParams.builder()
-                .stopId("1_75403")
+                .stopId("stopID")
                 .serviceDate(0L)
                 .tripId("tripId")
                 .build()
@@ -58,13 +58,13 @@ class ArrivalAndDepartureRetrieveParamsTest {
     fun getPathParam() {
         val params =
             ArrivalAndDepartureRetrieveParams.builder()
-                .stopId("1_75403")
+                .stopId("stopID")
                 .serviceDate(0L)
                 .tripId("tripId")
                 .build()
         assertThat(params).isNotNull
         // path param "stopId"
-        assertThat(params.getPathParam(0)).isEqualTo("1_75403")
+        assertThat(params.getPathParam(0)).isEqualTo("stopID")
         // out-of-bound path param
         assertThat(params.getPathParam(1)).isEqualTo("")
     }

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/RoutesForAgencyListParamsTest.kt

@@ -9,15 +9,15 @@ class RoutesForAgencyListParamsTest {
 
     @Test
     fun createRoutesForAgencyListParams() {
-        RoutesForAgencyListParams.builder().agencyId("40").build()
+        RoutesForAgencyListParams.builder().agencyId("agencyID").build()
     }
 
     @Test
     fun getPathParam() {
-        val params = RoutesForAgencyListParams.builder().agencyId("40").build()
+        val params = RoutesForAgencyListParams.builder().agencyId("agencyID").build()
         assertThat(params).isNotNull
         // path param "agencyId"
-        assertThat(params.getPathParam(0)).isEqualTo("40")
+        assertThat(params.getPathParam(0)).isEqualTo("agencyID")
         // out-of-bound path param
         assertThat(params.getPathParam(1)).isEqualTo("")
     }

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ScheduleForRouteRetrieveParamsTest.kt

@@ -12,7 +12,7 @@ class ScheduleForRouteRetrieveParamsTest {
     @Test
     fun createScheduleForRouteRetrieveParams() {
         ScheduleForRouteRetrieveParams.builder()
-            .routeId("1_100223")
+            .routeId("routeID")
             .date(LocalDate.parse("2019-12-27"))
             .build()
     }
@@ -21,7 +21,7 @@ class ScheduleForRouteRetrieveParamsTest {
     fun getQueryParams() {
         val params =
             ScheduleForRouteRetrieveParams.builder()
-                .routeId("1_100223")
+                .routeId("routeID")
                 .date(LocalDate.parse("2019-12-27"))
                 .build()
         val expected = QueryParams.builder()
@@ -31,17 +31,17 @@ class ScheduleForRouteRetrieveParamsTest {
 
     @Test
     fun getQueryParamsWithoutOptionalFields() {
-        val params = ScheduleForRouteRetrieveParams.builder().routeId("1_100223").build()
+        val params = ScheduleForRouteRetrieveParams.builder().routeId("routeID").build()
         val expected = QueryParams.builder()
         assertThat(params.getQueryParams()).isEqualTo(expected.build())
     }
 
     @Test
     fun getPathParam() {
-        val params = ScheduleForRouteRetrieveParams.builder().routeId("1_100223").build()
+        val params = ScheduleForRouteRetrieveParams.builder().routeId("routeID").build()
         assertThat(params).isNotNull
         // path param "routeId"
-        assertThat(params.getPathParam(0)).isEqualTo("1_100223")
+        assertThat(params.getPathParam(0)).isEqualTo("routeID")
         // out-of-bound path param
         assertThat(params.getPathParam(1)).isEqualTo("")
     }

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ArrivalAndDepartureServiceTest.kt

@@ -24,7 +24,7 @@ class ArrivalAndDepartureServiceTest {
         val arrivalAndDepartureRetrieveResponse =
             arrivalAndDepartureService.retrieve(
                 ArrivalAndDepartureRetrieveParams.builder()
-                    .stopId("1_75403")
+                    .stopId("stopID")
                     .serviceDate(0L)
                     .tripId("tripId")
                     .stopSequence(0L)
@@ -46,7 +46,7 @@ class ArrivalAndDepartureServiceTest {
         val arrivalAndDepartureListResponse =
             arrivalAndDepartureService.list(
                 ArrivalAndDepartureListParams.builder()
-                    .stopId("1_75403")
+                    .stopId("stopID")
                     .minutesAfter(0L)
                     .minutesBefore(0L)
                     .time(OffsetDateTime.parse("2019-12-27T18:11:19.117Z"))

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/RoutesForAgencyServiceTest.kt

@@ -20,7 +20,9 @@ class RoutesForAgencyServiceTest {
                 .build()
         val routesForAgencyService = client.routesForAgency()
         val routesForAgencyListResponse =
-            routesForAgencyService.list(RoutesForAgencyListParams.builder().agencyId("40").build())
+            routesForAgencyService.list(
+                RoutesForAgencyListParams.builder().agencyId("agencyID").build()
+            )
         println(routesForAgencyListResponse)
     }
 }

onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ScheduleForRouteServiceTest.kt

@@ -23,7 +23,7 @@ class ScheduleForRouteServiceTest {
         val scheduleForRouteRetrieveResponse =
             scheduleForRouteService.retrieve(
                 ScheduleForRouteRetrieveParams.builder()
-                    .routeId("1_100223")
+                    .routeId("routeID")
                     .date(LocalDate.parse("2019-12-27"))
                     .build()
             )

onebusaway-sdk-kotlin-example/build.gradle.kts

@@ -1,7 +1,14 @@
 plugins {
-    kotlin("jvm")
+    id("onebusaway-sdk.kotlin")
+    application
 }
 
+
+application {
+    mainClass = "org.onebusaway.example.MainKt"
+}
+
+
 group = "org.onebusaway.example"
 version = "0.0.1-alpha.0"
 
@@ -17,4 +24,4 @@ dependencies {
 
 tasks.test {
     useJUnitPlatform()
-}
+}