feat(client): add a withOptions method

Author: stainless-app[bot]

README.md

@@ -106,6 +106,21 @@ See this table for the available options:
 > Don't create more than one client in the same application. Each client has a connection pool and
 > thread pools, which are more efficient to share between requests.
 
+### Modifying configuration
+
+To temporarily use a modified client configuration, while reusing the same connection and thread pools, call `withOptions()` on any client or service:
+
+```kotlin
+import org.onebusaway.client.OnebusawaySdkClient
+
+val clientWithOptions: OnebusawaySdkClient = client.withOptions {
+    it.baseUrl("https://example.com")
+    it.maxRetries(42)
+}
+```
+
+The `withOptions()` method does not affect the original client or service.
+
 ## Requests and responses
 
 To send a request to the Onebusaway SDK API, build an instance of some `Params` class and pass it to the corresponding client method. When the response is received, it will be deserialized into an instance of a Kotlin class.

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClient.kt

@@ -2,6 +2,7 @@
 
 package org.onebusaway.client
 
+import org.onebusaway.core.ClientOptions
 import org.onebusaway.services.blocking.AgenciesWithCoverageService
 import org.onebusaway.services.blocking.AgencyService
 import org.onebusaway.services.blocking.ArrivalAndDepartureService
@@ -60,6 +61,13 @@ interface OnebusawaySdkClient {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: (ClientOptions.Builder) -> Unit): OnebusawaySdkClient
+
     fun agenciesWithCoverage(): AgenciesWithCoverageService
 
     fun agency(): AgencyService
@@ -134,6 +142,15 @@ interface OnebusawaySdkClient {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): OnebusawaySdkClient.WithRawResponse
+
         fun agenciesWithCoverage(): AgenciesWithCoverageService.WithRawResponse
 
         fun agency(): AgencyService.WithRawResponse

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsync.kt

@@ -2,6 +2,7 @@
 
 package org.onebusaway.client
 
+import org.onebusaway.core.ClientOptions
 import org.onebusaway.services.async.AgenciesWithCoverageServiceAsync
 import org.onebusaway.services.async.AgencyServiceAsync
 import org.onebusaway.services.async.ArrivalAndDepartureServiceAsync
@@ -60,6 +61,13 @@ interface OnebusawaySdkClientAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: (ClientOptions.Builder) -> Unit): OnebusawaySdkClientAsync
+
     fun agenciesWithCoverage(): AgenciesWithCoverageServiceAsync
 
     fun agency(): AgencyServiceAsync
@@ -135,6 +143,15 @@ interface OnebusawaySdkClientAsync {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): OnebusawaySdkClientAsync.WithRawResponse
+
         fun agenciesWithCoverage(): AgenciesWithCoverageServiceAsync.WithRawResponse
 
         fun agency(): AgencyServiceAsync.WithRawResponse

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsyncImpl.kt

@@ -191,6 +191,9 @@ class OnebusawaySdkClientAsyncImpl(private val clientOptions: ClientOptions) :
 
     override fun withRawResponse(): OnebusawaySdkClientAsync.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: (ClientOptions.Builder) -> Unit): OnebusawaySdkClientAsync =
+        OnebusawaySdkClientAsyncImpl(clientOptions.toBuilder().apply(modifier).build())
+
     override fun agenciesWithCoverage(): AgenciesWithCoverageServiceAsync = agenciesWithCoverage
 
     override fun agency(): AgencyServiceAsync = agency
@@ -366,6 +369,13 @@ class OnebusawaySdkClientAsyncImpl(private val clientOptions: ClientOptions) :
             ShapeServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        override fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): OnebusawaySdkClientAsync.WithRawResponse =
+            OnebusawaySdkClientAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier).build()
+            )
+
         override fun agenciesWithCoverage(): AgenciesWithCoverageServiceAsync.WithRawResponse =
             agenciesWithCoverage
 

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientImpl.kt

@@ -182,6 +182,9 @@ class OnebusawaySdkClientImpl(private val clientOptions: ClientOptions) : Onebus
 
     override fun withRawResponse(): OnebusawaySdkClient.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: (ClientOptions.Builder) -> Unit): OnebusawaySdkClient =
+        OnebusawaySdkClientImpl(clientOptions.toBuilder().apply(modifier).build())
+
     override fun agenciesWithCoverage(): AgenciesWithCoverageService = agenciesWithCoverage
 
     override fun agency(): AgencyService = agency
@@ -355,6 +358,13 @@ class OnebusawaySdkClientImpl(private val clientOptions: ClientOptions) : Onebus
             ShapeServiceImpl.WithRawResponseImpl(clientOptions)
         }
 
+        override fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): OnebusawaySdkClient.WithRawResponse =
+            OnebusawaySdkClientImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier).build()
+            )
+
         override fun agenciesWithCoverage(): AgenciesWithCoverageService.WithRawResponse =
             agenciesWithCoverage
 

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/AgenciesWithCoverageServiceAsync.kt

@@ -3,6 +3,7 @@
 package org.onebusaway.services.async
 
 import com.google.errorprone.annotations.MustBeClosed
