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

Methods

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) Creates a new blob.
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.
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.
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.
Page<Bucket>	list(Storage.BucketListOption... options) Lists the project's buckets.
Page<Blob>	list(String bucket, Storage.BlobListOption... options) Lists the bucket's blobs.
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.
URL	signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, Storage.SignUrlOption... options) Generates a signed URL for a blob.
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.
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

options

Method Detail

create

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

Creates a new bucket.

Returns:

a complete bucket

Throws:

StorageException - upon failure

create

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

Creates a new blob with no content.

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.

Returns:

a [@code Blob} with complete information

Throws:

StorageException - upon failure

See Also:

Hashes and ETags

create

Blob create(BlobInfo blobInfo,
          InputStream content,
          Storage.BlobWriteOption... 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. 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.

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.

Throws:

StorageException - upon failure

get

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

Returns the requested blob or null if not found.

Throws:

StorageException - upon failure

get

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

Returns the requested blob or null if not found.

Throws:

StorageException - upon failure

get

Blob get(BlobId blob)

Returns the requested blob or null if not found.

Throws:

StorageException - upon failure

list

Page<Bucket> list(Storage.BucketListOption... options)

Lists the project's buckets.

Throws:

StorageException - upon failure

list

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.

Throws:

StorageException - upon failure

update

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

Updates bucket information.

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.

Example usage of replacing blob's metadata:

 service.update(BlobInfo.builder("bucket", "name").metadata(null).build());
 service.update(BlobInfo.builder("bucket", "name").metadata(newMetadata).build());
 
 

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 usage of replacing blob's metadata:

 service.update(BlobInfo.builder("bucket", "name").metadata(null).build());
 service.update(BlobInfo.builder("bucket", "name").metadata(newMetadata).build());
 
 

Returns:

the updated blob

Throws:

StorageException - upon failure

delete

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

Deletes the requested bucket.

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.

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.

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.

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.

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.target(BlobInfo, Storage.BlobTargetOption...) or Storage.CopyRequest.Builder.target(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.result() immediately returns, regardless of the Storage.CopyRequest.megabytesCopiedPerChunk parameter. If source and destination have different location or storage class CopyWriter.result() might issue multiple RPC calls depending on blob's size.

Example usage of copy:

 BlobInfo blob = service.copy(copyRequest).result();
 

To explicitly issue chunk copy requests use CopyWriter.copyChunk() instead:

 CopyWriter copyWriter = service.copy(copyRequest);
 while (!copyWriter.isDone()) {
     copyWriter.copyChunk();
 }
 BlobInfo blob = copyWriter.result();
 
 

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.

Returns:

the blob's content

Throws:

StorageException - upon failure

readAllBytes

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

Reads all the bytes from a blob.

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:

StorageBatch batch = storage.batch();
 BlobId firstBlob = BlobId.of("bucket", "blob1"));
 BlobId secondBlob = BlobId.of("bucket", "blob2"));
 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.builder(secondBlob).contentType("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.etag() changes), subsequent calls to blobReadChannel.read(ByteBuffer) may throw StorageException.

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

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.etag() 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.

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.

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 a AuthCredentials.ServiceAccountAuthCredentials or an AuthCredentials.AppEngineAuthCredentials was passed to ServiceOptions.Builder.authCredentials(AuthCredentials) or the default credentials are being used and the environment variable GOOGLE_APPLICATION_CREDENTIALS is set, 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 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 ServiceOptions.Builder.authCredentials(AuthCredentials)
3. The default credentials, if no credentials were passed to StorageOptions

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

 service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS);
 

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

 service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS,
     SignUrlOption.signWith(
         AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
 

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.

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.

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.

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.

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.

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.

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