com.google.cloud.storage

Interface Storage

All Superinterfaces:

Service<StorageOptions>

public interface Storage
extends Service<StorageOptions>

An interface for Google Cloud Storage.

See Also:

Google Cloud Storage

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Storage.BlobField
static class	Storage.BlobGetOption Class for specifying blob get options.
static class	Storage.BlobListOption Class for specifying blob list options.
static class	Storage.BlobSourceOption Class for specifying blob source options.
static class	Storage.BlobTargetOption Class for specifying blob target options.
static class	Storage.BlobWriteOption Class for specifying blob write options.
static class	Storage.BucketField
static class	Storage.BucketGetOption Class for specifying bucket get options.
static class	Storage.BucketListOption Class for specifying bucket list options.
static class	Storage.BucketSourceOption Class for specifying bucket source options.
static class	Storage.BucketTargetOption Class for specifying bucket target options.
static class	Storage.ComposeRequest A class to contain all information needed for a Google Cloud Storage Compose operation.
static class	Storage.CopyRequest A class to contain all information needed for a Google Cloud Storage Copy operation.
static class	Storage.PredefinedAcl
static class	Storage.SignUrlOption Class for specifying signed URL options.

Method Summary

Modifier and Type	Method and Description
StorageBatch	batch() Creates a new empty batch for grouping multiple service calls in one underlying RPC call.
Blob	compose(Storage.ComposeRequest composeRequest) Sends a compose request.
CopyWriter	copy(Storage.CopyRequest copyRequest) Sends a copy request.
Blob	create(BlobInfo blobInfo, byte[] content, Storage.BlobTargetOption... options) Creates a new blob.
Blob	create(BlobInfo blobInfo, InputStream content, Storage.BlobWriteOption... options) Deprecated.
Blob	create(BlobInfo blobInfo, Storage.BlobTargetOption... options) Creates a new blob with no content.
Bucket	create(BucketInfo bucketInfo, Storage.BucketTargetOption... options) Creates a new bucket.
Acl	createAcl(BlobId blob, Acl acl) Creates a new ACL entry on the specified blob.
Acl	createAcl(String bucket, Acl acl)
Acl	createAcl(String bucket, Acl acl, Storage.BucketSourceOption... options) Creates a new ACL entry on the specified bucket.
Acl	createDefaultAcl(String bucket, Acl acl) Creates a new default blob ACL entry on the specified bucket.
List<Boolean>	delete(BlobId... blobIds) Deletes the requested blobs.
boolean	delete(BlobId blob) Deletes the requested blob.
boolean	delete(BlobId blob, Storage.BlobSourceOption... options) Deletes the requested blob.
List<Boolean>	delete(Iterable<BlobId> blobIds) Deletes the requested blobs.
boolean	delete(String bucket, Storage.BucketSourceOption... options) Deletes the requested bucket.
boolean	delete(String bucket, String blob, Storage.BlobSourceOption... options) Deletes the requested blob.
boolean	deleteAcl(BlobId blob, Acl.Entity entity) Deletes the ACL entry for the specified entity on the specified blob.
boolean	deleteAcl(String bucket, Acl.Entity entity)
boolean	deleteAcl(String bucket, Acl.Entity entity, Storage.BucketSourceOption... options) Deletes the ACL entry for the specified entity on the specified bucket.
boolean	deleteDefaultAcl(String bucket, Acl.Entity entity) Deletes the default object ACL entry for the specified entity on the specified bucket.
List<Blob>	get(BlobId... blobIds) Gets the requested blobs.
Blob	get(BlobId blob) Returns the requested blob or null if not found.
Blob	get(BlobId blob, Storage.BlobGetOption... options) Returns the requested blob or null if not found.
List<Blob>	get(Iterable<BlobId> blobIds) Gets the requested blobs.
Bucket	get(String bucket, Storage.BucketGetOption... options) Returns the requested bucket or null if not found.
Blob	get(String bucket, String blob, Storage.BlobGetOption... options) Returns the requested blob or null if not found.
Acl	getAcl(BlobId blob, Acl.Entity entity) Returns the ACL entry for the specified entity on the specified blob or null if not found.
Acl	getAcl(String bucket, Acl.Entity entity)
Acl	getAcl(String bucket, Acl.Entity entity, Storage.BucketSourceOption... options) Returns the ACL entry for the specified entity on the specified bucket or null if not found.
Acl	getDefaultAcl(String bucket, Acl.Entity entity) Returns the default object ACL entry for the specified entity on the specified bucket or null if not found.
Policy	getIamPolicy(String bucket, Storage.BucketSourceOption... options) Gets the IAM policy for the provided bucket.
ServiceAccount	getServiceAccount(String projectId) Returns the service account associated with the given project.
com.google.api.gax.paging.Page<Bucket>	list(Storage.BucketListOption... options) Lists the project's buckets.
com.google.api.gax.paging.Page<Blob>	list(String bucket, Storage.BlobListOption... options) Lists the bucket's blobs.
List<Acl>	listAcls(BlobId blob) Lists the ACL entries for the provided blob.
List<Acl>	listAcls(String bucket)
List<Acl>	listAcls(String bucket, Storage.BucketSourceOption... options) Lists the ACL entries for the provided bucket.
List<Acl>	listDefaultAcls(String bucket) Lists the default blob ACL entries for the provided bucket.
byte[]	readAllBytes(BlobId blob, Storage.BlobSourceOption... options) Reads all the bytes from a blob.
byte[]	readAllBytes(String bucket, String blob, Storage.BlobSourceOption... options) Reads all the bytes from a blob.
ReadChannel	reader(BlobId blob, Storage.BlobSourceOption... options) Returns a channel for reading the blob's content.
ReadChannel	reader(String bucket, String blob, Storage.BlobSourceOption... options) Returns a channel for reading the blob's content.
Policy	setIamPolicy(String bucket, Policy policy, Storage.BucketSourceOption... options) Updates the IAM policy on the specified bucket.
URL	signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, Storage.SignUrlOption... options) Generates a signed URL for a blob.
List<Boolean>	testIamPermissions(String bucket, List<String> permissions, Storage.BucketSourceOption... options) Tests whether the caller holds the permissions on the specified bucket.
List<Blob>	update(BlobInfo... blobInfos) Updates the requested blobs.
Blob	update(BlobInfo blobInfo) Updates blob information.
Blob	update(BlobInfo blobInfo, Storage.BlobTargetOption... options) Updates blob information.
Bucket	update(BucketInfo bucketInfo, Storage.BucketTargetOption... options) Updates bucket information.
List<Blob>	update(Iterable<BlobInfo> blobInfos) Updates the requested blobs.
Acl	updateAcl(BlobId blob, Acl acl) Updates an ACL entry on the specified blob.
Acl	updateAcl(String bucket, Acl acl)
Acl	updateAcl(String bucket, Acl acl, Storage.BucketSourceOption... options) Updates an ACL entry on the specified bucket.
Acl	updateDefaultAcl(String bucket, Acl acl) Updates a default blob ACL entry on the specified bucket.
WriteChannel	writer(BlobInfo blobInfo, Storage.BlobWriteOption... options) Creates a blob and return a channel for writing its content.

