Adding custom code

This page covers how to add custom logic, methods, interceptors, and dependencies to your Java SDK.

Adding custom logic

To get started adding custom code:

1
package com.example.helper;
2
3
public class Helper {
4
5
public static void myHelper() {
6
    System.out.println("Hello World!");
7
}
8
9
}

1
# Specify files that shouldn't be modified by Fern
2
3
src/main/java/<package>/Helper.java

1
import com.example.helper.Helper;
2
3
public class Main {
4
5
public static void main(String[] args) {
6
    Helper.myHelper();
7
}
8
9
}

Adding custom SDK methods

Fern also allows you to add custom methods to the SDK itself (e.g. client.my_method() ) by inheriting the Fern generated client and then extending it.

1
- name: fern-java-sdk
2
    version: "..."
3
    config:
4
      client-class-name: BaseClient

1
package com.example;
2
3
import com.example.client.BaseClient;
4
5
public class MyClient extends BaseClient { // extend the Fern generated client
6
7
  public void myHelper() {
8
    System.out.println("Hello World!");
9
  }
10
11
}

1
+ src/main/java/com/example/MyClient.java

1
client.myHelper();

Adding custom client configuration

The Java SDK generator supports builder extensibility through an opt-in self-type pattern. When enabled via the enable-extensible-builders flag, generated builders can be extended while maintaining type safety during method chaining.

Common use cases include:

• Dynamic URL construction: Replace placeholders with runtime values (e.g., https://api.${TENANT}.example.com)
• Custom authentication: Implement complex auth flows beyond basic token authentication
• Request transformation: Add custom headers or modify requests globally
• Multi-tenant support: Add tenant-specific configuration and headers

1
groups:
2
  local:
3
    generators:
4
      - name: fern-java-sdk
5
        version: 2.39.6
6
        config:
7
          enable-extensible-builders: true

1
public abstract class BaseClientBuilder<T extends BaseClientBuilder<T>> {
2
    protected abstract T self();
3
    
4
    public T token(String token) {
5
        return self();  // Returns your custom type, not BaseClientBuilder
6
    }
7
}

1
public class CustomApiBuilder extends BaseClientBuilder<CustomApiBuilder> {
2
    @Override
3
    protected CustomApiBuilder self() {
4
        return this;
5
    }
6
7
    @Override
8
    protected void setEnvironment(ClientOptions.Builder builder) {
9
        // Customize environment URL
10
        String url = this.environment.getUrl();
11
        String expandedUrl = expandEnvironmentVariables(url);
12
        builder.environment(Environment.custom(expandedUrl));
13
    }
14
15
    @Override
16
    protected void setAdditional(ClientOptions.Builder builder) {
17
        // Add custom headers
18
        builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
19
    }
20
}

1
BaseClient client = new CustomApiBuilder()
2
    .token("my-token")        // returns CustomApiBuilder
3
    .tenantId("tenant-123")   // returns CustomApiBuilder  
4
    .timeout(30)              // returns CustomApiBuilder
5
    .build();
6
7
client.users().list();

1
+ src/main/java/com/example/CustomApiBuilder.java

Default implementation

If you don’t need to extend the builder, use the provided Impl class:

1
BaseClient client = BaseClientBuilder.Impl()
2
    .token("my-token")
3
    .timeout(30)
4
    .build();

Method reference

Each method serves a specific purpose and is only generated when needed:

Common patterns

1
@Override
2
protected void setEnvironment(ClientOptions.Builder builder) {
3
    String url = this.environment.getUrl()
4
        .replace("/api/", "/tenants/" + tenantId + "/");
5
    builder.environment(Environment.custom(url));
6
}

1
@Override
2
protected void setAuthentication(ClientOptions.Builder builder) {
3
    super.setAuthentication(builder); // Keep existing auth
4
    builder.addHeader("Authorization", () ->
5
        "Bearer " + tokenProvider.getAccessToken()
6
    );
7
}

1
@Override
2
protected void setEnvironment(ClientOptions.Builder builder) {
3
    String url = this.environment.getUrl();
4
    // Replace ${VAR_NAME} with environment variables
5
    Pattern pattern = Pattern.compile("\\$\\{([^}]+)\\}");
6
    Matcher matcher = pattern.matcher(url);
7
    StringBuffer result = new StringBuffer();
8
    
9
    while (matcher.find()) {
10
        String envVar = System.getenv(matcher.group(1));
11
        matcher.appendReplacement(result, 
12
            envVar != null ? envVar : matcher.group(0));
13
    }
14
    matcher.appendTail(result);
15
    
16
    builder.environment(Environment.custom(result.toString()));
17
}

1
@Override
2
protected void setAdditional(ClientOptions.Builder builder) {
3
    builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
4
    builder.addHeader("X-Tenant-ID", this.tenantId);
5
    
6
    if (FeatureFlags.isEnabled("new-feature")) {
7
        builder.addHeader("X-Feature-Flag", "new-feature");
8
    }
9
}

Requirements

• Fern Java SDK version: 2.39.6 or later
• Configuration: enable-extensible-builders: true in generators.yml

Adding custom interceptors

OkHttp interceptors observe and rewrite every request and response an SDK sends, which covers request signing, public key client validation, and custom logging or tracing. Setting custom-interceptors to true adds an addInterceptor(okhttp3.Interceptor) method to your generated client builder, giving the developers who install your SDK a supported extension point for those customizations:

1
groups:
2
  java-sdk:
3
    generators:
4
      - name: fern-java-sdk
5
        version: 4.16.0
6
        config:
7
          custom-interceptors: true

Developers using your SDK register interceptors as they construct the client. Each call to addInterceptor appends to the chain, and all are applied to the underlying OkHttpClient at build time:

1
YourApiClient client = YourApiClient.builder()
2
    .token("<token>")
3
    .addInterceptor(chain -> chain.proceed(
4
        chain.request().newBuilder()
5
            .header("X-Request-Source", "checkout-service")
6
            .build()))
7
    .build();

Custom interceptors run in registration order, inside Fern’s retry interceptor, so a retried request passes through them again and a signing interceptor signs each attempt. For OAuth APIs, addInterceptor is available both before and after the token(...) or credentials(...) call.

To attach an interceptor yourself rather than requiring every caller to register one, override the protected setInterceptors(ClientOptions.Builder) method on a custom builder, and add that builder to .fernignore so regeneration doesn’t overwrite it.

Adding custom dependencies

To add packages that your custom code requires, update your generators.yml.

1
- name: fern-java-sdk
2
  version: "..."
3
  config:
4
    custom-dependencies:
5
      - org.apache.commons:commons-lang3:3.12.0
6
      - org.slf4j:slf4j-api:2.0.7