com.google.cloud.storage

Class Blob

java.lang.Object

com.google.cloud.storage.BlobInfo

com.google.cloud.storage.Blob

All Implemented Interfaces:

Serializable

public class Blob
extends BlobInfo

A Google cloud storage object.

Objects of this class are immutable. Operations that modify the blob like update(com.google.cloud.storage.Storage.BlobTargetOption...) and copyTo(com.google.cloud.storage.BlobId, com.google.cloud.storage.Blob.BlobSourceOption...) return a new object. To get a Blob object with the most recent information use reload(com.google.cloud.storage.Blob.BlobSourceOption...). Blob adds a layer of service-related functionality over BlobInfo.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Blob.BlobSourceOption Class for specifying blob source options when Blob methods are used.
static class	Blob.Builder Builder for Blob.

Nested classes/interfaces inherited from class com.google.cloud.storage.BlobInfo

BlobInfo.CustomerEncryption, BlobInfo.ImmutableEmptyMap<K,V>

Method Summary

Modifier and Type	Method and Description
CopyWriter	copyTo(BlobId targetBlob, Blob.BlobSourceOption... options) Sends a copy request for the current blob to the target blob.
CopyWriter	copyTo(String targetBucket, Blob.BlobSourceOption... options) Sends a copy request for the current blob to the target bucket, preserving its name.
CopyWriter	copyTo(String targetBucket, String targetBlob, Blob.BlobSourceOption... options) Sends a copy request for the current blob to the target blob.
Acl	createAcl(Acl acl) Creates a new ACL entry on this blob.
boolean	delete(Blob.BlobSourceOption... options) Deletes this blob.
boolean	deleteAcl(Acl.Entity entity) Deletes the ACL entry for the specified entity on this blob.
void	downloadTo(OutputStream outputStream, Blob.BlobSourceOption... options) Downloads this blob to the given output stream using specified blob read options.
void	downloadTo(Path path) Downloads this blob to the given file path.
void	downloadTo(Path path, Blob.BlobSourceOption... options) Downloads this blob to the given file path using specified blob read options.
boolean	equals(Object obj)
boolean	exists(Blob.BlobSourceOption... options) Checks if this blob exists.
Acl	getAcl(Acl.Entity entity) Returns the ACL entry for the specified entity on this blob or null if not found.
byte[]	getContent(Blob.BlobSourceOption... options) Returns this blob's content.
Storage	getStorage() Returns the blob's Storage object used to issue requests.
int	hashCode()
List<Acl>	listAcls() Lists the ACL entries for this blob.
com.google.cloud.ReadChannel	reader(Blob.BlobSourceOption... options) Returns a ReadChannel object for reading this blob's content.
Blob	reload(Blob.BlobSourceOption... options) Fetches current blob's latest information.
URL	signUrl(long duration, TimeUnit unit, Storage.SignUrlOption... options) Generates a signed URL for this blob.
Blob.Builder	toBuilder() Returns a builder for the current blob.
Blob	update(Storage.BlobTargetOption... options) Updates the blob's information.
Acl	updateAcl(Acl acl) Updates an ACL entry on this blob.
com.google.cloud.WriteChannel	writer(Storage.BlobWriteOption... options) Returns a WriteChannel object for writing to this blob.

Methods inherited from class com.google.cloud.storage.BlobInfo

getAcl, getBlobId, getBucket, getCacheControl, getComponentCount, getContentDisposition, getContentEncoding, getContentLanguage, getContentType, getCrc32c, getCrc32cToHexString, getCreateTime, getCustomerEncryption, getDeleteTime, getEtag, getEventBasedHold, getGeneratedId, getGeneration, getKmsKeyName, getMd5, getMd5ToHexString, getMediaLink, getMetadata, getMetageneration, getName, getOwner, getRetentionExpirationTime, getSelfLink, getSize, getStorageClass, getTemporaryHold, getUpdateTime, isDirectory, newBuilder, newBuilder, newBuilder, newBuilder, newBuilder, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

downloadTo