Methods inherited from interface com.google.cloud.Service

getOptions

Method Detail

create

Bucket create(BucketInfo bucketInfo,
              Storage.BucketTargetOption... options)

Creates a new bucket. Accepts an optional userProject Storage.BucketTargetOption option which defines the project id to assign operational costs.

Example of creating a bucket.

 
 String bucketName = "my_unique_bucket";
 Bucket bucket = storage.create(BucketInfo.of(bucketName));
 

Example of creating a bucket with storage class and location.

 
 String bucketName = "my_unique_bucket";
 Bucket bucket = storage.create(BucketInfo.newBuilder(bucketName)
     // See here for possible values: http://g.co/cloud/storage/docs/storage-classes
     .setStorageClass(StorageClass.COLDLINE)
     // Possible values: http://g.co/cloud/storage/docs/bucket-locations#location-mr
     .setLocation("asia")
     .build());
 

Returns:

a complete bucket

Throws:

StorageException - upon failure

create

Blob create(BlobInfo blobInfo,
            Storage.BlobTargetOption... options)

Creates a new blob with no content.

Example of creating a blob with no content.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 Blob blob = storage.create(blobInfo);
 

Returns:

a [@code Blob} with complete information

Throws:

StorageException - upon failure

create

Blob create(BlobInfo blobInfo,
            byte[] content,
            Storage.BlobTargetOption... options)

Creates a new blob. Direct upload is used to upload content. For large content, writer(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage.BlobWriteOption...) is recommended as it uses resumable upload. MD5 and CRC32C hashes of content are computed and used for validating transferred data. Accepts an optional userProject Storage.BlobGetOption option which defines the project id to assign operational costs.

Example of creating a blob from a byte array.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 Blob blob = storage.create(blobInfo, "Hello, World!".getBytes(UTF_8));
 

Returns:

a [@code Blob} with complete information

Throws:

StorageException - upon failure

See Also:

Hashes and ETags

create

@Deprecated
Blob create(BlobInfo blobInfo,
                        InputStream content,
                        Storage.BlobWriteOption... options)

Deprecated.

Creates a new blob. Direct upload is used to upload content. For large content, writer(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage.BlobWriteOption...) is recommended as it uses resumable upload. By default any md5 and crc32c values in the given blobInfo are ignored unless requested via the BlobWriteOption.md5Match and BlobWriteOption.crc32cMatch options. The given input stream is closed upon success.

