Added code for get file range diff (#14140)

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/ShareFileAsyncClient.java

@@ -58,6 +58,7 @@
 import com.azure.storage.file.share.models.ShareFileUploadRangeFromUrlInfo;
 import com.azure.storage.file.share.models.ShareRequestConditions;
 import com.azure.storage.file.share.models.ShareStorageException;
+import com.azure.storage.file.share.options.ShareFileListRangeOptions;
 import com.azure.storage.file.share.sas.ShareServiceSasSignatureValues;
 import reactor.core.Exceptions;
 import reactor.core.publisher.Flux;
@@ -1570,7 +1571,7 @@ private List<ShareFileRange> sliceFile(String path) {
      */
     public PagedFlux<ShareFileRange> listRanges() {
         try {
-            return listRanges(null);
+            return listRanges((ShareFileRange) null);
         } catch (RuntimeException ex) {
             return pagedFluxError(logger, ex);
         }
@@ -1613,21 +1614,47 @@ public PagedFlux<ShareFileRange> listRanges(ShareFileRange range) {
      */
     public PagedFlux<ShareFileRange> listRanges(ShareFileRange range, ShareRequestConditions requestConditions) {
         try {
-            return listRangesWithOptionalTimeout(range, requestConditions, null, Context.NONE);
+            return listRangesWithOptionalTimeout(new ShareFileListRangeOptions().setRange(range)
+                .setRequestConditions(requestConditions), null, Context.NONE);
         } catch (RuntimeException ex) {
             return pagedFluxError(logger, ex);
         }
     }
 
-    PagedFlux<ShareFileRange> listRangesWithOptionalTimeout(ShareFileRange range,
-        ShareRequestConditions requestConditions, Duration timeout, Context context) {
-        ShareRequestConditions finalRequestConditions = requestConditions == null
-            ? new ShareRequestConditions() : requestConditions;
-        String rangeString = range == null ? null : range.toString();
+    /**
+     * List of valid ranges for a file.
+     *
+     * <p><strong>Code Samples</strong></p>
+     *
+     * <p>List all ranges within the file range from 1KB to 2KB.</p>
+     *
+     * {@codesnippet com.azure.storage.file.share.ShareFileAsyncClient.listRanges#ShareFileListRangeOptions}
+     *
+     * <p>For more information, see the
+     * <a href="https://docs.microsoft.com/en-us/rest/api/storageservices/list-ranges">Azure Docs</a>.</p>
+     *
+     * @param options {@link ShareFileListRangeOptions}.
+     * @return {@link ShareFileRange ranges} in the files that satisfy the requirements
+     */
+    public PagedFlux<ShareFileRange> listRanges(ShareFileListRangeOptions options) {
+        try {
+            return listRangesWithOptionalTimeout(options, null, Context.NONE);
+        } catch (RuntimeException ex) {
+            return pagedFluxError(logger, ex);
+        }
+    }
+
+    PagedFlux<ShareFileRange> listRangesWithOptionalTimeout(ShareFileListRangeOptions options, Duration timeout,
+        Context context) {
+        ShareFileListRangeOptions finalOptions = options == null ? new ShareFileListRangeOptions() : options;
+
+        ShareRequestConditions finalRequestConditions = finalOptions.getRequestConditions() == null
+            ? new ShareRequestConditions() : finalOptions.getRequestConditions();
+        String rangeString = finalOptions.getRange() == null ? null : finalOptions.getRange().toString();
         Function<String, Mono<PagedResponse<ShareFileRange>>> retriever =
             marker -> StorageImplUtils.applyOptionalTimeout(this.azureFileStorageClient.files()
-                .getRangeListWithRestResponseAsync(shareName, filePath, snapshot, null, rangeString,
-                    finalRequestConditions.getLeaseId(), context), timeout)
+                .getRangeListWithRestResponseAsync(shareName, filePath, snapshot, finalOptions.getPreviousSnapshot(),
+                    null, rangeString, finalRequestConditions.getLeaseId(), context), timeout)
                 .map(response -> new PagedResponseBase<>(response.getRequest(),
                     response.getStatusCode(),
                     response.getHeaders(),

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/ShareFileClient.java

@@ -28,6 +28,7 @@
 import com.azure.storage.file.share.models.ShareFileUploadInfo;
 import com.azure.storage.file.share.models.ShareFileUploadRangeFromUrlInfo;
 import com.azure.storage.file.share.models.HandleItem;
+import com.azure.storage.file.share.options.ShareFileListRangeOptions;
 import com.azure.storage.file.share.sas.ShareServiceSasSignatureValues;
 import reactor.core.Exceptions;
 import reactor.core.publisher.Mono;
@@ -1194,7 +1195,7 @@ public void uploadFromFile(String uploadFilePath, ShareRequestConditions request
      * @return {@link ShareFileRange ranges} in the files.
      */
     public PagedIterable<ShareFileRange> listRanges() {
-        return listRanges(null, null, null);
+        return listRanges((ShareFileRange) null, null, null);
     }
 
     /**
@@ -1242,7 +1243,33 @@ public PagedIterable<ShareFileRange> listRanges(ShareFileRange range, Duration t
      */
     public PagedIterable<ShareFileRange> listRanges(ShareFileRange range, ShareRequestConditions requestConditions,
         Duration timeout, Context context) {
-        return new PagedIterable<>(shareFileAsyncClient.listRangesWithOptionalTimeout(range, requestConditions, timeout,
+        return new PagedIterable<>(shareFileAsyncClient.listRangesWithOptionalTimeout(new ShareFileListRangeOptions()
+            .setRange(range).setRequestConditions(requestConditions), timeout,
+            context));
+    }
+
+    /**
+     * List of valid ranges for a file.
+     *
+     * <p><strong>Code Samples</strong></p>
+     *
+     * <p>List all ranges within the file range from 1KB to 2KB.</p>
+     *
+     * {@codesnippet com.azure.storage.file.share.ShareFileClient.listRanges#ShareFileListRangeOptions-Duration-Context}
+     *
+     * <p>For more information, see the
+     * <a href="https://docs.microsoft.com/en-us/rest/api/storageservices/list-ranges">Azure Docs</a>.</p>
+     *
+     * @param options {@link ShareFileListRangeOptions}
+     * @param timeout An optional timeout applied to the operation. If a response is not returned before the timeout
+     * concludes a {@link RuntimeException} will be thrown.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return {@link ShareFileRange ranges} in the files that satisfy the requirements
+     * @throws RuntimeException if the operation doesn't complete before the timeout concludes.
+     */
+    public PagedIterable<ShareFileRange> listRanges(ShareFileListRangeOptions options, Duration timeout,
+        Context context) {
+        return new PagedIterable<>(shareFileAsyncClient.listRangesWithOptionalTimeout(options, timeout,
             context));
     }
 

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/implementation/DirectorysImpl.java

@@ -381,7 +381,7 @@ public Mono<DirectorysListHandlesResponse> listHandlesWithRestResponseAsync(Stri
      *
      * @param shareName The name of the target share.
      * @param directoryPath The path of the target directory.
-     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterix (‘*’) is a wildcard that specifies all handles.
+     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterisk (‘*’) is a wildcard that specifies all handles.
      * @param context The context to associate with this operation.
      * @throws IllegalArgumentException thrown if parameters fail the validation.
      * @return a Mono which performs the network request upon subscription.
@@ -401,7 +401,7 @@ public Mono<DirectorysForceCloseHandlesResponse> forceCloseHandlesWithRestRespon
      *
      * @param shareName The name of the target share.
      * @param directoryPath The path of the target directory.
-     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterix (‘*’) is a wildcard that specifies all handles.
+     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterisk (‘*’) is a wildcard that specifies all handles.
      * @param timeout The timeout parameter is expressed in seconds. For more information, see &lt;a href="https://docs.microsoft.com/en-us/rest/api/storageservices/Setting-Timeouts-for-File-Service-Operations?redirectedfrom=MSDN"&gt;Setting Timeouts for File Service Operations.&lt;/a&gt;.
      * @param marker A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items. The marker value is opaque to the client.
      * @param sharesnapshot The snapshot parameter is an opaque DateTime value that, when present, specifies the share snapshot to query.

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/implementation/FilesImpl.java

@@ -124,7 +124,7 @@ private interface FilesService {
         @Get("{shareName}/{filePath}")
         @ExpectedResponses({200})
         @UnexpectedResponseExceptionType(ShareStorageException.class)
-        Mono<FilesGetRangeListResponse> getRangeList(@PathParam("shareName") String shareName, @PathParam("filePath") String filePath, @HostParam("url") String url, @QueryParam("sharesnapshot") String sharesnapshot, @QueryParam("timeout") Integer timeout, @HeaderParam("x-ms-version") String version, @HeaderParam("x-ms-range") String range, @HeaderParam("x-ms-lease-id") String leaseId, @QueryParam("comp") String comp, Context context);
+        Mono<FilesGetRangeListResponse> getRangeList(@PathParam("shareName") String shareName, @PathParam("filePath") String filePath, @HostParam("url") String url, @QueryParam("sharesnapshot") String sharesnapshot, @QueryParam("prevsharesnapshot") String prevsharesnapshot, @QueryParam("timeout") Integer timeout, @HeaderParam("x-ms-version") String version, @HeaderParam("x-ms-range") String range, @HeaderParam("x-ms-lease-id") String leaseId, @QueryParam("comp") String comp, Context context);
 
         @Put("{shareName}/{filePath}")
         @ExpectedResponses({202})
@@ -580,11 +580,12 @@ public Mono<FilesUploadRangeFromURLResponse> uploadRangeFromURLWithRestResponseA
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<FilesGetRangeListResponse> getRangeListWithRestResponseAsync(String shareName, String filePath, Context context) {
         final String sharesnapshot = null;
+        final String prevsharesnapshot = null;
         final Integer timeout = null;
         final String range = null;
         final String leaseId = null;
         final String comp = "rangelist";
-        return service.getRangeList(shareName, filePath, this.client.getUrl(), sharesnapshot, timeout, this.client.getVersion(), range, leaseId, comp, context);
+        return service.getRangeList(shareName, filePath, this.client.getUrl(), sharesnapshot, prevsharesnapshot, timeout, this.client.getVersion(), range, leaseId, comp, context);
     }
 
     /**
@@ -593,6 +594,7 @@ public Mono<FilesGetRangeListResponse> getRangeListWithRestResponseAsync(String
      * @param shareName The name of the target share.
      * @param filePath The path of the target file.
      * @param sharesnapshot The snapshot parameter is an opaque DateTime value that, when present, specifies the share snapshot to query.
+     * @param prevsharesnapshot The previous snapshot parameter is an opaque DateTime value that, when present, specifies the previous snapshot.
      * @param timeout The timeout parameter is expressed in seconds. For more information, see &lt;a href="https://docs.microsoft.com/en-us/rest/api/storageservices/Setting-Timeouts-for-File-Service-Operations?redirectedfrom=MSDN"&gt;Setting Timeouts for File Service Operations.&lt;/a&gt;.
      * @param range Specifies the range of bytes over which to list ranges, inclusively.
      * @param leaseId If specified, the operation only succeeds if the resource's lease is active and matches this ID.
@@ -601,9 +603,9 @@ public Mono<FilesGetRangeListResponse> getRangeListWithRestResponseAsync(String
      * @return a Mono which performs the network request upon subscription.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
-    public Mono<FilesGetRangeListResponse> getRangeListWithRestResponseAsync(String shareName, String filePath, String sharesnapshot, Integer timeout, String range, String leaseId, Context context) {
+    public Mono<FilesGetRangeListResponse> getRangeListWithRestResponseAsync(String shareName, String filePath, String sharesnapshot, String prevsharesnapshot, Integer timeout, String range, String leaseId, Context context) {
         final String comp = "rangelist";
-        return service.getRangeList(shareName, filePath, this.client.getUrl(), sharesnapshot, timeout, this.client.getVersion(), range, leaseId, comp, context);
+        return service.getRangeList(shareName, filePath, this.client.getUrl(), sharesnapshot, prevsharesnapshot, timeout, this.client.getVersion(), range, leaseId, comp, context);
     }
 
     /**
@@ -758,7 +760,7 @@ public Mono<FilesListHandlesResponse> listHandlesWithRestResponseAsync(String sh
      *
      * @param shareName The name of the target share.
      * @param filePath The path of the target file.
-     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterix (‘*’) is a wildcard that specifies all handles.
+     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterisk (‘*’) is a wildcard that specifies all handles.
      * @param context The context to associate with this operation.
      * @throws IllegalArgumentException thrown if parameters fail the validation.
      * @return a Mono which performs the network request upon subscription.
@@ -777,7 +779,7 @@ public Mono<FilesForceCloseHandlesResponse> forceCloseHandlesWithRestResponseAsy
      *
      * @param shareName The name of the target share.
      * @param filePath The path of the target file.
-     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterix (‘*’) is a wildcard that specifies all handles.
+     * @param handleId Specifies handle ID opened on the file or directory to be closed. Asterisk (‘*’) is a wildcard that specifies all handles.
      * @param timeout The timeout parameter is expressed in seconds. For more information, see &lt;a href="https://docs.microsoft.com/en-us/rest/api/storageservices/Setting-Timeouts-for-File-Service-Operations?redirectedfrom=MSDN"&gt;Setting Timeouts for File Service Operations.&lt;/a&gt;.
      * @param marker A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items. The marker value is opaque to the client.
      * @param sharesnapshot The snapshot parameter is an opaque DateTime value that, when present, specifies the share snapshot to query.

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/options/ShareFileListRangeOptions.java

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.storage.file.share.options;
+
+import com.azure.core.annotation.Fluent;
+import com.azure.storage.file.share.models.ShareFileRange;
+import com.azure.storage.file.share.models.ShareRequestConditions;
+
+/**
+ * Extended options that may be passed when listing ranges for a File.
+ */
+@Fluent
+public class ShareFileListRangeOptions {
+
+    private ShareFileRange range;
+    private String previousSnapshot;
+    private ShareRequestConditions requestConditions;
+
+    /**
+     * @return The range of bytes over which to list ranges, inclusively.
+     */
+    public ShareFileRange getRange() {
+        return range;
+    }
+
+    /**
+     * @param range The range of bytes over which to list ranges, inclusively.
+     * @return The updated options.
+     */
+    public ShareFileListRangeOptions setRange(ShareFileRange range) {
+        this.range = range;
+        return this;
+    }
+
+    /**
+     * @return The previous snapshot to compare to.
+     */
+    public String getPreviousSnapshot() {
+        return previousSnapshot;
+    }
+
+    /**
+     * @param previousSnapshot Specifies that the response will contain only ranges that were changed between target
+     * file and previous snapshot. Changed ranges include both updated and cleared ranges. The target file may be a
+     * snapshot, as long as the snapshot specified by previousSnapshot is the older of the two.
+     * @return The updated options.
+     */
+    public ShareFileListRangeOptions setPreviousSnapshot(String previousSnapshot) {
+        this.previousSnapshot = previousSnapshot;
+        return this;
+    }
+
+    /**
+     * @return {@link ShareRequestConditions}
+     */
+    public ShareRequestConditions getRequestConditions() {
+        return requestConditions;
+    }
+
+    /**
+     * @param requestConditions {@link ShareRequestConditions} for the file.
+     * @return The updated options.
+     */
+    public ShareFileListRangeOptions setRequestConditions(ShareRequestConditions requestConditions) {
+        this.requestConditions = requestConditions;
+        return this;
+    }
+}

sdk/storage/azure-storage-file-share/src/main/java/com/azure/storage/file/share/options/package-info.java

@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Package containing options model classes used by Azure Storage File Shares.
+ */
+package com.azure.storage.file.share.options;

sdk/storage/azure-storage-file-share/src/main/java/module-info.java

@@ -8,6 +8,7 @@
 
     exports com.azure.storage.file.share;
     exports com.azure.storage.file.share.models;
+    exports com.azure.storage.file.share.options;
     exports com.azure.storage.file.share.sas;
     exports com.azure.storage.file.share.specialized;
 

sdk/storage/azure-storage-file-share/src/samples/java/com/azure/storage/file/share/ShareFileAsyncJavaDocCodeSamples.java

@@ -11,6 +11,7 @@
 import com.azure.storage.file.share.models.ShareFileRange;
 import com.azure.storage.file.share.models.NtfsFileAttributes;
 import com.azure.storage.file.share.models.ShareRequestConditions;
+import com.azure.storage.file.share.options.ShareFileListRangeOptions;
 import com.azure.storage.file.share.sas.ShareFileSasPermission;
 import com.azure.storage.file.share.sas.ShareServiceSasSignatureValues;
 import reactor.core.publisher.Flux;
@@ -823,6 +824,18 @@ public void listRangesAsyncMaxOverload() {
         // END: com.azure.storage.file.share.ShareFileAsyncClient.listRanges#ShareFileRange
     }
 
+    /**
+     * Generates a code sample for using {@link ShareFileAsyncClient#listRanges(ShareFileListRangeOptions)}
+     */
+    public void listRangesAsyncOptionalOverload() {
+        ShareFileAsyncClient shareFileAsyncClient = createAsyncClientWithSASToken();
+        // BEGIN: com.azure.storage.file.share.ShareFileAsyncClient.listRanges#ShareFileListRangeOptions
+        shareFileAsyncClient.listRanges(new ShareFileListRangeOptions().setRange(new ShareFileRange(1024, 2048L)))
+            .subscribe(result -> System.out.printf("List ranges completed with start: %d, end: %d",
+                result.getStart(), result.getEnd()));
+        // END: com.azure.storage.file.share.ShareFileAsyncClient.listRanges#ShareFileListRangeOptions
+    }
+
     /**
      * Generates a code sample for using {@link ShareFileAsyncClient#listRanges(ShareFileRange, ShareRequestConditions)}
      */