public void downloadTo(Path path,
                       Blob.BlobSourceOption... options)

Downloads this blob to the given file path using specified blob read options.

Parameters:

path - destination

options - blob read options

Throws:

StorageException - upon failure

downloadTo

public void downloadTo(OutputStream outputStream,
                       Blob.BlobSourceOption... options)

Downloads this blob to the given output stream using specified blob read options.

Parameters:

outputStream -

options -

downloadTo

public void downloadTo(Path path)

Downloads this blob to the given file path.

This method is replaced with downloadTo(Path, BlobSourceOption...), but is kept here for binary compatibility with the older versions of the client library.

Parameters:

path - destination

Throws:

StorageException - upon failure

exists

public boolean exists(Blob.BlobSourceOption... options)

Checks if this blob exists.

Example of checking if the blob exists.

 boolean exists = blob.exists();
 if (exists) {
   // the blob exists
 } else {
   // the blob was not found
 }
 

Parameters:

options - blob read options

Returns:

true if this blob exists, false otherwise

Throws:

StorageException - upon failure

getContent

public byte[] getContent(Blob.BlobSourceOption... options)

Returns this blob's content.

Example of reading all bytes of the blob, if its generation matches the BlobInfo.getGeneration() value, otherwise a StorageException is thrown.

 byte[] content = blob.getContent(BlobSourceOption.generationMatch());
 

Parameters:

options - blob read options

Throws:

StorageException - upon failure

reload

public Blob reload(Blob.BlobSourceOption... options)

Fetches current blob's latest information. Returns null if the blob does not exist.

Example of getting the blob's latest information, if its generation does not match the BlobInfo.getGeneration() value, otherwise a StorageException is thrown.

 Blob latestBlob = blob.reload(BlobSourceOption.generationNotMatch());
 if (latestBlob == null) {
   // the blob was not found
 }
 

Parameters:

options - blob read options

Returns:

a Blob object with latest information or null if not found

Throws:

StorageException - upon failure

update

public Blob update(Storage.BlobTargetOption... options)

Updates the blob's information. Bucket or blob's name cannot be changed by this method. If you want to rename the blob or move it to a different bucket use the copyTo(com.google.cloud.storage.BlobId, com.google.cloud.storage.Blob.BlobSourceOption...) and delete(com.google.cloud.storage.Blob.BlobSourceOption...) operations. A new Blob object is returned. By default no checks are made on the metadata generation of the current blob. If you want to update the information only if the current blob metadata are at their latest version use the metagenerationMatch option: newBlob.update(BlobTargetOption.metagenerationMatch()).

Original metadata are merged with metadata in the provided blobInfo. If the original metadata already contains a key specified in the provided blobInfo's metadata map, it will be replaced by the new value. Removing metadata can be done by setting that metadata's value to null.

Example of adding new metadata values or updating existing ones.

 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 Map<String, String> newMetadata = new HashMap<>();
 newMetadata.put("keyToAddOrUpdate", "value");
 Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
     .setMetadata(newMetadata)
     .build());
 

Example of removing metadata values.

 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 Map<String, String> newMetadata = new HashMap<>();
 newMetadata.put("keyToRemove", null);
 Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
     .setMetadata(newMetadata)
     .build());
 

Parameters:

options - update options

Returns:

a Blob object with updated information

Throws:

StorageException - upon failure

delete

public boolean delete(Blob.BlobSourceOption... options)

Deletes this blob.

Example of deleting the blob, if its generation matches the BlobInfo.getGeneration() value, otherwise a StorageException is thrown.

 boolean deleted = blob.delete(BlobSourceOption.generationMatch());
 if (deleted) {
   // the blob was deleted
 } else {
   // the blob was not found
 }
 

Parameters:

options - blob delete options

Returns:

true if blob was deleted, false if it was not found

Throws:

StorageException - upon failure

copyTo

public CopyWriter copyTo(BlobId targetBlob,
                         Blob.BlobSourceOption... options)

Sends a copy request for the current blob to the target blob. Possibly also some of the metadata are copied (e.g. content-type).

