fix(http-client-java): honor response replacements

[Weidong Xu (weidongxu-microsoft)]

Summary

Honor void and raw-byte response replacements for basic Java client operations. Preserve HTTP metadata, exception handling, and Azure protocol responses.

Update the tracked sync/async clients and add Spector coverage for the response-replacement scenarios introduced in #12137.

The _specs_ client updates and tests are isolated in a separate commit so they can be excluded if the namespace needs to change.

Validation

Emitter build, lint, formatting, and all 39 emitter tests passed. Targeted Java mapper/template and Azure Spector tests passed, along with native ClientCore and Azure model-response-overload checks.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client-java

Show changes

@typespec/http-client-java - fix ✏️

Honor void and raw-byte response replacements in generated Java clients, preserving types used by typed response headers. Fix raw-byte conversion for text responses.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[Copilot]

🟡 Changes recommended

Response replacement detection can misclassify parameter-only overrides and mishandles bodyless byte replacements.

5 open findings

• Handle bodyless byte replacements in Azure V1 response generation · New
• Use explicit replacement signals instead of return-type inference · New
• Preserve byte replacements for bodyless standard and Azure V2 responses · New
• Add SimpleAsync coverage for void convenience response mapping · New
• Add SimpleSync coverage for typed void replacement responses · New

What changed in this PR

Adds Java emitter support for TCGC void and raw-byte response replacements while preserving protocol responses.

Changes:

• Carries response overrides through the emitter and generator.
• Updates generated Azure clients and adds unit/Spector coverage.
• Documents the behavior and adds a fix changeset.

File	Description
packages/​http-client-java/​README.md	Documents response replacement.
.../​ResponseReplacementTests.java	Tests generated sync/async clients.
.../​responsereplacement_metadata.json	Updates generated metadata.
.../​ResponseReplacementClient.java	Updates generated sync API.
.../​ResponseReplacementAsyncClient.java	Updates generated async API.
.../​models/​Widget.java	Removes unused generated model.
.../​models/​package-info.java	Removes obsolete model package metadata.
.../​ClientMethodMapperTests.java	Tests replacement return-type mapping.
.../​ConvenienceSyncMethodTemplate.java	Handles synchronous void conversion.
.../​ConvenienceAsyncMethodTemplate.java	Handles asynchronous void conversion.
.../​ClientMethodsReturnDescription.java	Maps convenience response overrides.
.../​ConvenienceApi.java	Adds the response override model.
.../​response-replacement.tsp	Defines replacement test scenarios.
.../​code-model.test.ts	Characterizes flavor-specific output.
.../​common/​operation.ts	Extends the emitter code model.
.../​code-model-builder.ts	Detects and emits response replacements.
.chronus/​changes/​http-client-java-response-replacement.md	Records the fix.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Bodyless HEAD void replacements remain undetected, and their async Boolean protocol path would generate an incompatible return type.

2 open findings

• Detect void replacement for bodyless HEAD operations · New
• Use then() for void convenience methods with Boolean protocol bodies · New

5 resolved since last review

• Handle bodyless byte replacements in Azure V1 response generation
• Preserve byte replacements for bodyless standard and Azure V2 responses
• Use explicit replacement signals instead of return-type inference
• Add SimpleSync coverage for typed void replacement responses
• Add SimpleAsync coverage for void convenience response mapping

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Typed-header visibility regresses for Azure model overloads, and committed Spector execution coverage is missing.

1 open finding

• Add Spector tests for generated void and raw-byte response replacements · New

2 resolved since last review

• Use then() for void convenience methods with Boolean protocol bodies
• Detect void replacement for bodyless HEAD operations

Previously missed (1)

In code that hasn't changed since last review

Derive response-header model tracking independently of replacement convenience …

packages/​http-client-java/​emitter/​src/​code-model-builder.ts:2480

Disabling trackConvenienceApi for a replacement also disables header-schema tracking below. In Azure V1 with max-overload: model, the generated ResponseBase<Headers, ...> still publicly exposes typed headers, but enum/model header schemas are no longer promoted to public usage; ClientMapper.java:611-618 requires that promotion for public typed-header models. Derive trackResponseHeadersAsModel directly from the presence/options of op.convenienceApi instead.

    let trackConvenienceApi: boolean = Boolean(op.convenienceApi) && !replaceConvenienceResponse;
    const trackResponseHeadersAsModel =
      trackConvenienceApi &&
      (op.convenienceApi?.responseHeadersAsModel === true ||
        (this.isAzureV1() && this.options["max-overload"] === "model"));

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The implementation preserves protocol behavior, includes focused regression coverage, and addresses the previously identified edge cases.

0 open findings

1 resolved since last review

• Add Spector tests for generated void and raw-byte response replacements

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The cross-layer behavior, diagnostics, generated output, and relevant edge cases are consistently covered.

0 open findings

🧠 Review effort: Balanced