From 87c752aae1a2a94559d07788d90bfdc08f5583aa Mon Sep 17 00:00:00 2001 From: Tanmay Singh Date: Fri, 25 Jul 2025 13:33:40 -0400 Subject: [PATCH 1/3] Update builder extension docs with new template --- .../sdks/overview/java/custom-code.mdx | 152 +++++++++++++++--- 1 file changed, 126 insertions(+), 26 deletions(-) diff --git a/fern/products/sdks/overview/java/custom-code.mdx b/fern/products/sdks/overview/java/custom-code.mdx index 1531a8c41..6a1adef61 100644 --- a/fern/products/sdks/overview/java/custom-code.mdx +++ b/fern/products/sdks/overview/java/custom-code.mdx @@ -106,69 +106,91 @@ description: Augment your Java SDK with custom utilities ## Adding custom client configuration -When you need to intercept and transform client configuration before the SDK client is created, you can extend the generated builder classes. This allows you to add custom code and logic during the client initialization process. +The Java SDK generator now supports builder extensibility through a template method pattern. By extending the generated builder classes and overriding protected methods, you can customize how your SDK client is configured without modifying generated code. Common use cases include: - **Dynamic URL construction**: Replace placeholders with runtime values (e.g., `https://api.${DEV_NAMESPACE}.example.com`) - **Custom authentication**: Implement complex auth flows beyond basic token authentication - **Request transformation**: Add custom headers or modify requests globally +### How it works + +Generated builders use protected methods that can be overridden: + +```java +public class BaseApiClientBuilder { + protected ClientOptions buildClientOptions() { + ClientOptions.Builder builder = ClientOptions.builder(); + setEnvironment(builder); + setAuthentication(builder); // Only if API has auth + setCustomHeaders(builder); // Only if API defines headers + setVariables(builder); // Only if API has variables + setHttpClient(builder); + setTimeouts(builder); + setRetries(builder); + setAdditional(builder); + return builder.build(); + } +} +``` + -### Create a custom client that extends the base client +### Create a custom client class -This client will serve as the entry point for your customized SDK. +Extend the generated base client: ```java title="src/main/java/com/example/MyClient.java" package com.example; -import com.example.client.BaseClient; -import com.example.client.ClientOptions; +import com.example.api.BaseClient; +import com.example.api.core.ClientOptions; public class MyClient extends BaseClient { public MyClient(ClientOptions clientOptions) { super(clientOptions); } - + public static MyClientBuilder builder() { return new MyClientBuilder(); } } ``` -### Create a custom builder with your transformation logic +### Create a custom builder -Override the `buildClientOptions()` method to intercept and modify the configuration before the client is created. +Override methods to customize behavior: -```java title="src/main/java/com/example/MyClientBuilder.java" {10} +```java title="src/main/java/com/example/MyClientBuilder.java" package com.example; -import com.example.client.BaseClient.BaseClientBuilder; -import com.example.client.ClientOptions; -import com.example.environment.Environment; +import com.example.api.BaseClient.BaseClientBuilder; +import com.example.api.core.ClientOptions; +import com.example.api.core.Environment; public class MyClientBuilder extends BaseClientBuilder { + @Override - protected ClientOptions buildClientOptions() { - ClientOptions base = super.buildClientOptions(); - - // Transform configuration as needed - String transformedUrl = transformEnvironmentVariables( - base.environment().getUrl() - ); - - return ClientOptions.builder() - .from(base) - .environment(Environment.custom(transformedUrl)) - .build(); + protected void setEnvironment(ClientOptions.Builder builder) { + String url = this.environment.getUrl(); + String expandedUrl = expandEnvironmentVariables(url); + builder.environment(Environment.custom(expandedUrl)); + } + + @Override + protected void setAdditional(ClientOptions.Builder builder) { + builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString()); + } + + @Override + public MyClient build() { + return new MyClient(buildClientOptions()); } } ``` ### Update `.fernignore` -Add the `MyClient.java` and `MyClientBuilder.java` to `.fernignore`. - ```diff title=".fernignore" + src/main/java/com/example/MyClient.java + src/main/java/com/example/MyClientBuilder.java @@ -176,6 +198,84 @@ Add the `MyClient.java` and `MyClientBuilder.java` to `.fernignore`. +### Method reference + +Each method serves a specific purpose and is only generated when needed: + +| Method | Purpose | Available When | +|--------|---------|----------------| +| `setEnvironment(builder)` | Customize environment/URL configuration | Always | +| `setAuthentication(builder)` | Modify or add authentication | Only if API has auth | +| `setCustomHeaders(builder)` | Add custom headers defined in API spec | Only if API defines headers | +| `setVariables(builder)` | Configure API variables | Only if API has variables | +| `setHttpClient(builder)` | Customize OkHttp client | Always | +| `setTimeouts(builder)` | Modify timeout settings | Always | +| `setRetries(builder)` | Modify retry settings | Always | +| `setAdditional(builder)` | Final extension point for any custom configuration | Always | +| `validateConfiguration()` | Add custom validation logic | Always | +| `buildClientOptions()` | Orchestrates all configuration methods (rarely need to override) | Always | + +### Common patterns + +The `setAdditional()` method is your extension point for adding configuration that doesn't fit into other methods: + + +```java +@Override +protected void setEnvironment(ClientOptions.Builder builder) { + String baseUrl = this.environment.getUrl(); + String tenantUrl = baseUrl.replace("/api/", "/api/tenants/" + tenantId + "/"); + builder.environment(Environment.custom(tenantUrl)); +} +``` + + + +```java +@Override +protected void setAuthentication(ClientOptions.Builder builder) { + builder.addHeader("Authorization", () -> + "Bearer " + tokenProvider.getAccessToken() + ); +} +``` + + + +```java +@Override +protected void setAdditional(ClientOptions.Builder builder) { + // Add request tracking + builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString()); + builder.addHeader("X-Client-Version", "1.0.0"); + + // Add feature flags + if (FeatureFlags.isEnabled("new-algorithm")) { + builder.addHeader("X-Feature-Flag", "new-algorithm"); + } +} +``` + + + +```java +@Override +protected void setHttpClient(ClientOptions.Builder builder) { + OkHttpClient customClient = new OkHttpClient.Builder() + .connectTimeout(30, TimeUnit.SECONDS) + .readTimeout(60, TimeUnit.SECONDS) + .addInterceptor(new RetryInterceptor()) + .connectionPool(new ConnectionPool(50, 5, TimeUnit.MINUTES)) + .build(); + builder.httpClient(customClient); +} +``` + + +### Requirements + +- **Fern Java SDK version**: 2.39.1 or later + ## Adding custom dependencies From e58071af831f75b59435c2da463e74c3968bc4f0 Mon Sep 17 00:00:00 2001 From: Tanmay Singh Date: Fri, 25 Jul 2025 13:39:30 -0400 Subject: [PATCH 2/3] Remove a line about setAdditional --- fern/products/sdks/overview/java/custom-code.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/fern/products/sdks/overview/java/custom-code.mdx b/fern/products/sdks/overview/java/custom-code.mdx index 6a1adef61..cfb5a5164 100644 --- a/fern/products/sdks/overview/java/custom-code.mdx +++ b/fern/products/sdks/overview/java/custom-code.mdx @@ -217,8 +217,6 @@ Each method serves a specific purpose and is only generated when needed: ### Common patterns -The `setAdditional()` method is your extension point for adding configuration that doesn't fit into other methods: - ```java @Override From cd17b2a72959d0efcb3650639a0094ff4236a9bd Mon Sep 17 00:00:00 2001 From: Tanmay Singh Date: Fri, 25 Jul 2025 15:56:11 -0400 Subject: [PATCH 3/3] nit fixes --- fern/products/sdks/overview/java/custom-code.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/fern/products/sdks/overview/java/custom-code.mdx b/fern/products/sdks/overview/java/custom-code.mdx index cfb5a5164..e333fa491 100644 --- a/fern/products/sdks/overview/java/custom-code.mdx +++ b/fern/products/sdks/overview/java/custom-code.mdx @@ -106,7 +106,7 @@ description: Augment your Java SDK with custom utilities ## Adding custom client configuration -The Java SDK generator now supports builder extensibility through a template method pattern. By extending the generated builder classes and overriding protected methods, you can customize how your SDK client is configured without modifying generated code. +The Java SDK generator supports builder extensibility through a template method pattern. By extending the generated builder classes and overriding protected methods, you can customize how your SDK client is configured without modifying generated code. Common use cases include: - **Dynamic URL construction**: Replace placeholders with runtime values (e.g., `https://api.${DEV_NAMESPACE}.example.com`) @@ -157,7 +157,7 @@ public class MyClient extends BaseClient { } ``` -### Create a custom builder +### Create a custom builder class Override methods to customize behavior: @@ -191,6 +191,8 @@ public class MyClientBuilder extends BaseClientBuilder { ### Update `.fernignore` +By adding these two files to `.fernignore`, fern will not update them on new generations. + ```diff title=".fernignore" + src/main/java/com/example/MyClient.java + src/main/java/com/example/MyClientBuilder.java @@ -222,7 +224,7 @@ Each method serves a specific purpose and is only generated when needed: @Override protected void setEnvironment(ClientOptions.Builder builder) { String baseUrl = this.environment.getUrl(); - String tenantUrl = baseUrl.replace("/api/", "/api/tenants/" + tenantId + "/"); + String tenantUrl = baseUrl.replace("/api/", "/tenants/" + tenantId + "/"); builder.environment(Environment.custom(tenantUrl)); } ```