Example of copying the blob to a different bucket with a different name.

 String bucketName = "my_unique_bucket";
 String blobName = "copy_blob_name";
 CopyWriter copyWriter = blob.copyTo(BlobId.of(bucketName, blobName));
 Blob copiedBlob = copyWriter.getResult();
 

Parameters:

targetBlob - target blob's id

options - source blob options

Returns:

a CopyWriter object that can be used to get information on the newly created blob or to complete the copy if more than one RPC request is needed

Throws:

StorageException - upon failure

copyTo

public CopyWriter copyTo(String targetBucket,
                         Blob.BlobSourceOption... options)

Sends a copy request for the current blob to the target bucket, preserving its name. Possibly copying also some of the metadata (e.g. content-type).

Example of copying the blob to a different bucket, keeping the original name.

 String bucketName = "my_unique_bucket";
 CopyWriter copyWriter = blob.copyTo(bucketName);
 Blob copiedBlob = copyWriter.getResult();
 

Parameters:

targetBucket - target bucket's name

options - source blob options

Returns:

a CopyWriter object that can be used to get information on the newly created blob or to complete the copy if more than one RPC request is needed

Throws:

StorageException - upon failure

copyTo

public CopyWriter copyTo(String targetBucket,
                         String targetBlob,
                         Blob.BlobSourceOption... options)

Sends a copy request for the current blob to the target blob. Possibly also some of the metadata are copied (e.g. content-type).

Example of copying the blob to a different bucket with a different name.

 String bucketName = "my_unique_bucket";
 String blobName = "copy_blob_name";
 CopyWriter copyWriter = blob.copyTo(bucketName, blobName);
 Blob copiedBlob = copyWriter.getResult();
 

Example of moving a blob to a different bucket with a different name.

 String destBucket = "my_unique_bucket";
 String destBlob = "move_blob_name";
 CopyWriter copyWriter = blob.copyTo(destBucket, destBlob);
 Blob copiedBlob = copyWriter.getResult();
 boolean deleted = blob.delete();
 

Parameters:

targetBucket - target bucket's name

targetBlob - target blob's name

options - source blob options

Returns:

a CopyWriter object that can be used to get information on the newly created blob or to complete the copy if more than one RPC request is needed

Throws:

StorageException - upon failure

reader

public com.google.cloud.ReadChannel reader(Blob.BlobSourceOption... options)

Returns a ReadChannel object for reading this blob's content.

Example of reading the blob's content through a reader.

 try (ReadChannel reader = blob.reader()) {
   ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
   while (reader.read(bytes) > 0) {
     bytes.flip();
     // do something with bytes
     bytes.clear();
   }
 }
 

Example of reading just a portion of the blob's content.

 int start = 1;
 int end = 8;
 try (ReadChannel reader = blob.reader()) {
   reader.seek(start);
   ByteBuffer bytes = ByteBuffer.allocate(end - start);
   reader.read(bytes);
   return bytes.array();
 }
 

Parameters:

options - blob read options

Throws:

StorageException - upon failure

writer

public com.google.cloud.WriteChannel writer(Storage.BlobWriteOption... options)

Returns a WriteChannel object for writing to this blob. By default any md5 and crc32c values in the current blob are ignored unless requested via the BlobWriteOption.md5Match and BlobWriteOption.crc32cMatch options.

Example of writing the blob's content through a writer.

 byte[] content = "Hello, World!".getBytes(UTF_8);
 try (WriteChannel writer = blob.writer()) {
   try {
     writer.write(ByteBuffer.wrap(content, 0, content.length));
   } catch (Exception ex) {
     // handle exception
   }
 }
 

Parameters:

options - target blob options

Throws:

StorageException - upon failure

signUrl

public URL signUrl(long duration,
                   TimeUnit unit,
                   Storage.SignUrlOption... options)

