feat(client): add a withOptions method

Author: stainless-app[bot]

README.md

@@ -104,6 +104,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:
+
+```java
+import com.withorb.api.client.OrbClient;
+
+OrbClient clientWithOptions = client.withOptions(optionsBuilder -> {
+    optionsBuilder.baseUrl("https://example.com");
+    optionsBuilder.maxRetries(42);
+});
+```
+
+The `withOptions()` method does not affect the original client or service.
+
 ## Requests and responses
 
 To send a request to the Orb 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 Java class.

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClient.kt

@@ -2,6 +2,7 @@
 
 package com.withorb.api.client
 
+import com.withorb.api.core.ClientOptions
 import com.withorb.api.services.blocking.AlertService
 import com.withorb.api.services.blocking.BetaService
 import com.withorb.api.services.blocking.CouponService
@@ -20,6 +21,8 @@ import com.withorb.api.services.blocking.SubscriptionService
 import com.withorb.api.services.blocking.TopLevelService
 import com.withorb.api.services.blocking.WebhookService
 
+import java.util.function.Consumer
+
 /**
  * A client for interacting with the Orb REST API synchronously. You can also switch to asynchronous
  * execution via the [async] method.
@@ -49,6 +52,13 @@ interface OrbClient {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClient
+
     fun topLevel(): TopLevelService
 
     fun beta(): BetaService
@@ -99,6 +109,13 @@ interface OrbClient {
     /** A view of [OrbClient] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClient.WithRawResponse
+
         fun topLevel(): TopLevelService.WithRawResponse
 
         fun beta(): BetaService.WithRawResponse

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientAsync.kt

@@ -2,6 +2,7 @@
 
 package com.withorb.api.client
 
+import com.withorb.api.core.ClientOptions
 import com.withorb.api.services.async.AlertServiceAsync
 import com.withorb.api.services.async.BetaServiceAsync
 import com.withorb.api.services.async.CouponServiceAsync
@@ -18,6 +19,7 @@ import com.withorb.api.services.async.PriceServiceAsync
 import com.withorb.api.services.async.SubscriptionChangeServiceAsync
 import com.withorb.api.services.async.SubscriptionServiceAsync
 import com.withorb.api.services.async.TopLevelServiceAsync
+import java.util.function.Consumer
 
 /**
  * A client for interacting with the Orb REST API asynchronously. You can also switch to synchronous
@@ -48,6 +50,13 @@ interface OrbClientAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClientAsync
+
     fun topLevel(): TopLevelServiceAsync
 
     fun beta(): BetaServiceAsync
@@ -96,6 +105,13 @@ interface OrbClientAsync {
     /** A view of [OrbClientAsync] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClientAsync.WithRawResponse
+
         fun topLevel(): TopLevelServiceAsync.WithRawResponse
 
         fun beta(): BetaServiceAsync.WithRawResponse

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientAsyncImpl.kt

@@ -36,6 +36,7 @@ import com.withorb.api.services.async.SubscriptionServiceAsync
 import com.withorb.api.services.async.SubscriptionServiceAsyncImpl
 import com.withorb.api.services.async.TopLevelServiceAsync
 import com.withorb.api.services.async.TopLevelServiceAsyncImpl
+import java.util.function.Consumer
 
 class OrbClientAsyncImpl(private val clientOptions: ClientOptions) : OrbClientAsync {
 
@@ -116,6 +117,9 @@ class OrbClientAsyncImpl(private val clientOptions: ClientOptions) : OrbClientAs
 
     override fun withRawResponse(): OrbClientAsync.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClientAsync =
+        OrbClientAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
     override fun topLevel(): TopLevelServiceAsync = topLevel
 
     override fun beta(): BetaServiceAsync = beta
@@ -219,6 +223,13 @@ class OrbClientAsyncImpl(private val clientOptions: ClientOptions) : OrbClientAs
             SubscriptionChangeServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        override fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): OrbClientAsync.WithRawResponse =
+            OrbClientAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier::accept).build()
+            )
+
         override fun topLevel(): TopLevelServiceAsync.WithRawResponse = topLevel
 
         override fun beta(): BetaServiceAsync.WithRawResponse = beta

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientImpl.kt

@@ -38,6 +38,7 @@ import com.withorb.api.services.blocking.TopLevelService
 import com.withorb.api.services.blocking.TopLevelServiceImpl
 import com.withorb.api.services.blocking.WebhookService
 import com.withorb.api.services.blocking.WebhookServiceImpl
+import java.util.function.Consumer
 
 class OrbClientImpl(private val clientOptions: ClientOptions) : OrbClient {
 
@@ -108,6 +109,9 @@ class OrbClientImpl(private val clientOptions: ClientOptions) : OrbClient {
 
     override fun withRawResponse(): OrbClient.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrbClient =
+        OrbClientImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
     override fun topLevel(): TopLevelService = topLevel
 
     override fun beta(): BetaService = beta
@@ -211,6 +215,13 @@ class OrbClientImpl(private val clientOptions: ClientOptions) : OrbClient {
             SubscriptionChangeServiceImpl.WithRawResponseImpl(clientOptions)
         }
 
+        override fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): OrbClient.WithRawResponse =
+            OrbClientImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier::accept).build()
+            )
+
         override fun topLevel(): TopLevelService.WithRawResponse = topLevel
 
         override fun beta(): BetaService.WithRawResponse = beta

orb-java-core/src/main/kotlin/com/withorb/api/services/async/AlertServiceAsync.kt

@@ -2,6 +2,7 @@
 
 package com.withorb.api.services.async
 
+import com.withorb.api.core.ClientOptions
 import com.withorb.api.core.RequestOptions
 import com.withorb.api.core.http.HttpResponseFor
 import com.withorb.api.models.Alert
@@ -15,6 +16,7 @@ import com.withorb.api.models.AlertListParams
 import com.withorb.api.models.AlertRetrieveParams
 import com.withorb.api.models.AlertUpdateParams
 import java.util.concurrent.CompletableFuture
+import java.util.function.Consumer
 
 interface AlertServiceAsync {
 
@@ -23,6 +25,13 @@ interface AlertServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: Consumer<ClientOptions.Builder>): AlertServiceAsync
+
     /** This endpoint retrieves an alert by its ID. */
     fun retrieve(alertId: String): CompletableFuture<Alert> =
         retrieve(alertId, AlertRetrieveParams.none())