+import org.onebusaway.core.ClientOptions
 import org.onebusaway.core.RequestOptions
 import org.onebusaway.core.http.HttpResponseFor
 import org.onebusaway.models.agencieswithcoverage.AgenciesWithCoverageListParams
@@ -15,6 +16,13 @@ interface AgenciesWithCoverageServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: (ClientOptions.Builder) -> Unit): AgenciesWithCoverageServiceAsync
+
     /**
      * Returns a list of all transit agencies currently supported by OneBusAway along with the
      * center of their coverage area.
@@ -34,6 +42,15 @@ interface AgenciesWithCoverageServiceAsync {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): AgenciesWithCoverageServiceAsync.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get /api/where/agencies-with-coverage.json`, but is
          * otherwise the same as [AgenciesWithCoverageServiceAsync.list].

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/AgenciesWithCoverageServiceAsyncImpl.kt

@@ -27,6 +27,11 @@ internal constructor(private val clientOptions: ClientOptions) : AgenciesWithCov
     override fun withRawResponse(): AgenciesWithCoverageServiceAsync.WithRawResponse =
         withRawResponse
 
+    override fun withOptions(
+        modifier: (ClientOptions.Builder) -> Unit
+    ): AgenciesWithCoverageServiceAsync =
+        AgenciesWithCoverageServiceAsyncImpl(clientOptions.toBuilder().apply(modifier).build())
+
     override suspend fun list(
         params: AgenciesWithCoverageListParams,
         requestOptions: RequestOptions,
@@ -39,6 +44,13 @@ internal constructor(private val clientOptions: ClientOptions) : AgenciesWithCov
 
         private val errorHandler: Handler<JsonValue> = errorHandler(clientOptions.jsonMapper)
 
+        override fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): AgenciesWithCoverageServiceAsync.WithRawResponse =
+            AgenciesWithCoverageServiceAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier).build()
+            )
+
         private val listHandler: Handler<AgenciesWithCoverageListResponse> =
             jsonHandler<AgenciesWithCoverageListResponse>(clientOptions.jsonMapper)
                 .withErrorHandler(errorHandler)

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/AgencyServiceAsync.kt

@@ -3,6 +3,7 @@
 package org.onebusaway.services.async
 
 import com.google.errorprone.annotations.MustBeClosed
+import org.onebusaway.core.ClientOptions
 import org.onebusaway.core.RequestOptions
 import org.onebusaway.core.http.HttpResponseFor
 import org.onebusaway.models.agency.AgencyRetrieveParams
@@ -15,6 +16,13 @@ interface AgencyServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: (ClientOptions.Builder) -> Unit): AgencyServiceAsync
+
     /** Retrieve information for a specific transit agency identified by its unique ID. */
     suspend fun retrieve(
         agencyId: String,
@@ -38,6 +46,15 @@ interface AgencyServiceAsync {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): AgencyServiceAsync.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get /api/where/agency/{agencyID}.json`, but is otherwise
          * the same as [AgencyServiceAsync.retrieve].

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/AgencyServiceAsyncImpl.kt

@@ -27,6 +27,9 @@ class AgencyServiceAsyncImpl internal constructor(private val clientOptions: Cli
 
     override fun withRawResponse(): AgencyServiceAsync.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: (ClientOptions.Builder) -> Unit): AgencyServiceAsync =
+        AgencyServiceAsyncImpl(clientOptions.toBuilder().apply(modifier).build())
+
     override suspend fun retrieve(
         params: AgencyRetrieveParams,
         requestOptions: RequestOptions,
@@ -39,6 +42,13 @@ class AgencyServiceAsyncImpl internal constructor(private val clientOptions: Cli
 
         private val errorHandler: Handler<JsonValue> = errorHandler(clientOptions.jsonMapper)
 
+        override fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): AgencyServiceAsync.WithRawResponse =
+            AgencyServiceAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier).build()
+            )
+
         private val retrieveHandler: Handler<AgencyRetrieveResponse> =
             jsonHandler<AgencyRetrieveResponse>(clientOptions.jsonMapper)
                 .withErrorHandler(errorHandler)

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/ArrivalAndDepartureServiceAsync.kt

@@ -3,6 +3,7 @@
 package org.onebusaway.services.async
 
 import com.google.errorprone.annotations.MustBeClosed
+import org.onebusaway.core.ClientOptions
 import org.onebusaway.core.RequestOptions
 import org.onebusaway.core.http.HttpResponseFor
 import org.onebusaway.models.arrivalanddeparture.ArrivalAndDepartureListParams
@@ -17,6 +18,13 @@ interface ArrivalAndDepartureServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: (ClientOptions.Builder) -> Unit): ArrivalAndDepartureServiceAsync
+
     /** arrival-and-departure-for-stop */
     suspend fun retrieve(
         stopId: String,
@@ -58,6 +66,15 @@ interface ArrivalAndDepartureServiceAsync {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: (ClientOptions.Builder) -> Unit
+        ): ArrivalAndDepartureServiceAsync.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get
          * /api/where/arrival-and-departure-for-stop/{stopID}.json`, but is otherwise the same as