http-client-java, support `advanced-versioning` on `@added` optional parameter in TypeSpec, in non-DPG #9087

weidongxu-microsoft · 2025-11-25T07:32:20Z

This is already supported in DPG.
Here we support this for management. It should also apply to azure-v2, but we do not have test on it (as azure-v2 lib is not released).

This is enabled by advanced-versioning emitter option.

Test case

typespec/packages/http-client-java/generator/http-client-generator-test/tsp/arm-versioned.tsp

Lines 40 to 42 in 00fcc47

    
           @added(Versions.v2024_10_01_preview) 
        
           @query 
        
           newParameter?: string;

The difference on output be demonstrated here
2fe0045

… locally initialized

This reverts commit 0fa3f33.

This reverts commit 4991205.

Copilot

Pull request overview

This PR adds support for advanced-versioning in non-DPG (Data Plane Generation) mode for the http-client-java emitter, specifically targeting management (ARM) scenarios. The feature generates method overloads for operations with versioned parameters, allowing REST APIs to add optional parameters across versions while maintaining backward compatibility.

Key changes:

Updates @azure-tools/typespec-azure-resource-manager dependency from 0.62.0 to 0.62.1
Extends versioning support from DPG to management plane code generation
Adds logic to generate multiple method signatures for operations with @added versioned parameters
Includes comprehensive test case with ARM resource operations demonstrating the feature

Reviewed changes

Copilot reviewed 36 out of 40 changed files in this pull request and generated 62 comments.

Show a summary per file

File	Description
packages/http-client-java/package.json	Updates dependency versions including ARM resource manager to 0.62.1
packages/http-client-java/package-lock.json	Lock file updates matching package.json changes
packages/http-client-java/generator/http-client-generator-test/tsp/arm-versioned.tsp	New TypeSpec test specification demonstrating versioned ARM operations
packages/http-client-java/generator/http-client-generator-test/Generate.ps1	Adds configuration to enable advanced-versioning option for arm-versioned test
packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/ClientMethodMapper.java	Refactors versioning overload generation to support non-DPG scenarios with context parameters
packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java	Improves logic for determining when optional parameters need local variable instantiation
packages/http-client-java/generator/http-client-generator-mgmt/src/main/java/com/microsoft/typespec/http/client/generator/mgmt/mapper/FluentClientMethodMapper.java	Adds versioning overload generation for LRO methods in management plane
packages/http-client-java/generator/http-client-generator-mgmt/src/main/java/com/microsoft/typespec/http/client/generator/mgmt/model/clientmodel/fluentmodel/ResourceOperation.java	Improves parameter selection by choosing client method with most parameters
Multiple generated Java files	Generated test code demonstrating the advanced-versioning feature output

Files not reviewed (1)

packages/http-client-java/package-lock.json: Language not supported

...in/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java

...oft/typespec/http/client/generator/mgmt/model/clientmodel/fluentmodel/ResourceOperation.java

...in/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java

...rator/http-client-generator-test/src/main/java/tsptest/armversioned/ArmVersionedManager.java

...generator-test/src/main/java/tsptest/armversioned/implementation/ArmVersionedClientImpl.java

...r-test/src/main/java/tsptest/armversioned/implementation/TopLevelArmResourcesClientImpl.java

…/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java Co-authored-by: Copilot <[email protected]>

…com/weidongxu-microsoft/typespec into http-client-java_versioning-non-dpg

This reverts commit 6a8d204.

weidongxu-microsoft · 2025-11-26T09:55:03Z

Updated test case (now include Get and Delete)

Difference on output demonstrated

haolingdong-msft · 2025-11-28T07:38:27Z

packages/http-client-java/generator/http-client-generator-test/Generate.ps1

    $tspOptions += " --option ""@typespec/http-client-java.customization-class=../../customization/src/main/java/KeyVaultCustomization.java"""