This method is marked as Deprecated because it cannot safely retry, given that it accepts an InputStream which can only be consumed once.

Example of creating a blob from an input stream.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 Blob blob = storage.create(blobInfo, content);
 

Example of uploading an encrypted blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String encryptionKey = "my_encryption_key";
 InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));

 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId)
     .setContentType("text/plain")
     .build();
 Blob blob = storage.create(blobInfo, content, BlobWriteOption.encryptionKey(encryptionKey));
 

Returns:

a [@code Blob} with complete information

Throws:

StorageException - upon failure

get

Bucket get(String bucket,
           Storage.BucketGetOption... options)

Returns the requested bucket or null if not found. Accepts an optional userProject Storage.BucketGetOption option which defines the project id to assign operational costs.

Example of getting information on a bucket, only if its metageneration matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 long bucketMetageneration = 42;
 Bucket bucket = storage.get(bucketName,
     BucketGetOption.metagenerationMatch(bucketMetageneration));
 

Throws:

StorageException - upon failure

get

Blob get(String bucket,
         String blob,
         Storage.BlobGetOption... options)

Returns the requested blob or null if not found. Accepts an optional userProject Storage.BlobGetOption option which defines the project id to assign operational costs.

Example of getting information on a blob, only if its metageneration matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobMetageneration = 42;
 Blob blob = storage.get(bucketName, blobName,
     BlobGetOption.metagenerationMatch(blobMetageneration));
 

Throws:

StorageException - upon failure

get

Blob get(BlobId blob,
         Storage.BlobGetOption... options)

Returns the requested blob or null if not found. Accepts an optional userProject Storage.BlobGetOption option which defines the project id to assign operational costs.

Example of getting information on a blob, only if its metageneration matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobMetageneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName);
 Blob blob = storage.get(blobId, BlobGetOption.metagenerationMatch(blobMetageneration));
 

Throws:

StorageException - upon failure

get

Blob get(BlobId blob)

Returns the requested blob or null if not found.

Example of getting information on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 Blob blob = storage.get(blobId);
 

Throws:

StorageException - upon failure

list

com.google.api.gax.paging.Page<Bucket> list(Storage.BucketListOption... options)

Lists the project's buckets.

Example of listing buckets, specifying the page size and a name prefix.

 
 String prefix = "bucket_";
 Page<Bucket> buckets = storage.list(BucketListOption.pageSize(100),
     BucketListOption.prefix(prefix));
 Iterator<Bucket> bucketIterator = buckets.iterateAll();
 while (bucketIterator.hasNext()) {
   Bucket bucket = bucketIterator.next();
   // do something with the bucket
 }
 

Throws:

StorageException - upon failure

list

com.google.api.gax.paging.Page<Blob> list(String bucket,
                                          Storage.BlobListOption... options)

Lists the bucket's blobs. If the Storage.BlobListOption.currentDirectory() option is provided, results are returned in a directory-like mode.

Example of listing blobs in a provided directory.

 
 String bucketName = "my_unique_bucket";
 String directory = "my_directory/";
 Page<Blob> blobs = storage.list(bucketName, BlobListOption.currentDirectory(),
     BlobListOption.prefix(directory));
 Iterator<Blob> blobIterator = blobs.iterateAll();
 while (blobIterator.hasNext()) {
   Blob blob = blobIterator.next();
   // do something with the blob
 }
 

Throws:

StorageException - upon failure

update

Bucket update(BucketInfo bucketInfo,
              Storage.BucketTargetOption... options)

Updates bucket information. Accepts an optional userProject Storage.BucketTargetOption option which defines the project id to assign operational costs.

Example of updating bucket information.

 
 String bucketName = "my_unique_bucket";
 BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName).setVersioningEnabled(true).build();
 Bucket bucket = storage.update(bucketInfo);
 

Returns:

the updated bucket

Throws:

StorageException - upon failure

update

Blob update(BlobInfo blobInfo,
            Storage.BlobTargetOption... options)

Updates blob information. Original metadata are merged with metadata in the provided blobInfo. To replace metadata instead you first have to unset them. Unsetting metadata can be done by setting the provided blobInfo's metadata to null. Accepts an optional userProject Storage.BlobTargetOption option which defines the project id to assign operational costs.

Example of udating a blob, only if the blob's metageneration matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 Blob blob = storage.get(bucketName, blobName);
 BlobInfo updatedInfo = blob.toBuilder().setContentType("text/plain").build();
 storage.update(updatedInfo, BlobTargetOption.metagenerationMatch());
 

Returns:

the updated blob

Throws:

StorageException - upon failure

update

Blob update(BlobInfo blobInfo)

Updates blob information. Original metadata are merged with metadata in the provided blobInfo. To replace metadata instead you first have to unset them. Unsetting metadata can be done by setting the provided blobInfo's metadata to null.

