public class Blob extends BlobInfo
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
.
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 . |
BlobInfo.CustomerEncryption, BlobInfo.ImmutableEmptyMap<K,V>
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(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.
|
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.
|
WriteChannel |
writer(Storage.BlobWriteOption... options)
Returns a
WriteChannel object for writing to this blob. |
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
public void downloadTo(Path path, Blob.BlobSourceOption... options)
path
- destinationoptions
- blob read optionsStorageException
- upon failurepublic void downloadTo(Path path)
This method is replaced with downloadTo(Path, BlobSourceOption...)
, but is kept
here for binary compatibility with the older versions of the client library.
path
- destinationStorageException
- upon failurepublic boolean exists(Blob.BlobSourceOption... options)
Example of checking if the blob exists.
boolean exists = blob.exists();
if (exists) {
// the blob exists
} else {
// the blob was not found
}
options
- blob read optionsStorageException
- upon failurepublic byte[] getContent(Blob.BlobSourceOption... options)
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());
options
- blob read optionsStorageException
- upon failurepublic Blob reload(Blob.BlobSourceOption... options)
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
}
options
- blob read optionsBlob
object with latest information or null
if not foundStorageException
- upon failurepublic Blob update(Storage.BlobTargetOption... options)
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 in this blob
. To replace
metadata instead you first have to unset them. Unsetting metadata can be done by setting this
blob
's metadata to null
.
Example of replacing blob's metadata.
Map<String, String> newMetadata = new HashMap<>();
newMetadata.put("key", "value");
blob.toBuilder().setMetadata(null).build().update();
Blob updatedBlob = blob.toBuilder().setMetadata(newMetadata).build().update();
options
- update optionsBlob
object with updated informationStorageException
- upon failurepublic boolean delete(Blob.BlobSourceOption... options)
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
}
options
- blob delete optionstrue
if blob was deleted, false
if it was not foundStorageException
- upon failurepublic CopyWriter copyTo(BlobId targetBlob, Blob.BlobSourceOption... options)
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();
targetBlob
- target blob's idoptions
- source blob optionsCopyWriter
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 neededStorageException
- upon failurepublic CopyWriter copyTo(String targetBucket, Blob.BlobSourceOption... options)
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();
targetBucket
- target bucket's nameoptions
- source blob optionsCopyWriter
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 neededStorageException
- upon failurepublic CopyWriter copyTo(String targetBucket, String targetBlob, Blob.BlobSourceOption... options)
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();
targetBucket
- target bucket's nametargetBlob
- target blob's nameoptions
- source blob optionsCopyWriter
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 neededStorageException
- upon failurepublic ReadChannel reader(Blob.BlobSourceOption... options)
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();
}
options
- blob read optionsStorageException
- upon failurepublic WriteChannel writer(Storage.BlobWriteOption... options)
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
}
}
options
- target blob optionsStorageException
- upon failurepublic URL signUrl(long duration, TimeUnit unit, Storage.SignUrlOption... options)
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:
Storage.SignUrlOption.signWith(ServiceAccountSigner)
StorageOptions
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))));
duration
- time until the signed URL expires, expressed in unit
. The finer
granularity supported is 1 second, finer granularities will be truncatedunit
- time unit of the duration
parameteroptions
- optional URL signing optionsIllegalStateException
- 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
ServiceAccountSigner.SigningException
- if the attempt to sign the URL failedpublic Acl getAcl(Acl.Entity entity)
null
if not found.
Example of getting the ACL entry for an entity.
Acl acl = blob.getAcl(User.ofAllAuthenticatedUsers());
StorageException
- upon failurepublic boolean deleteAcl(Acl.Entity entity)
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
}
true
if the ACL was deleted, false
if it was not foundStorageException
- upon failurepublic Acl createAcl(Acl acl)
Example of creating a new ACL entry.
Acl acl = blob.createAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.READER));
StorageException
- upon failurepublic Acl updateAcl(Acl acl)
Example of updating a new ACL entry.
Acl acl = blob.updateAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.OWNER));
StorageException
- upon failurepublic List<Acl> listAcls()
Example of listing the ACL entries.
List<Acl> acls = blob.listAcls();
for (Acl acl : acls) {
// do something with ACL entry
}
StorageException
- upon failurepublic Storage getStorage()
Storage
object used to issue requests.public Blob.Builder toBuilder()
BlobInfo
Copyright © 2019 Google LLC. All rights reserved.