Generates a signed URL for this blob. If you want to allow access for a fixed amount of time to this blob, you can use this method to generate a URL that is only valid within a certain time period. This is particularly useful if you don't want publicly accessible blobs, but also don't want to require users to explicitly log in. Signing a URL requires a service account signer. If an instance of ServiceAccountSigner was passed to StorageOptions' builder via setCredentials(Credentials) or the default credentials are being used and the environment variable GOOGLE_APPLICATION_CREDENTIALS is set or your application is running in App Engine, then signUrl will use that credentials to sign the URL. If the credentials passed to StorageOptions do not implement ServiceAccountSigner (this is the case, for instance, for Compute Engine credentials and Google Cloud SDK credentials) then signUrl will throw an IllegalStateException unless an implementation of ServiceAccountSigner is passed using the Storage.SignUrlOption.signWith(ServiceAccountSigner) option.

A service account signer is looked for in the following order:

1. The signer passed with the option Storage.SignUrlOption.signWith(ServiceAccountSigner)
2. The credentials passed to StorageOptions
3. The default credentials, if no credentials were passed to StorageOptions

Example of creating a signed URL for the blob that is valid for 2 weeks, using the default credentials for signing the URL.

 URL signedUrl = blob.signUrl(14, TimeUnit.DAYS);
 

Example of creating a signed URL for the blob passing the Storage.SignUrlOption.signWith(ServiceAccountSigner) option, that will be used to sign the URL.

 String keyPath = "/path/to/key.json";
 URL signedUrl = blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
     ServiceAccountCredentials.fromStream(new FileInputStream(keyPath))));
 

Parameters:

duration - time until the signed URL expires, expressed in unit. The finer granularity supported is 1 second, finer granularities will be truncated

unit - time unit of the duration parameter

options - optional URL signing options

Returns:

a signed URL for this blob and the specified options

Throws:

IllegalStateException - if Storage.SignUrlOption.signWith(ServiceAccountSigner) was not used and no implementation of ServiceAccountSigner was provided to StorageOptions

IllegalArgumentException - if SignUrlOption.withMd5() option is used and blobInfo.md5() is null

IllegalArgumentException - if SignUrlOption.withContentType() option is used and blobInfo.contentType() is null

com.google.auth.ServiceAccountSigner.SigningException - if the attempt to sign the URL failed

See Also:

Signed-URLs

getAcl

public Acl getAcl(Acl.Entity entity)

Returns the ACL entry for the specified entity on this blob or null if not found.

Example of getting the ACL entry for an entity.

 Acl acl = blob.getAcl(User.ofAllAuthenticatedUsers());
 

Throws:

StorageException - upon failure

deleteAcl

public boolean deleteAcl(Acl.Entity entity)

Deletes the ACL entry for the specified entity on this blob.

Example of deleting the ACL entry for an entity.

 boolean deleted = blob.deleteAcl(User.ofAllAuthenticatedUsers());
 if (deleted) {
   // the acl entry was deleted
 } else {
   // the acl entry was not found
 }
 

Returns:

true if the ACL was deleted, false if it was not found

Throws:

StorageException - upon failure

createAcl

public Acl createAcl(Acl acl)

Creates a new ACL entry on this blob.

Example of creating a new ACL entry.

 Acl acl = blob.createAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.READER));
 

Throws:

StorageException - upon failure

updateAcl

public Acl updateAcl(Acl acl)

Updates an ACL entry on this blob.

Example of updating a new ACL entry.

 Acl acl = blob.updateAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.OWNER));
 

Throws:

StorageException - upon failure

listAcls

public List<Acl> listAcls()

Lists the ACL entries for this blob.

Example of listing the ACL entries.

 List<Acl> acls = blob.listAcls();
 for (Acl acl : acls) {
   // do something with ACL entry
 }
 

Throws:

StorageException - upon failure

getStorage

public Storage getStorage()

Returns the blob's Storage object used to issue requests.

toBuilder

public Blob.Builder toBuilder()

Description copied from class: BlobInfo

Returns a builder for the current blob.

Overrides:

toBuilder in class BlobInfo

equals

public final boolean equals(Object obj)

Overrides:

equals in class BlobInfo

hashCode

public final int hashCode()

Overrides:

hashCode in class BlobInfo