From c3bdd28aefa0eea1af2dae46dc035d1365d7d565 Mon Sep 17 00:00:00 2001
From: Rick Ley <frley@microsoft.com>
Date: Fri, 2 Oct 2020 14:57:38 -0700
Subject: [PATCH] Added docs and readme samples for copy blob (#15560)

* Added docs and readme samples for copy blob

* fixed some embedme line numbers
---
 sdk/storage/azure-storage-blob/README.md      | 51 +++++++++++++------
 .../blob/specialized/BlobAsyncClientBase.java | 26 +++++++++-
 .../blob/specialized/BlobClientBase.java      | 24 +++++++++
 .../com/azure/storage/blob/ReadmeSamples.java | 11 ++++
 4 files changed, 95 insertions(+), 17 deletions(-)

diff --git a/sdk/storage/azure-storage-blob/README.md b/sdk/storage/azure-storage-blob/README.md
index d984d63e50add..f60f920535202 100644
--- a/sdk/storage/azure-storage-blob/README.md
+++ b/sdk/storage/azure-storage-blob/README.md
@@ -149,13 +149,14 @@ The following sections provide several code snippets covering some of the most c
 - [Download a blob to a stream](#download-a-blob-to-a-stream)
 - [Download a blob to local path](#download-a-blob-to-local-path)
 - [Enumerate blobs](#enumerate-blobs)
+- [Copy a blob](#copy-a-blob)
 - [Authenticate with Azure Identity](#authenticate-with-azure-identity)
 
 ### Create a `BlobServiceClient`
 
 Create a `BlobServiceClient` using the [`sasToken`](#get-credentials) generated above.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L27-L30 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L30-L33 -->
 ```java
 BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
     .endpoint("<your-storage-account-url>")
@@ -165,7 +166,7 @@ BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L34-L37 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L37-L40 -->
 ```java
 // Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
@@ -177,14 +178,14 @@ BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
 
 Create a `BlobContainerClient` using a `BlobServiceClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L41-L41 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L44-L44 -->
 ```java
 BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");
 ```
 
 Create a `BlobContainerClient` from the builder [`sasToken`](#get-credentials) generated above.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L45-L49 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L48-L52 -->
 ```java
 BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
     .endpoint("<your-storage-account-url>")
@@ -195,7 +196,7 @@ BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L53-L56 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L56-L59 -->
 ```java
 // Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
@@ -207,7 +208,7 @@ BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
 
 Create a `BlobClient` using a `BlobContainerClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L60-L60 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L63-L63 -->
 ```java
 BlobClient blobClient = blobContainerClient.getBlobClient("myblob");
 ```
@@ -216,7 +217,7 @@ or
 
 Create a `BlobClient` from the builder [`sasToken`](#get-credentials) generated above.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L64-L69 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L67-L72 -->
 ```java
 BlobClient blobClient = new BlobClientBuilder()
     .endpoint("<your-storage-account-url>")
@@ -228,7 +229,7 @@ BlobClient blobClient = new BlobClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L73-L76 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L76-L79 -->
 ```java
 // Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 BlobClient blobClient = new BlobClientBuilder()
@@ -240,7 +241,7 @@ BlobClient blobClient = new BlobClientBuilder()
 
 Create a container using a `BlobServiceClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L80-L80 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L83-L83 -->
 ```java
 blobServiceClient.createBlobContainer("mycontainer");
 ```
@@ -249,7 +250,7 @@ or
 
 Create a container using a `BlobContainerClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L84-L84 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L87-L87 -->
 ```java
 blobContainerClient.create();
 ```
@@ -258,7 +259,7 @@ blobContainerClient.create();
 
 Upload from an `InputStream` to a blob using a `BlockBlobClient` generated from a `BlobContainerClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L88-L94 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L91-L97 -->
 ```java
 BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
 String dataSample = "samples";
@@ -273,7 +274,7 @@ try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBy
 
 Upload a file to a blob using a `BlobClient` generated from a `BlobContainerClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L98-L99 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L101-L102 -->
 ```java
 BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
 blobClient.uploadFromFile("local-file.jpg");
@@ -283,7 +284,7 @@ blobClient.uploadFromFile("local-file.jpg");
 
 Download a blob to an `OutputStream` using a `BlobClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L103-L107 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L106-L110 -->
 ```java
 try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
     blobClient.download(outputStream);
@@ -296,7 +297,7 @@ try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
 
 Download blob to a local file using a `BlobClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L111-L111 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L114-L114 -->
 ```java
 blobClient.downloadToFile("downloaded-file.jpg");
 ```
@@ -305,18 +306,36 @@ blobClient.downloadToFile("downloaded-file.jpg");
 
 Enumerating all blobs using a `BlobContainerClient`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L115-L117 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L118-L120 -->
 ```java
 for (BlobItem blobItem : blobContainerClient.listBlobs()) {
     System.out.println("This is the blob name: " + blobItem.getName());
 }
 ```
 
+### Copy a blob
+
+Copying a blob. Please refer to the javadocs on each of these methods for more information around requirements on the 
+copy source and its authentication.
+
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L131-L132 -->
+```java
+SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
+poller.waitForCompletion();
+```
+
+or
+
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L136-L136 -->
+```java
+blobClient.copyFromUrl("url-to-blob");
+```
+
 ### Authenticate with Azure Identity
 
 The [Azure Identity library][identity] provides Azure Active Directory support for authenticating with Azure Storage.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L121-L124 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L124-L127 -->
 ```java
 BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
     .endpoint("<your-storage-account-url>")
diff --git a/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobAsyncClientBase.java b/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobAsyncClientBase.java
index 620b28c2843af..0733af6e2304b 100644
--- a/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobAsyncClientBase.java
+++ b/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobAsyncClientBase.java
@@ -397,6 +397,11 @@ Mono<Response<Boolean>> existsWithResponse(Context context) {
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -417,6 +422,11 @@ public PollerFlux<BlobCopyInfo, Void> beginCopy(String sourceUrl, Duration pollI
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Starting a copy operation</strong></p>
      * Starting a copy operation and polling on the responses.
@@ -451,6 +461,11 @@ public PollerFlux<BlobCopyInfo, Void> beginCopy(String sourceUrl, Map<String, St
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Starting a copy operation</strong></p>
      * Starting a copy operation and polling on the responses.
@@ -664,6 +679,9 @@ Mono<Response<Void>> abortCopyFromUrlWithResponse(String copyId, String leaseId,
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -685,6 +703,9 @@ public Mono<String> copyFromUrl(String copySource) {
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -713,7 +734,10 @@ public Mono<Response<String>> copyFromUrlWithResponse(String copySource, Map<Str
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
-     *
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
+     * 
      * <p><strong>Code Samples</strong></p>
      *
      * {@codesnippet com.azure.storage.blob.specialized.BlobAsyncClientBase.copyFromUrlWithResponse#BlobCopyFromUrlOptions}
diff --git a/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobClientBase.java b/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobClientBase.java
index a2ab5e01c6600..fb8e3a4158dae 100644
--- a/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobClientBase.java
+++ b/sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobClientBase.java
@@ -286,6 +286,11 @@ public Response<Boolean> existsWithResponse(Duration timeout, Context context) {
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -310,6 +315,11 @@ public SyncPoller<BlobCopyInfo, Void> beginCopy(String sourceUrl, Duration pollI
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -342,6 +352,11 @@ public SyncPoller<BlobCopyInfo, Void> beginCopy(String sourceUrl, Map<String, St
 
     /**
      * Copies the data at the source URL to a blob.
+     * <p>
+     * This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
+     * the source is in another account, the source must either be public or authenticated with a SAS token. If the
+     * source is in the same account, the Shared Key authorization on the destination will also be applied to the
+     * source. The source URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -398,6 +413,9 @@ public Response<Void> abortCopyFromUrlWithResponse(String copyId, String leaseId
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -416,6 +434,9 @@ public String copyFromUrl(String copySource) {
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
@@ -447,6 +468,9 @@ public Response<String> copyFromUrlWithResponse(String copySource, Map<String, S
 
     /**
      * Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
+     * <p>
+     * The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
+     * attached. The URL must be URL encoded.
      *
      * <p><strong>Code Samples</strong></p>
      *
diff --git a/sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java b/sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java
index d64cefc604759..fa21efe7eb268 100644
--- a/sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java
+++ b/sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java
@@ -2,13 +2,16 @@
 // Licensed under the MIT License.
 package com.azure.storage.blob;
 
+import com.azure.core.util.polling.SyncPoller;
 import com.azure.identity.DefaultAzureCredentialBuilder;
+import com.azure.storage.blob.models.BlobCopyInfo;
 import com.azure.storage.blob.models.BlobItem;
 import com.azure.storage.blob.specialized.BlockBlobClient;
 
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.time.Duration;
 
 /**
  * WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS
@@ -124,5 +127,13 @@ public void authWithIdentity() {
             .buildClient();
     }
 
+    public void copyBlob() {
+        SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
+        poller.waitForCompletion();
+    }
+
+    public void copyBlob2() {
+        blobClient.copyFromUrl("url-to-blob");
+    }
 }