@@ -301,6 +310,15 @@ interface AlertServiceAsync {
     /** A view of [AlertServiceAsync] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): AlertServiceAsync.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get /alerts/{alert_id}`, but is otherwise the same as
          * [AlertServiceAsync.retrieve].

orb-java-core/src/main/kotlin/com/withorb/api/services/async/AlertServiceAsyncImpl.kt

@@ -28,6 +28,7 @@ import com.withorb.api.models.AlertListParams
 import com.withorb.api.models.AlertRetrieveParams
 import com.withorb.api.models.AlertUpdateParams
 import java.util.concurrent.CompletableFuture
+import java.util.function.Consumer
 import kotlin.jvm.optionals.getOrNull
 
 class AlertServiceAsyncImpl internal constructor(private val clientOptions: ClientOptions) :
@@ -39,6 +40,9 @@ class AlertServiceAsyncImpl internal constructor(private val clientOptions: Clie
 
     override fun withRawResponse(): AlertServiceAsync.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: Consumer<ClientOptions.Builder>): AlertServiceAsync =
+        AlertServiceAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
     override fun retrieve(
         params: AlertRetrieveParams,
         requestOptions: RequestOptions,
@@ -100,6 +104,13 @@ class AlertServiceAsyncImpl internal constructor(private val clientOptions: Clie
 
         private val errorHandler: Handler<JsonValue> = errorHandler(clientOptions.jsonMapper)
 
+        override fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): AlertServiceAsync.WithRawResponse =
+            AlertServiceAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier::accept).build()
+            )
+
         private val retrieveHandler: Handler<Alert> =
             jsonHandler<Alert>(clientOptions.jsonMapper).withErrorHandler(errorHandler)
 

orb-java-core/src/main/kotlin/com/withorb/api/services/async/BetaServiceAsync.kt

@@ -2,6 +2,7 @@
 
 package com.withorb.api.services.async
 
+import com.withorb.api.core.ClientOptions
 import com.withorb.api.core.RequestOptions
 import com.withorb.api.core.http.HttpResponseFor
 import com.withorb.api.models.BetaCreatePlanVersionParams
@@ -11,6 +12,7 @@ import com.withorb.api.models.Plan
 import com.withorb.api.models.PlanVersion
 import com.withorb.api.services.async.beta.ExternalPlanIdServiceAsync
 import java.util.concurrent.CompletableFuture
+import java.util.function.Consumer
 
 interface BetaServiceAsync {
 
@@ -19,6 +21,13 @@ interface BetaServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: Consumer<ClientOptions.Builder>): BetaServiceAsync
+
     fun externalPlanId(): ExternalPlanIdServiceAsync
 
     /**
@@ -112,6 +121,13 @@ interface BetaServiceAsync {
     /** A view of [BetaServiceAsync] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(modifier: Consumer<ClientOptions.Builder>): BetaServiceAsync.WithRawResponse
+
         fun externalPlanId(): ExternalPlanIdServiceAsync.WithRawResponse
 
         /**

orb-java-core/src/main/kotlin/com/withorb/api/services/async/BetaServiceAsyncImpl.kt

@@ -24,6 +24,7 @@ import com.withorb.api.models.PlanVersion
 import com.withorb.api.services.async.beta.ExternalPlanIdServiceAsync
 import com.withorb.api.services.async.beta.ExternalPlanIdServiceAsyncImpl
 import java.util.concurrent.CompletableFuture
+import java.util.function.Consumer
 import kotlin.jvm.optionals.getOrNull
 
 class BetaServiceAsyncImpl internal constructor(private val clientOptions: ClientOptions) :
@@ -39,6 +40,9 @@ class BetaServiceAsyncImpl internal constructor(private val clientOptions: Clien
 
     override fun withRawResponse(): BetaServiceAsync.WithRawResponse = withRawResponse
 
+    override fun withOptions(modifier: Consumer<ClientOptions.Builder>): BetaServiceAsync =
+        BetaServiceAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
     override fun externalPlanId(): ExternalPlanIdServiceAsync = externalPlanId
 
     override fun createPlanVersion(
@@ -71,6 +75,13 @@ class BetaServiceAsyncImpl internal constructor(private val clientOptions: Clien
             ExternalPlanIdServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        override fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): BetaServiceAsync.WithRawResponse =
+            BetaServiceAsyncImpl.WithRawResponseImpl(
+                clientOptions.toBuilder().apply(modifier::accept).build()
+            )
+
         override fun externalPlanId(): ExternalPlanIdServiceAsync.WithRawResponse = externalPlanId
 
         private val createPlanVersionHandler: Handler<PlanVersion> =

orb-java-core/src/main/kotlin/com/withorb/api/services/async/CouponServiceAsync.kt

@@ -2,6 +2,7 @@
 
 package com.withorb.api.services.async
 
+import com.withorb.api.core.ClientOptions
 import com.withorb.api.core.RequestOptions
 import com.withorb.api.core.http.HttpResponseFor
 import com.withorb.api.models.Coupon
@@ -12,6 +13,7 @@ import com.withorb.api.models.CouponListPageAsync
 import com.withorb.api.models.CouponListParams
 import com.withorb.api.services.async.coupons.SubscriptionServiceAsync
 import java.util.concurrent.CompletableFuture
+import java.util.function.Consumer
 
 interface CouponServiceAsync {
 
@@ -20,6 +22,13 @@ interface CouponServiceAsync {
      */
     fun withRawResponse(): WithRawResponse
 
+    /**
+     * Returns a view of this service with the given option modifications applied.
+     *
+     * The original service is not modified.
+     */
+    fun withOptions(modifier: Consumer<ClientOptions.Builder>): CouponServiceAsync
+
     fun subscriptions(): SubscriptionServiceAsync
 
     /**
@@ -136,6 +145,15 @@ interface CouponServiceAsync {
      */
     interface WithRawResponse {
 
+        /**
+         * Returns a view of this service with the given option modifications applied.
+         *
+         * The original service is not modified.
+         */
+        fun withOptions(
+            modifier: Consumer<ClientOptions.Builder>
+        ): CouponServiceAsync.WithRawResponse
+
         fun subscriptions(): SubscriptionServiceAsync.WithRawResponse
 
         /**