Example of replacing blob's metadata.

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

Returns:

the updated blob

Throws:

StorageException - upon failure

delete

boolean delete(String bucket,
               Storage.BucketSourceOption... options)

Deletes the requested bucket. Accepts an optional userProject Storage.BucketSourceOption option which defines the project id to assign operational costs.

Example of deleting a bucket, only if its metageneration matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 long bucketMetageneration = 42;
 boolean deleted = storage.delete(bucketName,
     BucketSourceOption.metagenerationMatch(bucketMetageneration));
 if (deleted) {
   // the bucket was deleted
 } else {
   // the bucket was not found
 }
 

Returns:

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

Throws:

StorageException - upon failure

delete

boolean delete(String bucket,
               String blob,
               Storage.BlobSourceOption... options)

Deletes the requested blob.

Example of deleting a blob, only if its generation matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 boolean deleted = storage.delete(bucketName, blobName,
     BlobSourceOption.generationMatch(blobGeneration));
 if (deleted) {
   // the blob was deleted
 } else {
   // the blob was not found
 }
 

Returns:

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

Throws:

StorageException - upon failure

delete

boolean delete(BlobId blob,
               Storage.BlobSourceOption... options)

Deletes the requested blob. Accepts an optional userProject Storage.BlobSourceOption option which defines the project id to assign operational costs.

Example of deleting a blob, only if its generation matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName);
 boolean deleted = storage.delete(blobId, BlobSourceOption.generationMatch(blobGeneration));
 if (deleted) {
   // the blob was deleted
 } else {
   // the blob was not found
 }
 

Returns:

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

Throws:

StorageException - upon failure

delete

boolean delete(BlobId blob)

Deletes the requested blob.

Example of deleting a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 boolean deleted = storage.delete(blobId);
 if (deleted) {
   // the blob was deleted
 } else {
   // the blob was not found
 }
 

Returns:

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

Throws:

StorageException - upon failure

compose

Blob compose(Storage.ComposeRequest composeRequest)

Sends a compose request. Accepts an optional userProject Storage.BlobTargetOption option which defines the project id to assign operational costs.

Example of composing two blobs.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String sourceBlob1 = "source_blob_1";
 String sourceBlob2 = "source_blob_2";
 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 ComposeRequest request = ComposeRequest.newBuilder()
     .setTarget(blobInfo)
     .addSource(sourceBlob1)
     .addSource(sourceBlob2)
     .build();
 Blob blob = storage.compose(request);
 

Returns:

the composed blob

Throws:

StorageException - upon failure

copy

CopyWriter copy(Storage.CopyRequest copyRequest)

Sends a copy request. This method copies both blob's data and information. To override source blob's information supply a BlobInfo to the CopyRequest using either Storage.CopyRequest.Builder.setTarget(BlobInfo, Storage.BlobTargetOption...) or Storage.CopyRequest.Builder.setTarget(BlobInfo, Iterable).

This method returns a CopyWriter object for the provided CopyRequest. If source and destination objects share the same location and storage class the source blob is copied with one request and CopyWriter.getResult() immediately returns, regardless of the Storage.CopyRequest.megabytesCopiedPerChunk parameter. If source and destination have different location or storage class CopyWriter.getResult() might issue multiple RPC calls depending on blob's size.

Example of copying a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String copyBlobName = "copy_blob_name";
 CopyRequest request = CopyRequest.newBuilder()
     .setSource(BlobId.of(bucketName, blobName))
     .setTarget(BlobId.of(bucketName, copyBlobName))
     .build();
 Blob blob = storage.copy(request).getResult();
 

Example of copying a blob in chunks.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String copyBlobName = "copy_blob_name";
 CopyRequest request = CopyRequest.newBuilder()
     .setSource(BlobId.of(bucketName, blobName))
     .setTarget(BlobId.of(bucketName, copyBlobName))
     .build();
 CopyWriter copyWriter = storage.copy(request);
 while (!copyWriter.isDone()) {
   copyWriter.copyChunk();
 }
 Blob blob = copyWriter.getResult();
 

Example of rotating the encryption key of a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String oldEncryptionKey = "old_encryption_key";
 String newEncryptionKey = "new_encryption_key";
 BlobId blobId = BlobId.of(bucketName, blobName);
 CopyRequest request = CopyRequest.newBuilder()
     .setSource(blobId)
     .setSourceOptions(BlobSourceOption.decryptionKey(oldEncryptionKey))
     .setTarget(blobId, BlobTargetOption.encryptionKey(newEncryptionKey))
     .build();
 Blob blob = storage.copy(request).getResult();
 

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

See Also:

Rewrite

readAllBytes

byte[] readAllBytes(String bucket,
                    String blob,
                    Storage.BlobSourceOption... options)