+  } elseif ($tspFile -match "tsp[\\/]arm-versioned.tsp") {
+    # enable advanced versioning for resiliency test
+    $tspOptions += " --option ""@typespec/http-client-java.advanced-versioning=true"""


Just for understanding purpose: is advanced-versioning default to false, so we have to explicitly set true here? Do we have plan to default it to true?

haolingdong-msft · 2025-11-28T07:54:09Z

...va/com/microsoft/typespec/http/client/generator/core/model/clientmodel/ClientMethodType.java

     * Mono&lt;PagedResponseBase&lt;H,T&gt;&gt;.
     */
    PagingAsyncSinglePage(2, true, false, false),
-    SimulatedPagingSync(3, false, false, true), // unused


double confirm: is this just code clean up unrelated to advanced versioning?

haolingdong-msft · 2025-11-28T08:23:45Z

...in/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java

-            // If the parameter isn't required and the client method only uses required parameters, optional
-            // parameters are omitted and will need to instantiated in the method.
-            boolean optionalOmitted = clientMethod.getOnlyRequiredParameters() && !parameter.isRequired();
+            // If the parameter isn't required and the client method only uses required parameters,


the client method only uses required parameters: just trying to understasnd the meaning. Does it mean in the client method with only required parameters, we need to initialize the optional parameters value? But I thought in client method with full parameters, we need to initialize optional parameters if user does not provide as well.
Would be awesome if we could add an example (better in javadoc) to explain the case we want to handle in the logics from line 176-190?

haolingdong-msft · 2025-11-28T08:43:24Z

...c/main/java/com/microsoft/typespec/http/client/generator/core/mapper/ClientMethodMapper.java


-    private static void createOverloadForVersioning(boolean isProtocolMethod, List<ClientMethod> methods,
-        ClientMethod baseMethod) {
+    protected void createOverloadForVersioning(List<ClientMethod> methods, ClientMethod baseMethod,


might be worth to add some javadoc about this method.

haolingdong-msft · 2025-11-28T09:25:50Z

...ent-generator-test/src/main/java/tsptest/armversioned/fluent/TopLevelArmResourcesClient.java

+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    void delete(String resourceGroupName, String topLevelArmResourcePropertiesName);


Does delete need overloaded functions similar as deleteWithResponse? e.g.

void delete(String resourceGroupName, String topLevelArmResourcePropertiesName, String parameter, Context context)

void delete(String resourceGroupName, String topLevelArmResourcePropertiesName, String parameter, String newParameter, Context context)

weidongxu-microsoft added 30 commits October 21, 2025 14:35

fallback to version compare by date

7c81a00

set to undefined, if cannot find version in apiVersions

941939b

nit

c598d4e

fix lint

e49c321

test case

225dd59

nit to cover the case of the erasure of preview api-version

a668d88

Merge branch 'main' into http-client-java_versioning-non-dpg

ea588f3

partial tool

8d2f7ab

simple method uses WithResponse

ff2e84e

enhance

bb96c02

Merge branch 'main' into http-client-java_versioning-non-dpg

032f3a9

improve client method template to recognize parameter that need to be…

99ae880

… locally initialized

format

f01061b

regen

d6652f0

advanced versioning for arm-versioned test

0aa271a

regen with advanced-versioning

5e17044

test

a61c34a

Merge branch 'main' into http-client-java_versioning-non-dpg

ce526d0

update addOptionalVariables

0fa3f33

Revert "update addOptionalVariables"

b4fa958

This reverts commit 0fa3f33.

overload for LRO createOrUpdate in mgmt

d8f7ed4

overload for method for lro and pageable

ffb4c88

regen

a451335

mgmt, update logic for taking the client method of full parameters

64218ae

update npm deps

d99c9cd

bug fix

2b3b222

regen

9653e35

update test

7648f09

make a diff

4991205

Revert "make a diff"

2fe0045

This reverts commit 4991205.

Copilot AI reviewed Nov 26, 2025

View reviewed changes

weidongxu-microsoft and others added 10 commits November 26, 2025 10:43

Update packages/http-client-java/generator/http-client-generator-core…

ccf67b6

…/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplate.java Co-authored-by: Copilot <[email protected]>

format

7c93f90

Merge branch 'main' into http-client-java_versioning-non-dpg

bf9d6ea

add more API to test case

e730949

bug fix for not taking the client method of full parameters

f4f4461

Merge branch 'http-client-java_versioning-non-dpg' of https://github.…

7e90d5c

…com/weidongxu-microsoft/typespec into http-client-java_versioning-non-dpg

regen

dd89acb

update test

66dcfba

regen

55551cf

update test

f420686

weidongxu-microsoft marked this pull request as draft November 26, 2025 09:06

weidongxu-microsoft added 5 commits November 26, 2025 17:30

fix and test

07fb92f

comment

8e13f79

regen

3f11d0d

demonstrate for case without advanced-versioning

6a8d204

Revert "demonstrate for case without advanced-versioning"

2fba784

This reverts commit 6a8d204.

weidongxu-microsoft marked this pull request as ready for review November 26, 2025 10:14

weidongxu-microsoft mentioned this pull request Nov 26, 2025

eng, sync http-client-java_versioning-non-dpg Azure/autorest.java#3226

Draft

weidongxu-microsoft marked this pull request as draft November 27, 2025 01:39

weidongxu-microsoft changed the title ~~http-client-java, support advanced-versioning in non-DPG~~ http-client-java, support advanced-versioning on @added optional parameter in TypeSpec, in non-DPG Nov 27, 2025

weidongxu-microsoft added 5 commits November 27, 2025 15:15

rename to make the var easier to understand

90c1119

add overloadedClientMethod var to ClientMethod

ef26163

refine the logic

a041c47

fix

02dd013

regen

18abe5b

weidongxu-microsoft marked this pull request as ready for review November 28, 2025 01:52

comment

fbba5d9

haolingdong-msft reviewed Nov 28, 2025

View reviewed changes

	@added(Versions.v2024_10_01_preview)
	@query
	newParameter?: string;

http-client-java, support advanced-versioning on @added optional parameter in TypeSpec, in non-DPG #9087

Are you sure you want to change the base?

http-client-java, support advanced-versioning on @added optional parameter in TypeSpec, in non-DPG #9087

Uh oh!

Conversation

weidongxu-microsoft commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weidongxu-microsoft commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

haolingdong-msft Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

haolingdong-msft Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

haolingdong-msft Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

haolingdong-msft Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

haolingdong-msft Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

http-client-java, support `advanced-versioning` on `@added` optional parameter in TypeSpec, in non-DPG #9087

http-client-java, support `advanced-versioning` on `@added` optional parameter in TypeSpec, in non-DPG #9087

weidongxu-microsoft commented Nov 25, 2025 •

edited

Loading

weidongxu-microsoft commented Nov 26, 2025 •

edited

Loading