Package com.azure.storage.blob

Class BlobClient

java.lang.Object
com.azure.storage.blob.specialized.BlobClientBase
com.azure.storage.blob.BlobClient
public class BlobClient extends BlobClientBase
This class provides a client that contains generic blob operations for Azure Storage Blobs. Operations allowed by the client are uploading and downloading, copying a blob, retrieving and setting metadata, retrieving and setting HTTP headers, and deleting and un-deleting a blob.

This client is instantiated through BlobClientBuilder or retrieved via getBlobClient.

For operations on a specific blob type (i.e append, block, or page) use getAppendBlobClient, getBlockBlobClient, or getPageBlobClient to construct a client that allows blob specific operations.

Please refer to the Azure Docs for more information.

  • Field Details

    • BLOB_DEFAULT_UPLOAD_BLOCK_SIZE

      public static final int BLOB_DEFAULT_UPLOAD_BLOCK_SIZE
      The block size to use if none is specified in parallel operations.
      See Also:

    • BLOB_DEFAULT_NUMBER_OF_BUFFERS

      public static final int BLOB_DEFAULT_NUMBER_OF_BUFFERS
      The number of buffers to use if none is specified on the buffered upload method.
      See Also:

    • BLOB_DEFAULT_HTBB_UPLOAD_BLOCK_SIZE

      public static final int BLOB_DEFAULT_HTBB_UPLOAD_BLOCK_SIZE
      If a blob is known to be greater than 100MB, using a larger block size will trigger some server-side optimizations. If the block size is not set and the size of the blob is known to be greater than 100MB, this value will be used.
      See Also:

  • Constructor Details

    • BlobClient

      protected BlobClient(BlobAsyncClient client)
      Protected constructor for use by BlobClientBuilder.
      Parameters:
      client - the async blob client

    • BlobClient

      protected BlobClient(BlobAsyncClient client, com.azure.core.http.HttpPipeline pipeline, String url, BlobServiceVersion serviceVersion, String accountName, String containerName, String blobName, String snapshot, CpkInfo customerProvidedKey, com.azure.storage.blob.implementation.models.EncryptionScope encryptionScope, String versionId)
      Protected constructor for use by BlobClientBuilder.
      Parameters:
      client - the async blob client
      pipeline - The pipeline used to send and receive service requests.
      url - The endpoint where to send service requests.
      serviceVersion - The version of the service to receive requests.
      accountName - The storage account name.
      containerName - The container name.
      blobName - The blob name.
      snapshot - The snapshot identifier for the blob, pass null to interact with the blob directly.
      customerProvidedKey - Customer provided key used during encryption of the blob's data on the server, pass null to allow the service to use its own encryption.
      encryptionScope - Encryption scope used during encryption of the blob's data on the server, pass null to allow the service to use its own encryption.
      versionId - The version identifier for the blob, pass null to interact with the latest blob version.

  • Method Details

    • getSnapshotClient

      public BlobClient getSnapshotClient(String snapshot)
      Creates a new BlobClient linked to the snapshot of this blob resource.
      Overrides:
      getSnapshotClient in class BlobClientBase
      Parameters:
      snapshot - the identifier for a specific snapshot of this blob
      Returns:
      A BlobClient used to interact with the specific snapshot.

    • getVersionClient

      public BlobClient getVersionClient(String versionId)
      Creates a new BlobClient linked to the version of this blob resource.
      Overrides:
      getVersionClient in class BlobClientBase
      Parameters:
      versionId - the identifier for a specific version of this blob, pass null to interact with the latest blob version.
      Returns:
      A BlobClient used to interact with the specific version.

    • getEncryptionScopeClient

      public BlobClient getEncryptionScopeClient(String encryptionScope)
      Creates a new BlobClient with the specified encryptionScope.
      Overrides:
      getEncryptionScopeClient in class BlobClientBase
      Parameters:
      encryptionScope - the encryption scope for the blob, pass null to use no encryption scope.
      Returns:
      a BlobClient with the specified encryptionScope.

    • getCustomerProvidedKeyClient

      public BlobClient getCustomerProvidedKeyClient(CustomerProvidedKey customerProvidedKey)
      Creates a new BlobClient with the specified customerProvidedKey.
      Overrides:
      getCustomerProvidedKeyClient in class BlobClientBase
      Parameters:
      customerProvidedKey - the CustomerProvidedKey for the blob, pass null to use no customer provided key.
      Returns:
      a BlobClient with the specified customerProvidedKey.

    • getAppendBlobClient

      public AppendBlobClient getAppendBlobClient()
      Creates a new AppendBlobClient associated with this blob.
      Returns:
      A AppendBlobClient associated with this blob.

    • getBlockBlobClient

      public BlockBlobClient getBlockBlobClient()
      Creates a new BlockBlobClient associated with this blob.
      Returns:
      A BlockBlobClient associated with this blob.

    • getPageBlobClient

      public PageBlobClient getPageBlobClient()
      Creates a new PageBlobClient associated with this blob.
      Returns:
      A PageBlobClient associated with this blob.

    • upload

      public void upload(InputStream data)
      Creates a new blob. By default this method will not overwrite an existing blob.
      Parameters:
      data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider opening a BlobOutputStream and writing to the returned stream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.

    • upload

      public void upload(InputStream data, long length)
      Creates a new blob. By default this method will not overwrite an existing blob.
      Parameters:
      data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider opening a BlobOutputStream and writing to the returned stream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.
      length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.

    • upload

      public void upload(InputStream data, boolean overwrite)
      Creates a new blob, or updates the content of an existing blob.
      Parameters:
      data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider opening a BlobOutputStream and writing to the returned stream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.
      overwrite - Whether or not to overwrite, should data exist on the blob.

    • upload

      public void upload(InputStream data, long length, boolean overwrite)
      Creates a new blob, or updates the content of an existing blob.
      Parameters:
      data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider opening a BlobOutputStream and writing to the returned stream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.
      length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.
      overwrite - Whether or not to overwrite, should data exist on the blob.

    • upload

      public void upload(com.azure.core.util.BinaryData data)
      Creates a new blob. By default this method will not overwrite an existing blob.
      Parameters:
      data - The data to write to the blob.

    • upload

      public void upload(com.azure.core.util.BinaryData data, boolean overwrite)
      Creates a new blob, or updates the content of an existing blob.
      Parameters:
      data - The data to write to the blob.
      overwrite - Whether or not to overwrite, should data exist on the blob.

    • uploadWithResponse

      @Deprecated public void uploadWithResponse(InputStream data, long length, ParallelTransferOptions parallelTransferOptions, BlobHttpHeaders headers, Map<String,String> metadata, AccessTier tier, BlobRequestConditions requestConditions, Duration timeout, com.azure.core.util.Context context)
      Deprecated.
      See uploadWithResponse(BlobParallelUploadOptions, Duration, Context) instead
      Creates a new blob, or updates the content of an existing blob.

      To avoid overwriting, pass "*" to BlobRequestConditions.setIfNoneMatch(String).

      Parameters:
      data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider opening a BlobOutputStream and writing to the returned stream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.
      length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.
      parallelTransferOptions - ParallelTransferOptions used to configure buffered uploading.
      headers - BlobHttpHeaders
      metadata - Metadata to associate with the blob. If there is leading or trailing whitespace in any metadata key or value, it must be removed or encoded.
      tier - AccessTier for the destination blob.
      requestConditions - BlobRequestConditions
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.

    • uploadWithResponse

      @Deprecated public com.azure.core.http.rest.Response<BlockBlobItem> uploadWithResponse(BlobParallelUploadOptions options, com.azure.core.util.Context context)
      Deprecated.
      Use uploadWithResponse(BlobParallelUploadOptions, Duration, Context)
      Creates a new blob, or updates the content of an existing blob.

      To avoid overwriting, pass "*" to BlobRequestConditions.setIfNoneMatch(String).

      Parameters:
      options - BlobParallelUploadOptions
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      Information about the uploaded block blob.

    • uploadWithResponse

      public com.azure.core.http.rest.Response<BlockBlobItem> uploadWithResponse(BlobParallelUploadOptions options, Duration timeout, com.azure.core.util.Context context)
      Creates a new blob, or updates the content of an existing blob.

      To avoid overwriting, pass "*" to BlobRequestConditions.setIfNoneMatch(String).

      Parameters:
      options - BlobParallelUploadOptions
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      Information about the uploaded block blob.

    • uploadFromFile

      public void uploadFromFile(String filePath)
      Creates a new block blob. By default this method will not overwrite an existing blob.

      Code Samples

       try {
     client.uploadFromFile(filePath);
     System.out.println("Upload from file succeeded");
 } catch (UncheckedIOException ex) {
     System.err.printf("Failed to upload from file %s%n", ex.getMessage());
 }
      Parameters:
      filePath - Path of the file to upload
      Throws:
      UncheckedIOException - If an I/O error occurs

    • uploadFromFile

      public void uploadFromFile(String filePath, boolean overwrite)
      Creates a new block blob, or updates the content of an existing block blob.

      Code Samples

       try {
     boolean overwrite = false;
     client.uploadFromFile(filePath, overwrite);
     System.out.println("Upload from file succeeded");
 } catch (UncheckedIOException ex) {
     System.err.printf("Failed to upload from file %s%n", ex.getMessage());
 }
      Parameters:
      filePath - Path of the file to upload
      overwrite - Whether or not to overwrite, should the blob already exist
      Throws:
      UncheckedIOException - If an I/O error occurs

    • uploadFromFile

      public void uploadFromFile(String filePath, ParallelTransferOptions parallelTransferOptions, BlobHttpHeaders headers, Map<String,String> metadata, AccessTier tier, BlobRequestConditions requestConditions, Duration timeout)
      Creates a new block blob, or updates the content of an existing block blob.

      To avoid overwriting, pass "*" to BlobRequestConditions.setIfNoneMatch(String).

      Code Samples

       BlobHttpHeaders headers = new BlobHttpHeaders()
     .setContentMd5("data".getBytes(StandardCharsets.UTF_8))
     .setContentLanguage("en-US")
     .setContentType("binary");

 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 BlobRequestConditions requestConditions = new BlobRequestConditions()
     .setLeaseId(leaseId)
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
 Long blockSize = 100L * 1024L * 1024L; // 100 MB;
 ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions().setBlockSizeLong(blockSize);

 try {
     client.uploadFromFile(filePath, parallelTransferOptions, headers, metadata,
         AccessTier.HOT, requestConditions, timeout);
     System.out.println("Upload from file succeeded");
 } catch (UncheckedIOException ex) {
     System.err.printf("Failed to upload from file %s%n", ex.getMessage());
 }
      Parameters:
      filePath - Path of the file to upload
      parallelTransferOptions - ParallelTransferOptions to use to upload from file. Number of parallel transfers parameter is ignored.
      headers - BlobHttpHeaders
      metadata - Metadata to associate with the blob. If there is leading or trailing whitespace in any metadata key or value, it must be removed or encoded.
      tier - AccessTier for the uploaded blob
      requestConditions - BlobRequestConditions
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      Throws:
      UncheckedIOException - If an I/O error occurs

    • uploadFromFileWithResponse

      public com.azure.core.http.rest.Response<BlockBlobItem> uploadFromFileWithResponse(BlobUploadFromFileOptions options, Duration timeout, com.azure.core.util.Context context)
      Creates a new block blob, or updates the content of an existing block blob.

      To avoid overwriting, pass "*" to BlobRequestConditions.setIfNoneMatch(String).

      Code Samples

       BlobHttpHeaders headers = new BlobHttpHeaders()
     .setContentMd5("data".getBytes(StandardCharsets.UTF_8))
     .setContentLanguage("en-US")
     .setContentType("binary");

 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Map<String, String> tags = Collections.singletonMap("tag", "value");
 BlobRequestConditions requestConditions = new BlobRequestConditions()
     .setLeaseId(leaseId)
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
 Long blockSize = 100 * 1024 * 1024L; // 100 MB;
 ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions().setBlockSizeLong(blockSize);

 try {
     client.uploadFromFileWithResponse(new BlobUploadFromFileOptions(filePath)
         .setParallelTransferOptions(parallelTransferOptions).setHeaders(headers).setMetadata(metadata)
         .setTags(tags).setTier(AccessTier.HOT).setRequestConditions(requestConditions), timeout,
         new Context(key2, value2));
     System.out.println("Upload from file succeeded");
 } catch (UncheckedIOException ex) {
     System.err.printf("Failed to upload from file %s%n", ex.getMessage());
 }
      Parameters:
      options - BlobUploadFromFileOptions
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      Information about the uploaded block blob.
      Throws:
      UncheckedIOException - If an I/O error occurs