Reads all the bytes from a blob.

Example of reading all bytes of a blob, if generation matches a value, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42";
 byte[] content = storage.readAllBytes(bucketName, blobName,
     BlobSourceOption.generationMatch(blobGeneration));
 

Returns:

the blob's content

Throws:

StorageException - upon failure

readAllBytes

byte[] readAllBytes(BlobId blob,
                    Storage.BlobSourceOption... options)

Reads all the bytes from a blob.

Example of reading all bytes of a blob's specific generation, otherwise a StorageException is thrown.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 byte[] content = storage.readAllBytes(blobId);
 

Example of reading all bytes of an encrypted blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String decryptionKey = "my_encryption_key";
 byte[] content = storage.readAllBytes(
     bucketName, blobName, BlobSourceOption.decryptionKey(decryptionKey));
 

Returns:

the blob's content

Throws:

StorageException - upon failure

batch

StorageBatch batch()

Creates a new empty batch for grouping multiple service calls in one underlying RPC call.

Example of using a batch request to delete, update and get a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 StorageBatch batch = storage.batch();
 BlobId firstBlob = BlobId.of(bucketName, blobName1);
 BlobId secondBlob = BlobId.of(bucketName, blobName2);
 batch.delete(firstBlob).notify(new BatchResult.Callback<Boolean, StorageException>() {
   public void success(Boolean result) {
     // deleted successfully
   }

   public void error(StorageException exception) {
     // delete failed
   }
 });
 batch.update(BlobInfo.newBuilder(secondBlob).setContentType("text/plain").build());
 StorageBatchResult<Blob> result = batch.get(secondBlob);
 batch.submit();
 Blob blob = result.get(); // returns get result or throws StorageException
 

reader

ReadChannel reader(String bucket,
                   String blob,
                   Storage.BlobSourceOption... options)

Returns a channel for reading the blob's content. The blob's latest generation is read. If the blob changes while reading (i.e. BlobInfo.getEtag() changes), subsequent calls to blobReadChannel.read(ByteBuffer) may throw StorageException.

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

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 try (ReadChannel reader = storage.reader(bucketName, blobName)) {
   ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
   while (reader.read(bytes) > 0) {
     bytes.flip();
     // do something with bytes
     bytes.clear();
   }
 }
 

Throws:

StorageException - upon failure

reader

ReadChannel reader(BlobId blob,
                   Storage.BlobSourceOption... options)

Returns a channel for reading the blob's content. If blob.generation() is set data corresponding to that generation is read. If blob.generation() is null the blob's latest generation is read. If the blob changes while reading (i.e. BlobInfo.getEtag() changes), subsequent calls to blobReadChannel.read(ByteBuffer) may throw StorageException.

