[Storage] Migrate azure-storage-queue to TypeSpec by gunjansingh-msft · Pull Request #49822 · Azure/azure-sdk-for-java

gunjansingh-msft · 2026-07-15T05:47:59Z

Summary

Migrates azure-storage-queue from AutoRest/Swagger to TypeSpec codegen. The hand-written public clients (QueueClient / QueueServiceClient and async) are adapted to consume the generated protocol impl, and the generated impl reproduces AutoRest's 4-class topology (ServicesImpl / QueuesImpl / MessagesImpl / MessageIdsImpl).

Key points

Operation-group split without a TCGC patch. The duplicate-client-name error that blocked the @@clientLocation split for Java was traced to the rust/go QueueClient extends Queue client copying every Queue op; pinning those copies out of the java scope resolves it spec-only (see spec PR below). No public API change.
Per-status-code exception regression fixed — collapsed to a single QueueStorageExceptionInternal default in the customization so XML error deserialization keeps working.
Customization class suppresses the generated public clients/builder (we ship the hand-written convenience layer).

Validation (stock, unpatched TCGC 0.69 + typespec-java 0.45.4)

✅ main + test compile
✅ revapi — 0 violations (public API preserved)
✅ 323 playback tests, 0 failures (incl. QueueErrorDeserializationTests)

⚠️ Not mergeable yet — known TODOs

tsp-location.yaml pins a personal fork (gunjansingh-msft/azure-rest-api-specs). Must be re-pointed to the merged Azure/azure-rest-api-specs commit once the spec PR lands: Storage Queue (data-plane): Java client customizations for TypeSpec migration azure-rest-api-specs#44686.
Public-model javadoc drift to review before final.
Draft until the spec PR merges.

Pull request overview

Migrates azure-storage-queue from the legacy AutoRest/Swagger implementation to TypeSpec-based generation, while keeping the existing hand-written public client surface and adapting it to call into the generated protocol layer.

Changes:

Introduces TypeSpec input wiring (tsp-location.yaml) and TypeSpec metadata/property files for the module.
Refactors hand-written clients/builders to use RequestOptions + XML BinaryData bodies/responses against the generated protocol operations.
Adds a customization module to suppress generated public clients and to restore desired model/client behavior parity (fluent models, exception mapping, etc.).

Reviewed changes

Copilot reviewed 42 out of 45 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
sdk/storage/azure-storage-queue/tsp-location.yaml	Adds TypeSpec spec source location (currently fork-pinned).
sdk/storage/azure-storage-queue/src/test/java/com/azure/storage/queue/QueueTestBase.java	Normalizes URL/headers for playback matching with new protocol layer behavior.
sdk/storage/azure-storage-queue/src/main/resources/META-INF/azure-storage-queue-tsp_metadata.json	Adds TypeSpec cross-language API mapping metadata for generated protocol types.
sdk/storage/azure-storage-queue/src/main/resources/META-INF/azure-storage-queue_metadata.json	Adds updated cross-language metadata for the hand-written convenience surface.
sdk/storage/azure-storage-queue/src/main/resources/azure-storage-queue-tsp.properties	Adds TypeSpec-specific properties for metadata/versioning.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueServiceClientBuilder.java	Updates builder to construct TypeSpec-backed protocol impl.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueServiceClient.java	Refactors service client methods to use `RequestOptions` + XML `BinaryData` handling.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueServiceAsyncClient.java	Refactors async service client to new protocol layer patterns.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueClientBuilder.java	Updates queue builder to use queue-scoped base URL for protocol operations.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueClient.java	Refactors queue client methods to new `RequestOptions` + XML serialization/deserialization.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/QueueAsyncClient.java	Refactors async queue client methods to new protocol layer patterns.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/package-info.java	Updates package documentation/header to TypeSpec generation.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/UserDelegationKey.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/SendMessageResult.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueSignedIdentifier.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueServiceStatistics.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueServiceProperties.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueRetentionPolicy.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueMetrics.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueItem.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueCorsRule.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueAnalyticsLogging.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/QueueAccessPolicy.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/package-info.java	Updates models package documentation/header to TypeSpec generation.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/GeoReplicationStatus.java	Regenerates enum docs/header to TypeSpec generation.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/models/GeoReplication.java	Regenerates XML model parsing/shape for TypeSpec output.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/util/ModelHelper.java	Adds helpers for `RequestOptions`, metadata headers, XML (de)serialization, and paging conversion.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/package-info.java	Updates implementation package documentation/header to TypeSpec generation.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/SignedIdentifiers.java	Adds generated internal XML wrapper model for ACL responses.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/ReceivedMessages.java	Adds generated internal XML wrapper model for receive-messages responses.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/QueueMessageItemInternal.java	Regenerates internal received-message model to TypeSpec output (immutability/constructors).
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/QueueMessage.java	Regenerates internal message body model to TypeSpec output (immutability/constructors).
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/PeekedMessages.java	Adds generated internal XML wrapper model for peek-messages responses.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/PeekedMessageItemInternal.java	Regenerates internal peeked-message model to TypeSpec output (immutability/constructors).
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/package-info.java	Updates implementation models package documentation/header.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/ListQueuesIncludeType.java	Adds generated internal enum for list-queues include values.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/ListOfSentMessage.java	Adds generated internal XML wrapper model for send-message responses.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/models/KeyInfo.java	Regenerates key info XML model (now OffsetDateTime-based) for TypeSpec.
sdk/storage/azure-storage-queue/src/main/java/com/azure/storage/queue/implementation/AzureQueueStorageImpl.java	Updates protocol client holder to TypeSpec generation and new service-version type.
sdk/storage/azure-storage-queue/customization/src/main/java/QueueStorageCustomizations.java	Adds TypeSpec customization to suppress generated public clients and patch generated shapes/behavior.
sdk/storage/azure-storage-queue/customization/pom.xml	Adds Maven module for running codegen customizations.

