diff --git a/.release-please-manifest.json b/.release-please-manifest.json index ff4f9a5..36b2aff 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.1.0-alpha.33" + ".": "0.1.0-alpha.34" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 08d15d7..66f2cc8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 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) + +### Chores + +* **docs:** update readme ([#99](https://github.com/OneBusAway/kotlin-sdk/issues/99)) ([2fff1ff](https://github.com/OneBusAway/kotlin-sdk/commit/2fff1ff263f423c9d3a15938e164718dac1acfb2)) + ## 0.1.0-alpha.33 (2024-12-13) Full Changelog: [v0.1.0-alpha.32...v0.1.0-alpha.33](https://github.com/OneBusAway/kotlin-sdk/compare/v0.1.0-alpha.32...v0.1.0-alpha.33) diff --git a/README.md b/README.md index 3fdb5f1..cf7c482 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The REST API documentation can be found on [developer.onebusaway.org](https://d ```kotlin -implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.33") +implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.34") ``` #### Maven @@ -30,7 +30,7 @@ implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.33") org.onebusaway onebusaway-sdk-kotlin - 0.1.0-alpha.33 + 0.1.0-alpha.34 ``` @@ -52,6 +52,9 @@ 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 @@ -71,8 +74,7 @@ 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 @@ -90,14 +92,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.models.core.JsonValue +import org.onebusaway.core.JsonValue +import org.onebusaway.models.CurrentTimeRetrieveParams + val params = CurrentTimeRetrieveParams.builder() // ... normal properties .putAdditionalProperty("secret_param", JsonValue.from("4242")) @@ -111,15 +113,19 @@ 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()) { @@ -141,6 +147,8 @@ 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") ``` @@ -154,31 +162,33 @@ 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) @@ -190,6 +200,10 @@ 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)) @@ -201,12 +215,14 @@ 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(new Proxy( - Type.HTTP, - new InetSocketAddress("proxy.com", 8080) - )) + .proxy(Proxy(Proxy.Type.HTTP, InetSocketAddress("example.com", 8080))) .build() ``` diff --git a/build.gradle.kts b/build.gradle.kts index 584fb8a..202ebf6 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -4,7 +4,7 @@ plugins { allprojects { group = "org.onebusaway" - version = "0.1.0-alpha.33" // x-release-please-version + version = "0.1.0-alpha.34" // x-release-please-version } nexusPublishing { diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureListParamsTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureListParamsTest.kt index 98e5092..15676cb 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureListParamsTest.kt +++ b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureListParamsTest.kt @@ -12,7 +12,7 @@ class ArrivalAndDepartureListParamsTest { @Test fun createArrivalAndDepartureListParams() { ArrivalAndDepartureListParams.builder() - .stopId("stopID") + .stopId("1_75403") .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("stopID") + .stopId("1_75403") .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("stopID").build() + val params = ArrivalAndDepartureListParams.builder().stopId("1_75403").build() val expected = QueryParams.builder() assertThat(params.getQueryParams()).isEqualTo(expected.build()) } @Test fun getPathParam() { - val params = ArrivalAndDepartureListParams.builder().stopId("stopID").build() + val params = ArrivalAndDepartureListParams.builder().stopId("1_75403").build() assertThat(params).isNotNull // path param "stopId" - assertThat(params.getPathParam(0)).isEqualTo("stopID") + assertThat(params.getPathParam(0)).isEqualTo("1_75403") // out-of-bound path param assertThat(params.getPathParam(1)).isEqualTo("") } diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureRetrieveParamsTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureRetrieveParamsTest.kt index f7ad2ab..af85193 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureRetrieveParamsTest.kt +++ b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ArrivalAndDepartureRetrieveParamsTest.kt @@ -11,7 +11,7 @@ class ArrivalAndDepartureRetrieveParamsTest { @Test fun createArrivalAndDepartureRetrieveParams() { ArrivalAndDepartureRetrieveParams.builder() - .stopId("stopID") + .stopId("1_75403") .serviceDate(0L) .tripId("tripId") .stopSequence(0L) @@ -24,7 +24,7 @@ class ArrivalAndDepartureRetrieveParamsTest { fun getQueryParams() { val params = ArrivalAndDepartureRetrieveParams.builder() - .stopId("stopID") + .stopId("1_75403") .serviceDate(0L) .tripId("tripId") .stopSequence(0L) @@ -44,7 +44,7 @@ class ArrivalAndDepartureRetrieveParamsTest { fun getQueryParamsWithoutOptionalFields() { val params = ArrivalAndDepartureRetrieveParams.builder() - .stopId("stopID") + .stopId("1_75403") .serviceDate(0L) .tripId("tripId") .build() @@ -58,13 +58,13 @@ class ArrivalAndDepartureRetrieveParamsTest { fun getPathParam() { val params = ArrivalAndDepartureRetrieveParams.builder() - .stopId("stopID") + .stopId("1_75403") .serviceDate(0L) .tripId("tripId") .build() assertThat(params).isNotNull // path param "stopId" - assertThat(params.getPathParam(0)).isEqualTo("stopID") + assertThat(params.getPathParam(0)).isEqualTo("1_75403") // out-of-bound path param assertThat(params.getPathParam(1)).isEqualTo("") } diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/RoutesForAgencyListParamsTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/RoutesForAgencyListParamsTest.kt index 5dae5c7..25e5db1 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/RoutesForAgencyListParamsTest.kt +++ b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/RoutesForAgencyListParamsTest.kt @@ -9,15 +9,15 @@ class RoutesForAgencyListParamsTest { @Test fun createRoutesForAgencyListParams() { - RoutesForAgencyListParams.builder().agencyId("agencyID").build() + RoutesForAgencyListParams.builder().agencyId("40").build() } @Test fun getPathParam() { - val params = RoutesForAgencyListParams.builder().agencyId("agencyID").build() + val params = RoutesForAgencyListParams.builder().agencyId("40").build() assertThat(params).isNotNull // path param "agencyId" - assertThat(params.getPathParam(0)).isEqualTo("agencyID") + assertThat(params.getPathParam(0)).isEqualTo("40") // out-of-bound path param assertThat(params.getPathParam(1)).isEqualTo("") } diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ScheduleForRouteRetrieveParamsTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ScheduleForRouteRetrieveParamsTest.kt index dbf0138..ad74668 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ScheduleForRouteRetrieveParamsTest.kt +++ b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/models/ScheduleForRouteRetrieveParamsTest.kt @@ -12,7 +12,7 @@ class ScheduleForRouteRetrieveParamsTest { @Test fun createScheduleForRouteRetrieveParams() { ScheduleForRouteRetrieveParams.builder() - .routeId("routeID") + .routeId("1_100223") .date(LocalDate.parse("2019-12-27")) .build() } @@ -21,7 +21,7 @@ class ScheduleForRouteRetrieveParamsTest { fun getQueryParams() { val params = ScheduleForRouteRetrieveParams.builder() - .routeId("routeID") + .routeId("1_100223") .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("routeID").build() + val params = ScheduleForRouteRetrieveParams.builder().routeId("1_100223").build() val expected = QueryParams.builder() assertThat(params.getQueryParams()).isEqualTo(expected.build()) } @Test fun getPathParam() { - val params = ScheduleForRouteRetrieveParams.builder().routeId("routeID").build() + val params = ScheduleForRouteRetrieveParams.builder().routeId("1_100223").build() assertThat(params).isNotNull // path param "routeId" - assertThat(params.getPathParam(0)).isEqualTo("routeID") + assertThat(params.getPathParam(0)).isEqualTo("1_100223") // out-of-bound path param assertThat(params.getPathParam(1)).isEqualTo("") } diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ArrivalAndDepartureServiceTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ArrivalAndDepartureServiceTest.kt index 2190ef0..9e3e729 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ArrivalAndDepartureServiceTest.kt +++ b/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("stopID") + .stopId("1_75403") .serviceDate(0L) .tripId("tripId") .stopSequence(0L) @@ -46,7 +46,7 @@ class ArrivalAndDepartureServiceTest { val arrivalAndDepartureListResponse = arrivalAndDepartureService.list( ArrivalAndDepartureListParams.builder() - .stopId("stopID") + .stopId("1_75403") .minutesAfter(0L) .minutesBefore(0L) .time(OffsetDateTime.parse("2019-12-27T18:11:19.117Z")) diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/RoutesForAgencyServiceTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/RoutesForAgencyServiceTest.kt index 2dd0d5b..873ce86 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/RoutesForAgencyServiceTest.kt +++ b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/RoutesForAgencyServiceTest.kt @@ -20,9 +20,7 @@ class RoutesForAgencyServiceTest { .build() val routesForAgencyService = client.routesForAgency() val routesForAgencyListResponse = - routesForAgencyService.list( - RoutesForAgencyListParams.builder().agencyId("agencyID").build() - ) + routesForAgencyService.list(RoutesForAgencyListParams.builder().agencyId("40").build()) println(routesForAgencyListResponse) } } diff --git a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ScheduleForRouteServiceTest.kt b/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ScheduleForRouteServiceTest.kt index 40039f2..c44474c 100644 --- a/onebusaway-sdk-kotlin-core/src/test/kotlin/org/onebusaway/services/blocking/ScheduleForRouteServiceTest.kt +++ b/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("routeID") + .routeId("1_100223") .date(LocalDate.parse("2019-12-27")) .build() )