The Storage.BlobSourceOption.generationMatch() and Storage.BlobSourceOption.generationMatch(long) options can be used to ensure that blobReadChannel.read(ByteBuffer) calls will throw StorageException if the blob`s generation differs from the expected one.

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

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 try (ReadChannel reader = storage.reader(blobId)) {
   ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
   while (reader.read(bytes) > 0) {
     bytes.flip();
     // do something with bytes
     bytes.clear();
   }
 }
 

Throws:

StorageException - upon failure

writer

WriteChannel writer(BlobInfo blobInfo,
                    Storage.BlobWriteOption... options)

Creates a blob and return a channel for writing its content. By default any md5 and crc32c values in the given blobInfo are ignored unless requested via the BlobWriteOption.md5Match and BlobWriteOption.crc32cMatch options.

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

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 BlobId blobId = BlobId.of(bucketName, blobName);
 byte[] content = "Hello, World!".getBytes(UTF_8);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 try (WriteChannel writer = storage.writer(blobInfo)) {
   try {
     writer.write(ByteBuffer.wrap(content, 0, content.length));
   } catch (Exception ex) {
     // handle exception
   }
 }
 

Throws:

StorageException - upon failure

signUrl

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

Generates a signed URL for a blob. If you have a blob that you want to allow access to for a fixed amount of time, 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 that is valid for 2 weeks, using the default credentials for signing the URL.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 URL signedUrl = storage.signUrl(BlobInfo.newBuilder(bucketName, blobName).build(), 14,
     TimeUnit.DAYS);
 

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

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String keyPath = "/path/to/key.json";
 URL signedUrl = storage.signUrl(BlobInfo.newBuilder(bucketName, blobName).build(),
     14, TimeUnit.DAYS, SignUrlOption.signWith(
         ServiceAccountCredentials.fromStream(new FileInputStream(keyPath))));
 

Parameters:

blobInfo - the blob associated with the signed URL

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

unit - time unit of the duration parameter

options - optional URL signing 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

ServiceAccountSigner.SigningException - if the attempt to sign the URL failed

See Also:

Signed-URLs

get

List<Blob> get(BlobId... blobIds)

Gets the requested blobs. A batch request is used to perform this call.

Example of getting information on several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 BlobId firstBlob = BlobId.of(bucketName, blobName1);
 BlobId secondBlob = BlobId.of(bucketName, blobName2);
 List<Blob> blobs = storage.get(firstBlob, secondBlob);
 

Parameters:

blobIds - blobs to get

Returns:

an immutable list of Blob objects. If a blob does not exist or access to it has been denied the corresponding item in the list is null.

Throws:

StorageException - upon failure

get

List<Blob> get(Iterable<BlobId> blobIds)

Gets the requested blobs. A batch request is used to perform this call.

Example of getting information on several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 List<BlobId> blobIds = new LinkedList<>();
 blobIds.add(BlobId.of(bucketName, blobName1));
 blobIds.add(BlobId.of(bucketName, blobName2));
 List<Blob> blobs = storage.get(blobIds);
 

Parameters:

blobIds - blobs to get

Returns:

an immutable list of Blob objects. If a blob does not exist or access to it has been denied the corresponding item in the list is null.

Throws:

StorageException - upon failure

update

List<Blob> update(BlobInfo... blobInfos)

Updates the requested blobs. A batch request is used to perform this call. Original metadata are merged with metadata in the provided BlobInfo objects. To replace metadata instead you first have to unset them. Unsetting metadata can be done by setting the provided BlobInfo objects metadata to null. See update(BlobInfo) for a code example.

Example of updating information on several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 Blob firstBlob = storage.get(bucketName, blobName1);
 Blob secondBlob = storage.get(bucketName, blobName2);
 List<Blob> updatedBlobs = storage.update(
     firstBlob.toBuilder().setContentType("text/plain").build(),
     secondBlob.toBuilder().setContentType("text/plain").build());
 

Parameters:

blobInfos - blobs to update

Returns:

an immutable list of Blob objects. If a blob does not exist or access to it has been denied the corresponding item in the list is null.

Throws:

StorageException - upon failure

update

List<Blob> update(Iterable<BlobInfo> blobInfos)

Updates the requested blobs. A batch request is used to perform this call. Original metadata are merged with metadata in the provided BlobInfo objects. To replace metadata instead you first have to unset them. Unsetting metadata can be done by setting the provided BlobInfo objects metadata to null. See update(BlobInfo) for a code example.

Example of updating information on several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 Blob firstBlob = storage.get(bucketName, blobName1);
 Blob secondBlob = storage.get(bucketName, blobName2);
 List<BlobInfo> blobs = new LinkedList<>();
 blobs.add(firstBlob.toBuilder().setContentType("text/plain").build());
 blobs.add(secondBlob.toBuilder().setContentType("text/plain").build());
 List<Blob> updatedBlobs = storage.update(blobs);
 

Parameters:

blobInfos - blobs to update

Returns:

an immutable list of Blob objects. If a blob does not exist or access to it has been denied the corresponding item in the list is null.

Throws:

StorageException - upon failure

delete

List<Boolean> delete(BlobId... blobIds)

Deletes the requested blobs. A batch request is used to perform this call.

Example of deleting several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 BlobId firstBlob = BlobId.of(bucketName, blobName1);
 BlobId secondBlob = BlobId.of(bucketName, blobName2);
 List<Boolean> deleted = storage.delete(firstBlob, secondBlob);
 

Parameters:

blobIds - blobs to delete

Returns:

an immutable list of booleans. If a blob has been deleted the corresponding item in the list is true. If a blob was not found, deletion failed or access to the resource was denied the corresponding item is false.

Throws:

StorageException - upon failure

delete

List<Boolean> delete(Iterable<BlobId> blobIds)

Deletes the requested blobs. A batch request is used to perform this call.

Example of deleting several blobs using a single batch request.

 
 String bucketName = "my_unique_bucket";
 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 List<BlobId> blobIds = new LinkedList<>();
 blobIds.add(BlobId.of(bucketName, blobName1));
 blobIds.add(BlobId.of(bucketName, blobName2));
 List<Boolean> deleted = storage.delete(blobIds);
 

Parameters:

blobIds - blobs to delete

Returns:

an immutable list of booleans. If a blob has been deleted the corresponding item in the list is true. If a blob was not found, deletion failed or access to the resource was denied the corresponding item is false.

Throws:

StorageException - upon failure

getAcl

Acl getAcl(String bucket,
           Acl.Entity entity,
           Storage.BucketSourceOption... options)

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

Example of getting the ACL entry for an entity on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.getAcl(bucketName, User.ofAllAuthenticatedUsers());
 

Example of getting the ACL entry for a specific user on a requester_pays bucket with a user_project option.

 
 String bucketName = "my_unique_bucket";
 String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
 BucketSourceOption userProjectOption = BucketSourceOption.userProject("myProject");
 Acl acl = storage.getAcl(bucketName, new User(userEmail), userProjectOption);
 

Parameters:

bucket - name of the bucket where the getAcl operation takes place

entity - ACL entity to fetch

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

getAcl

Acl getAcl(String bucket,
           Acl.Entity entity)

See Also:

#getAcl(String, Entity, BucketSourceOption...)

deleteAcl

boolean deleteAcl(String bucket,
                  Acl.Entity entity,
                  Storage.BucketSourceOption... options)

Deletes the ACL entry for the specified entity on the specified bucket.

Example of deleting the ACL entry for an entity on a bucket.

 
 String bucketName = "my_unique_bucket";
 boolean deleted = storage.deleteAcl(bucketName, User.ofAllAuthenticatedUsers());
 if (deleted) {
   // the acl entry was deleted
 } else {
   // the acl entry was not found
 }
 

Example of deleting the ACL entry for a specific user on a requester_pays bucket with a user_project option.

 
 String bucketName = "my_unique_bucket";
 BucketSourceOption userProject = BucketSourceOption.userProject("myProject");
 boolean deleted = storage.deleteAcl(bucketName, User.ofAllAuthenticatedUsers(), userProject);
 

Parameters:

bucket - name of the bucket to delete an ACL from

entity - ACL entity to delete

options - extra parameters to apply to this operation

Returns:

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

Throws:

StorageException - upon failure

deleteAcl

boolean deleteAcl(String bucket,
                  Acl.Entity entity)

See Also:

#deleteAcl(String, Entity, BucketSourceOption...)

createAcl

Acl createAcl(String bucket,
              Acl acl,
              Storage.BucketSourceOption... options)

Creates a new ACL entry on the specified bucket.

Example of creating a new ACL entry on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.createAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
 

Example of creating a new ACL entry on a requester_pays bucket with a user_project option.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.createAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER),
     BucketSourceOption.userProject("myProject"));
 

Parameters:

bucket - name of the bucket for which an ACL should be created

acl - ACL to create

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

createAcl

Acl createAcl(String bucket,
              Acl acl)

See Also:

createAcl(String, Acl, BucketSourceOption...)

updateAcl

Acl updateAcl(String bucket,
              Acl acl,
              Storage.BucketSourceOption... options)

Updates an ACL entry on the specified bucket.

Example of updating a new ACL entry on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.updateAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
 

Example of updating a new ACL entry on a requester_pays bucket with a user_project option.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.updateAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER),
     BucketSourceOption.userProject("myProject"));
 

Parameters:

bucket - name of the bucket where the updateAcl operation takes place

acl - ACL to update

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

updateAcl

Acl updateAcl(String bucket,
              Acl acl)

See Also:

updateAcl(String, Acl, BucketSourceOption...)

listAcls

List<Acl> listAcls(String bucket,
                   Storage.BucketSourceOption... options)

Lists the ACL entries for the provided bucket.

Example of listing the ACL entries for a blob.

 
 String bucketName = "my_unique_bucket";
 List<Acl> acls = storage.listAcls(bucketName);
 for (Acl acl : acls) {
   // do something with ACL entry
 }
 

Example of listing the ACL entries for a blob in a requester_pays bucket with a user_project option.

 
 String bucketName = "my_unique_bucket";
 List<Acl> acls = storage.listAcls(bucketName, BucketSourceOption.userProject("myProject"));
 for (Acl acl : acls) {
   // do something with ACL entry
 }
 

Parameters:

bucket - the name of the bucket to list ACLs for

options - any number of BucketSourceOptions to apply to this operation

Throws:

StorageException - upon failure

listAcls

List<Acl> listAcls(String bucket)

See Also:

listAcls(String, BucketSourceOption...)

getDefaultAcl

Acl getDefaultAcl(String bucket,
                  Acl.Entity entity)

Returns the default object ACL entry for the specified entity on the specified bucket or null if not found.

Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.

Example of getting the default ACL entry for an entity on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl = storage.getDefaultAcl(bucketName, User.ofAllAuthenticatedUsers());
 

Throws:

StorageException - upon failure

deleteDefaultAcl

boolean deleteDefaultAcl(String bucket,
                         Acl.Entity entity)

Deletes the default object ACL entry for the specified entity on the specified bucket.

Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.

Example of deleting the default ACL entry for an entity on a bucket.

 
 String bucketName = "my_unique_bucket";
 boolean deleted = storage.deleteDefaultAcl(bucketName, 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

createDefaultAcl

Acl createDefaultAcl(String bucket,
                     Acl acl)

Creates a new default blob ACL entry on the specified bucket.

Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.

Example of creating a new default ACL entry on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl =
     storage.createDefaultAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
 

Throws:

StorageException - upon failure

updateDefaultAcl

Acl updateDefaultAcl(String bucket,
                     Acl acl)

Updates a default blob ACL entry on the specified bucket.

Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.

Example of updating a new default ACL entry on a bucket.

 
 String bucketName = "my_unique_bucket";
 Acl acl =
     storage.updateDefaultAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
 

Throws:

StorageException - upon failure

listDefaultAcls

List<Acl> listDefaultAcls(String bucket)

Lists the default blob ACL entries for the provided bucket.

Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.

Example of listing the default ACL entries for a blob.

 
 String bucketName = "my_unique_bucket";
 List<Acl> acls = storage.listDefaultAcls(bucketName);
 for (Acl acl : acls) {
   // do something with ACL entry
 }
 

Throws:

StorageException - upon failure

getAcl

Acl getAcl(BlobId blob,
           Acl.Entity entity)

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

Example of getting the ACL entry for an entity on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 Acl acl = storage.getAcl(blobId, User.ofAllAuthenticatedUsers());
 

Example of getting the ACL entry for a specific user on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
 BlobId blobId = BlobId.of(bucketName, blobName);
 Acl acl = storage.getAcl(blobId, new User(userEmail));
 

Throws:

StorageException - upon failure

deleteAcl

boolean deleteAcl(BlobId blob,
                  Acl.Entity entity)

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

Example of deleting the ACL entry for an entity on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 boolean deleted = storage.deleteAcl(blobId, 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

Acl createAcl(BlobId blob,
              Acl acl)

Creates a new ACL entry on the specified blob.

Example of creating a new ACL entry on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 Acl acl = storage.createAcl(blobId, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
 

Example of updating a blob to be public-read.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 Acl acl = storage.createAcl(blobId, Acl.of(User.ofAllUsers(), Role.READER));
 

Throws:

StorageException - upon failure

updateAcl

Acl updateAcl(BlobId blob,
              Acl acl)

Updates an ACL entry on the specified blob.

Example of updating a new ACL entry on a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 Acl acl = storage.updateAcl(blobId, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
 

Throws:

StorageException - upon failure

listAcls

List<Acl> listAcls(BlobId blob)

Lists the ACL entries for the provided blob.

Example of listing the ACL entries for a blob.

 
 String bucketName = "my_unique_bucket";
 String blobName = "my_blob_name";
 long blobGeneration = 42;
 BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
 List<Acl> acls = storage.listAcls(blobId);
 for (Acl acl : acls) {
   // do something with ACL entry
 }
 

Throws:

StorageException - upon failure

getIamPolicy

@BetaApi
Policy getIamPolicy(String bucket,
                             Storage.BucketSourceOption... options)

Gets the IAM policy for the provided bucket.

Example of getting the IAM policy for a bucket.

 
 String bucketName = "my_unique_bucket";
 Policy policy = storage.getIamPolicy(bucketName);
 

Parameters:

bucket - name of the bucket where the getIamPolicy operation takes place

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

setIamPolicy

@BetaApi
Policy setIamPolicy(String bucket,
                             Policy policy,
                             Storage.BucketSourceOption... options)

Updates the IAM policy on the specified bucket.

Example of updating the IAM policy on a bucket.

 // We want to make all objects in our bucket publicly readable.
 String bucketName = "my_unique_bucket";
 Policy currentPolicy = storage.getIamPolicy(bucketName);
 Policy updatedPolicy =
     storage.setIamPolicy(
         bucketName,
         currentPolicy.toBuilder()
             .addIdentity(StorageRoles.objectViewer(), Identity.allUsers())
             .build());
 

Parameters:

bucket - name of the bucket where the setIamPolicy operation takes place

policy - policy to be set on the specified bucket

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

testIamPermissions

@BetaApi
List<Boolean> testIamPermissions(String bucket,
                                          List<String> permissions,
                                          Storage.BucketSourceOption... options)

Tests whether the caller holds the permissions on the specified bucket. Returns a list of booleans in the same placement and order in which the permissions were specified.

Example of testing permissions on a bucket.

 
 String bucketName = "my_unique_bucket";
 List<Boolean> response =
     storage.testIamPermissions(
         bucket,
         ImmutableList.of("storage.buckets.get", "storage.buckets.getIamPolicy"));
 for (boolean hasPermission : response) {
   // Do something with permission test response
 }
 

Parameters:

bucket - name of the bucket where the testIamPermissions operation takes place

permissions - list of permissions to test on the bucket

options - extra parameters to apply to this operation

Throws:

StorageException - upon failure

getServiceAccount

ServiceAccount getServiceAccount(String projectId)

Returns the service account associated with the given project.

Example of getting a service account.

 
 String projectId = "[email protected]";
 ServiceAccount account = storage.getServiceAccount(projectId);
 

Parameters:

projectId - the ID of the project for which the service account should be fetched.

Returns:

the service account associated with this project

Throws:

StorageException - upon failure