+additionalDirectories:
+


+commit: e594f9e6853ec4044c9642948466d697c2fd8544
+repo: gunjansingh-msft/azure-rest-api-specs


 import com.azure.core.http.rest.PagedFlux;
 import com.azure.core.http.rest.PagedResponse;
+import com.azure.core.http.rest.RequestOptions;
 import com.azure.core.http.rest.Response;
 import com.azure.core.http.rest.SimpleResponse;


+        RequestOptions requestOptions = requestOptions(context);
+        addOptionalQueryParam(requestOptions, "prefix", prefix);
+        addOptionalQueryParam(requestOptions, "marker", marker);
+        addOptionalQueryParam(requestOptions, "maxresults", maxResults);
+        requestOptions.addQueryParam("include",
+            (include == null || include.isEmpty()) ? "" : String.join(",", include));
+        return requestOptions;


ibrandes

didn't get to a ton of files, but here's what i've found so far!

ibrandes · 2026-07-15T17:35:07Z

+    private static void restoreAccessPolicyDateTimeType(Editor editor, Logger logger) {
+        String path = "src/main/java/com/azure/storage/queue/models/QueueAccessPolicy.java";
+        String content = editor.getContents().get(path);


is there a client.tsp customization we can use instead of this? maybe

@@alternateType(AccessPolicy.start, offsetDateTime, "java"); @@alternateType(AccessPolicy.expiry, offsetDateTime, "java");

ibrandes · 2026-07-15T18:06:26Z

+    private static void preserveHandwrittenModuleInfo(Editor editor, Logger logger) {
+        String path = "src/main/java/module-info.java";
+        if (editor.getContents().containsKey(path)) {
+            editor.removeFile(path);
+            logger.info("Removed generated module-info.java to preserve the hand-written module descriptor.");
+        } else {
+            logger.info("Generated module-info.java not present; nothing to remove.");
+        }
+    }


can you add this to FILES_TO_REMOVE?

ibrandes · 2026-07-15T18:09:51Z

     */
    @Generated
-    private String start;
+    private OffsetDateTime start;


i know this model is internal so its not a breaking change - but do we still need to keep this as a string? does it being OffsetDateTime cause issues further down the stack? same question for the other internal models that have types changed

ibrandes · 2026-07-15T19:32:27Z

    public static QueueAccessPolicy fromXml(XmlReader xmlReader, String rootElementName) throws XMLStreamException {
        String finalRootElementName
-            = rootElementName == null || rootElementName.isEmpty() ? "QueueAccessPolicy" : rootElementName;
+            = rootElementName == null || rootElementName.isEmpty() ? "AccessPolicy" : rootElementName;


should this be QueueAccessPolicy? my same question applies to all the other classes that have the name of the xml root element changed

Local Merge added 2 commits July 8, 2026 15:39

typespec migration

14f497f

typespec migration

928e6f3

github-actions Bot added the Storage Storage Service (Queues, Blobs, Files) label Jul 15, 2026

Local Merge added 2 commits July 15, 2026 17:50

remove customization comments

83a1388

remove client comments

54c4a43

gunjansingh-msft marked this pull request as ready for review July 15, 2026 12:44

Copilot AI review requested due to automatic review settings July 15, 2026 12:44

gunjansingh-msft requested review from a team, alzimmermsft, browndav-msft, ibrandes, kyleknap and seanmcc-msft as code owners July 15, 2026 12:44

Copilot started reviewing on behalf of gunjansingh-msft July 15, 2026 12:45 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

ibrandes reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Storage] Migrate azure-storage-queue to TypeSpec#49822

[Storage] Migrate azure-storage-queue to TypeSpec#49822
gunjansingh-msft wants to merge 4 commits into
mainfrom
feature/storage/typespec

gunjansingh-msft commented Jul 15, 2026 •

edited

Loading

Uh oh!

azure-pipelines Bot commented Jul 15, 2026

Uh oh!

azure-pipelines Bot commented Jul 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

ibrandes left a comment

Uh oh!

ibrandes Jul 15, 2026

Uh oh!

ibrandes Jul 15, 2026

Uh oh!

ibrandes Jul 15, 2026 •

edited

Loading

Uh oh!

ibrandes Jul 15, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		commit: e594f9e6853ec4044c9642948466d697c2fd8544
		repo: gunjansingh-msft/azure-rest-api-specs

		additionalDirectories:

Uh oh!

Conversation

gunjansingh-msft commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key points

Validation (stock, unpatched TCGC 0.69 + typespec-java 0.45.4)

⚠️ Not mergeable yet — known TODOs

Related

Uh oh!

azure-pipelines Bot commented Jul 15, 2026

Uh oh!

azure-pipelines Bot commented Jul 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

ibrandes left a comment

Choose a reason for hiding this comment

Uh oh!

ibrandes Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

ibrandes Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

ibrandes Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibrandes Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gunjansingh-msft commented Jul 15, 2026 •

edited

Loading

ibrandes Jul 15, 2026 •

edited

Loading

ibrandes Jul 15, 2026 •

edited

Loading