Skip to content

[Java] Consume TCGC LRO status metadata and operation ID (core generator) - #12566

Draft
iscai-msft wants to merge 6 commits into
microsoft:mainfrom
iscai-msft:java-tcgc-lro-metadata
Draft

iscai-msft wants to merge 6 commits into
microsoft:mainfrom
iscai-msft:java-tcgc-lro-metadata

Conversation

@iscai-msft

@iscai-msft iscai-msft commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Part of Azure/typespec-azure#5996

The Java emitter (@typespec/http-client-java) consumes the LRO metadata added in TCGC 0.74.0:

The Azure/typespec-azure follow-up pins this commit through packages/typespec-java/core-commit.json, enables azure/client-generator-core/lro/operation-id, and carries the customization table.

Changes

Status metadata: No new generator API is needed: the typed PollResponse<T>.getValue() is the latest status-monitor body, including failed responses. The metadata test checks intermediate and terminal values. azure-core SyncPoller and PollerFlux do not expose continuation-token or poller rehydration.

Operation ID: Supported typed poll-result models expose getOperationId(). The selected body property wins; the polling URL path is the fallback. The sync and async wrappers capture TCGC's selected response header and delegate polling with the complete URL. A selected existing getOperationId() uses the same path fallback. Unsupported nested or non-string properties and naming conflicts produce warnings. Poll-result overrides do not generate an accessor that the polling strategy cannot populate.

Availability tradeoff: The ID is exposed on the status model rather than on the poller. An empty initial 202 has no model, so callers cannot access a path ID before the first status response with a body. The ID is applied on subsequent status responses, including failure. This does not add a poller-level accessor.

The generated API is limited to azure-core, non-fluent typed poll results. Protocol (BinaryData) methods and wire formats are unchanged. @typespec/http-client-java already uses TCGC 0.74.0, so no version bump was needed.

SyncPoller<DocumentAnalysisStatus, DocumentAnalysisResult> poller = client.beginAnalyze("document-1");
String operationId = poller.poll().getValue().getOperationId();

Validation

  • CI passes, including all Java build, test and regeneration matrix jobs, formatting, and lint.
  • Full generator build and unit tests, emitter tests and typecheck pass locally.
  • Focused sync/async polling, selected-header, polymorphic, model fallback and Spector metadata and operation ID tests pass. Generated clients were also checked with mixed poll-result overrides on shared models.

Remaining (draft)

Generate a read-only getOperationId() on long-running poll-result models,
populated from the @lroOperationId monitor-body property and/or the polling
URL path parameter. Add Spector e2e tests for lro/operation-id.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the emitter:client:java Issue for the Java client emitter: @typespec/http-client-java label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/http-client-java
Show changes

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

Expose the LRO operation ID selected by @lroOperationId on supported typed poll-result models via getOperationId(). The poll-result model is available once a status response with a body is received; its body property takes precedence over the polling URL path. Polling continues to use the complete polling URL.,> ,> java,> SyncPoller<DocumentAnalysisStatus, DocumentAnalysisResult> poller = client.beginAnalyze("document-1");,> String operationId = poller.poll().getValue().getOperationId();,>

@azure-sdk-automation

azure-sdk-automation Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

iscai-msft and others added 2 commits November 16, 2026 12:55
Compare the poll result with the cached schema rather than invoking its lazy getter, preserving existing LRO model output.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Preserve both upstream SSE metadata and LRO operation ID metadata in ClientModel and its builder.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
iscai-msft and others added 2 commits November 18, 2026 11:27
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@weidongxu-microsoft

Weidong Xu (weidongxu-microsoft) commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Generally LGTM

It adds a certain level of complexity to a rarely used feature, but at least it is not too complex.

One concern is if e.g. the model is also used in e.g. a property of a normal model. That getOperationId would be on the model, even if it is not in a polling context.

Wait a bit for Copilot review as well.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Polling can use the wrong header or fail to start, and generated operation-ID accessors can introduce incompatible overrides that break subclass compilation.

4 open issues
What changed in this PR

This PR connects TCGC operation-ID metadata to the Java emitter and core generator, exposing getOperationId() on supported azure-core, non-fluent typed polling models.

Changes:

  • Carry operation-ID sources through the emitter, code model, and Java mappings.
  • Generate body-first accessors with polling-URL fallback and sync/async polling wrappers.
  • Add metadata, template, and runtime coverage, plus generated fixtures and a changelog.

Paths are relative to packages/http-client-java/, except the changelog.

