Use Optional return types instead of nullable boxed primitives in public API #187

Summary

The public API of this SDK uses nullable boxed types (Boolean, Integer, Double) on mutable config/builder classes to represent optional values. This is a C# idiom — not a Java one. Java has had Optional<T>, OptionalInt, and OptionalDouble since Java 8 (2014), and returning Optional from getters is the established idiomatic way to express "this value may be absent."

Today the SDK has ~30 public getters on mutable classes returning nullable boxed types and zero uses of Optional anywhere in non-generated source code. This is a clear signal that the nullable-return convention was carried over from the C# reference implementation rather than adapted to Java idioms during the port.

Scope

What to change

Only mutable config/builder classes (regular classes with hand-written getters/setters). These classes all have tri-state semantics where null means "use the server/runtime default" — a contract that is invisible in the current type signatures but becomes explicit with Optional.

What NOT to change

• Record types — Record accessor methods are auto-generated from components. Optional as a record component is unidiomatic and clashes with Jackson deserialization. Records like PingResponse, ToolDefinition, PreToolUseHookOutput, PostToolUseHookOutput, SessionEndHookOutput, and UserPromptSubmittedHookOutput are explicitly out of scope.
• Generated code under src/generated/java/ — do not modify.
• Internal fields — Fields remain as nullable boxed types for Jackson serialization (@JsonInclude(NON_NULL)). Only the getter return types and setter parameter types change.

Specification

For each affected getter/setter pair, apply this transformation:

For Boolean fields

Before:

private Boolean enableSessionTelemetry;

public Boolean getEnableSessionTelemetry() {
    return enableSessionTelemetry;
}

public SessionConfig setEnableSessionTelemetry(Boolean enableSessionTelemetry) {
    this.enableSessionTelemetry = enableSessionTelemetry;
    return this;
}

After:

private Boolean enableSessionTelemetry;

public Optional<Boolean> getEnableSessionTelemetry() {
    return Optional.ofNullable(enableSessionTelemetry);
}

public SessionConfig setEnableSessionTelemetry(boolean enableSessionTelemetry) {
    this.enableSessionTelemetry = enableSessionTelemetry;
    return this;
}

public SessionConfig clearEnableSessionTelemetry() {
    this.enableSessionTelemetry = null;
    return this;
}

For Integer fields

Before:

private Integer sessionIdleTimeoutSeconds;

public Integer getSessionIdleTimeoutSeconds() {
    return sessionIdleTimeoutSeconds;
}

public CopilotClientOptions setSessionIdleTimeoutSeconds(Integer sessionIdleTimeoutSeconds) {
    this.sessionIdleTimeoutSeconds = sessionIdleTimeoutSeconds;
    return this;
}

After:

private Integer sessionIdleTimeoutSeconds;

public OptionalInt getSessionIdleTimeoutSeconds() {
    return sessionIdleTimeoutSeconds == null ? OptionalInt.empty() : OptionalInt.of(sessionIdleTimeoutSeconds);
}

public CopilotClientOptions setSessionIdleTimeoutSeconds(int sessionIdleTimeoutSeconds) {
    this.sessionIdleTimeoutSeconds = sessionIdleTimeoutSeconds;
    return this;
}

public CopilotClientOptions clearSessionIdleTimeoutSeconds() {
    this.sessionIdleTimeoutSeconds = null;
    return this;
}

For Double fields

Same pattern, using OptionalDouble and primitive double setter.

Affected classes and fields

Public API config classes (user-facing)

CopilotClientOptions.java

SessionConfig.java

ResumeSessionConfig.java

InfiniteSessionConfig.java

InputOptions.java

ModelCapabilitiesOverride.Supports (inner class)

ModelCapabilitiesOverride.Limits (inner class)

ProviderConfig.java

TelemetryConfig.java

SessionUiCapabilities.java

CustomAgentConfig.java

UserInputRequest.java

Internal wire DTOs (not directly user-facing, but same pattern applies)

CreateSessionRequest.java

ResumeSessionRequest.java

McpServerConfig.java (abstract base)

ModelLimits.java

Caller updates required

All internal callers that null-check these getters must be updated to use Optional APIs. Common patterns:

// BEFORE (e.g., CliServerManager.java)
if (options.getSessionIdleTimeoutSeconds() != null) {
    args.add("--session-idle-timeout");
    args.add(String.valueOf(options.getSessionIdleTimeoutSeconds()));
}

// AFTER
options.getSessionIdleTimeoutSeconds().ifPresent(timeout -> {
    args.add("--session-idle-timeout");
    args.add(String.valueOf(timeout));
});

// BEFORE (e.g., CliServerManager.java)
if (options.getUseLoggedInUser() != null && options.getUseLoggedInUser()) {
    args.add("--use-logged-in-user");
}

// AFTER
options.getUseLoggedInUser().filter(v -> v).ifPresent(v ->
    args.add("--use-logged-in-user")
);

// BEFORE (e.g., SessionRequestBuilder.java)
Boolean value = config.getEnableSessionTelemetry();
if (value != null) {
    request.setEnableSessionTelemetry(value);
}

// AFTER
config.getEnableSessionTelemetry().ifPresent(request::setEnableSessionTelemetry);

Jackson serialization

No changes needed to Jackson configuration. The internal fields remain as nullable boxed types (Boolean, Integer, Double) with @JsonInclude(NON_NULL). Jackson reads/writes the fields directly — the Optional wrapper exists only on the getter return type, not on the field or in the serialized JSON.

Testing

• All existing tests must continue to pass after the changes.
• The clearXxx() methods should be exercised in tests to verify they reset the field to null (and that Jackson then omits the field from serialized output).
• Callers updated from null-check patterns to Optional patterns should produce identical behavior.

Why this matters

This is a breaking API change for getter return types and should be planned accordingly.