Class BlobClient

Direct Known Subclasses:
EncryptedBlobClient

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 specied 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

  • 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, 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, 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(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(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, Context context)
      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 Response<BlockBlobItem> uploadWithResponse(BlobParallelUploadOptions options, 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
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      Information about the uploaded block blob.
    • uploadWithResponse

      public Response<BlockBlobItem> uploadWithResponse(BlobParallelUploadOptions options, Duration timeout, 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 Response<BlockBlobItem> uploadFromFileWithResponse(BlobUploadFromFileOptions options, Duration timeout, 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