File Description
generator/​http-client-generator/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​TypeSpecPlugin.java Filters supported metadata and emits helpers.
generator/​http-client-generator-test/​src/​test/​java/​azure/​clientgenerator/​core/​lro/​operationid/​OperationIdTests.java Adds operation-ID integration tests.
generator/​http-client-generator-test/​src/​test/​java/​azure/​clientgenerator/​core/​lro/​operationid/​implementation/​OperationIdPollingStrategyTests.java Tests header capture and ID fallback.
generator/​http-client-generator-test/​src/​test/​java/​azure/​clientgenerator/​core/​lro/​metadata/​MetadataTests.java Checks intermediate status metadata.
generator/​http-client-generator-test/​src/​main/​resources/​META-INF/​azure-clientgenerator-core-lro-operationid_metadata.json Registers generated polling helpers.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​models/​TranslationWithPathStatus.java Adds combined body/path ID accessor.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​models/​TranslationStatus.java Adds body-derived ID accessor.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​models/​DocumentAnalysisStatus.java Adds path-derived ID accessor.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​implementation/​SyncOperationIdPollingStrategy.java Generated synchronous ID wrapper.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​implementation/​OperationIdPollingStrategy.java Generated asynchronous ID wrapper.
generator/​http-client-generator-test/​src/​main/​java/​azure/​clientgenerator/​core/​lro/​operationid/​implementation/​OperationIdClientImpl.java Applies wrappers to typed polling methods.
generator/​http-client-generator-core/​src/​test/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​template/​LroOperationIdModelTemplateTests.java Tests accessor generation and conflicts.
generator/​http-client-generator-core/​src/​main/​resources/​SyncOperationIdPollingStrategy.java Supplies synchronous wrapper template.
generator/​http-client-generator-core/​src/​main/​resources/​OperationIdPollingStrategy.java Supplies ID extraction and asynchronous wrapper.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​util/​ClientModelUtil.java Defines support checks and helper names.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​template/​ModelTemplate.java Generates ID fields, accessors, and warnings.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​model/​clientmodel/​ClientModel.java Stores model-level operation-ID metadata.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​mapper/​ProxyMethodMapper.java Exposes operation-name resolution for filtering.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​mapper/​PollingMetadata.java Constructs operation-ID polling wrappers.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​mapper/​ModelMapper.java Maps metadata onto supported models.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​extension/​model/​extensionmodel/​XmsExtensions.java Adds schema-level metadata extension.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​extension/​model/​codemodel/​LongRunningOperationIdMetadata.java Defines Java operation-ID source metadata.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​extension/​model/​codemodel/​LongRunningMetadata.java Attaches operation-ID sources to LROs.
generator/​http-client-generator-core/​src/​main/​java/​com/​microsoft/​typespec/​http/​client/​generator/​core/​extension/​model/​codemodel/​CodeModelCustomConstructor.java Deserializes the new schema extension.
emitter/​test/​fixtures/​lro-operation-id.tsp Defines path, body, and combined scenarios.
emitter/​test/​code-model.test.ts Verifies metadata propagation and merging.
emitter/​src/​common/​long-running-metadata.ts Defines emitter-side operation-ID metadata.
emitter/​src/​code-model-builder.ts Converts TCGC selections into code-model metadata.
.chronus/​changes/​java-tcgc-lro-metadata-2026-10-12-17-55-0.md Documents the feature and usage.

Review effort: Balanced

Comment on lines +100 to +106
final String headerArg = ClassType.STRING.defaultValueExpression(operationId.getPollingHeaderName());
final String operationIdPollingStrategy = String.format("new %s.%s<>(%s, %s, %s, %s)", packageName,
ClientModelUtil.OPERATION_ID_POLLING_STRATEGY, pollingStrategy, pathTemplateArg, pathParameterArg,
headerArg);
final String syncOperationIdPollingStrategy = String.format("new %s.%s<>(%s, %s, %s, %s)", packageName,
ClientModelUtil.SYNC_OPERATION_ID_POLLING_STRATEGY, syncPollingStrategy, pathTemplateArg,
pathParameterArg, headerArg);
Comment on lines +1586 to +1587
return conflict ? null : lroOperationId;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems a rare corner case. May not need to handle.

Comment on lines +1654 to +1655
methodBlock.methodReturn(LRO_OPERATION_ID_PROPERTY_VALUE_NAME + " != null ? "
+ LRO_OPERATION_ID_PROPERTY_VALUE_NAME + " : this." + LRO_OPERATION_ID_FIELD_NAME);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems a rare corner case. May not need to handle.

}
String path;
try {
path = URI.create(pollingUrl).getRawPath();
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b9420119-96ca-4665-8899-a2a907c1efec

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:client:java Issue for the Java client emitter: @typespec/http-client-java

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants