|
| 1 | +--- |
| 2 | +title: Copy a blob with Java |
| 3 | +titleSuffix: Azure Storage |
| 4 | +description: Learn how to copy a blob in Azure Storage by using the Java client library. |
| 5 | +services: storage |
| 6 | +author: pauljewellmsft |
| 7 | + |
| 8 | +ms.author: pauljewell |
| 9 | +ms.date: 11/16/2022 |
| 10 | +ms.service: storage |
| 11 | +ms.subservice: blobs |
| 12 | +ms.topic: how-to |
| 13 | +ms.devlang: java |
| 14 | +ms.custom: devx-track-java, devguide-java |
| 15 | +--- |
| 16 | + |
| 17 | +# Copy a blob using the Java client library |
| 18 | + |
| 19 | +This article demonstrates how to copy a blob in an Azure Storage account. It also shows how to abort a copy operation. The example code uses the [Azure Storage client library for Java](/java/api/overview/azure/storage-blob-readme). |
| 20 | + |
| 21 | +## About copying blobs |
| 22 | + |
| 23 | +When you copy a blob within the same storage account, it's a synchronous operation. When you copy across accounts, it's an asynchronous operation. |
| 24 | + |
| 25 | +The source blob for a copy operation may be a block blob, an append blob, a page blob, a snapshot, or a blob version. If the destination blob already exists, it must be of the same blob type as the source blob. An existing destination blob will be overwritten. |
| 26 | + |
| 27 | +The destination blob can't be modified while a copy operation is in progress. A destination blob can only have one outstanding copy operation. In other words, a blob can't be the destination for multiple pending copy operations. |
| 28 | + |
| 29 | +The entire source blob or file is always copied. Copying a range of bytes or set of blocks isn't supported. |
| 30 | + |
| 31 | +When a blob is copied, its system properties are copied to the destination blob with the same values. |
| 32 | + |
| 33 | +A copy operation can take any of the following forms: |
| 34 | + |
| 35 | +- Copy a source blob to a destination blob with a different name. The destination blob can be an existing blob of the same blob type (block, append, or page), or can be a new blob created by the copy operation. |
| 36 | +- Copy a source blob to a destination blob with the same name, effectively replacing the destination blob. Such a copy operation removes any uncommitted blocks and overwrites the destination blob's metadata. |
| 37 | +- Copy a source file in the Azure File service to a destination blob. The destination blob can be an existing block blob, or can be a new block blob created by the copy operation. Copying from files to page blobs or append blobs isn't supported. |
| 38 | +- Copy a snapshot over its base blob. By promoting a snapshot to the position of the base blob, you can restore an earlier version of a blob. |
| 39 | +- Copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot. |
| 40 | + |
| 41 | +## Copy a blob |
| 42 | + |
| 43 | +To copy a blob, use the following method: |
| 44 | + |
| 45 | +- [copyFromUrl](/java/api/com.azure.storage.blob.specialized.blobclientbase) |
| 46 | + |
| 47 | +This method synchronously copies the data at the source URL to a blob and waits for the copy to complete before returning a response. The source must be a block blob no larger than 256 MB. The source URL must include a SAS token that provides permissions to read the source blob. To learn more about the underlying operation, see [Copy Blob From URL](/rest/api/storageservices/copy-blob-from-url). |
| 48 | + |
| 49 | +The following code example gets a `BlobClient` object representing an existing blob and copies it to a new blob in a different container. This example also gets a lease on the source blob before copying so that no other client can modify the blob until the copy is complete and the lease is broken. |
| 50 | + |
| 51 | +:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/blob-devguide/blob-devguide-blobs/src/main/java/com/blobs/devguide/blobs/BlobCopy.java" id="Snippet_CopyBlobURL"::: |
| 52 | + |
| 53 | +Sample output is similar to: |
| 54 | + |
| 55 | +```console |
| 56 | +Source blob lease state: leased |
| 57 | +Copy status: success |
| 58 | +Copy progress: 5/5 |
| 59 | +Copy completion time: 2022-11-14T16:53:54Z |
| 60 | +Total bytes copied: 5 |
| 61 | +Source blob lease state: broken |
| 62 | +``` |
| 63 | + |
| 64 | +You can also copy a blob using the following method: |
| 65 | + |
| 66 | +- [beginCopy](/java/api/com.azure.storage.blob.specialized.blobclientbase) |
| 67 | + |
| 68 | +This method triggers a long-running, asynchronous operation. The source may be another blob or an Azure File resource. If the source is in another storage account, the source must either be public or authorized with a SAS token. To learn more about the underlying operation, see [Copy Blob](/rest/api/storageservices/copy-blob). |
| 69 | + |
| 70 | +:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/blob-devguide/blob-devguide-blobs/src/main/java/com/blobs/devguide/blobs/BlobCopy.java" id="Snippet_CopyBlobBeginCopy"::: |
| 71 | + |
| 72 | +You can also specify extended options for the copy operation by passing in a [BlobBeginCopyOptions](/java/api/com.azure.storage.blob.options.blobbegincopyoptions) object to the `beginCopy` method. The following example shows how to create a `BlobBeginCopyOptions` object and configure options to pass with the copy request: |
| 73 | + |
| 74 | +:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/blob-devguide/blob-devguide-blobs/src/main/java/com/blobs/devguide/blobs/BlobCopy.java" id="Snippet_CopyBlobOptions"::: |
| 75 | + |
| 76 | +## Abort a copy operation |
| 77 | + |
| 78 | +If you have a pending copy operation and need to cancel it, you can abort the operation. Aborting a copy operation results in a destination blob of zero length and full metadata. To learn more about the underlying operation, see [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob). |
| 79 | + |
| 80 | +The metadata for the destination blob will have the new values copied from the source blob or set explicitly during the copy operation. To keep the original metadata from before the copy, make a snapshot of the destination blob before calling one of the copy methods. The final blob will be committed when the copy completes. |
| 81 | + |
| 82 | +To abort a copy operation, use the following method: |
| 83 | + |
| 84 | +- [BlobClient.abortCopyFromUrl](/java/api/com.azure.storage.blob.specialized.blobclientbase) |
| 85 | + |
| 86 | +The following example stops a pending copy and leaves a destination blob with zero length and full metadata: |
| 87 | + |
| 88 | +:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/blob-devguide/blob-devguide-blobs/src/main/java/com/blobs/devguide/blobs/BlobCopy.java" id="Snippet_AbortCopy"::: |
| 89 | + |
| 90 | +## See also |
| 91 | + |
| 92 | +- [View code sample in GitHub](https://github.com/Azure-Samples/AzureStorageSnippets/blob/master/blobs/howto/Java/blob-devguide/blob-devguide-blobs/src/main/java/com/blobs/devguide/blobs/BlobCopy.java) |
| 93 | +- [Copy Blob](/rest/api/storageservices/copy-blob) (REST API) |
| 94 | +- [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob) (REST API) |
0 commit comments