com.google.cloud.storage

Class Bucket

java.lang.Object

com.google.cloud.storage.BucketInfo

com.google.cloud.storage.Bucket

All Implemented Interfaces:

Serializable

public class Bucket
extends BucketInfo

A Google cloud storage bucket.

Objects of this class are immutable. Operations that modify the bucket like update(com.google.cloud.storage.Storage.BucketTargetOption...) return a new object. To get a Bucket object with the most recent information use reload(com.google.cloud.storage.Bucket.BucketSourceOption...). Bucket adds a layer of service-related functionality over BucketInfo.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Bucket.BlobTargetOption Class for specifying blob target options when Bucket methods are used.
static class	Bucket.BlobWriteOption Class for specifying blob write options when Bucket methods are used.
static class	Bucket.BucketSourceOption Class for specifying bucket source options when Bucket methods are used.
static class	Bucket.Builder Builder for Bucket.

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

BucketInfo.AgeDeleteRule, BucketInfo.CreatedBeforeDeleteRule, BucketInfo.DeleteRule, BucketInfo.IsLiveDeleteRule, BucketInfo.NumNewerVersionsDeleteRule

Method Summary

Methods

Modifier and Type	Method and Description
Blob	create(String blob, byte[] content, Bucket.BlobTargetOption... options) Creates a new blob in this bucket.
Blob	create(String blob, byte[] content, String contentType, Bucket.BlobTargetOption... options) Creates a new blob in this bucket.
Blob	create(String blob, InputStream content, Bucket.BlobWriteOption... options) Creates a new blob in this bucket.
Blob	create(String blob, InputStream content, String contentType, Bucket.BlobWriteOption... options) Creates a new blob in this bucket.
boolean	delete(Bucket.BucketSourceOption... options) Deletes this bucket.
boolean	equals(Object obj)
boolean	exists(Bucket.BucketSourceOption... options) Checks if this bucket exists.
List<Blob>	get(Iterable<String> blobNames) Returns a list of requested blobs in this bucket.
Blob	get(String blob, Storage.BlobGetOption... options) Returns the requested blob in this bucket or null if not found.
List<Blob>	get(String blobName1, String blobName2, String... blobNames) Returns a list of requested blobs in this bucket.
int	hashCode()
Page<Blob>	list(Storage.BlobListOption... options) Returns the paginated list of Blob in this bucket.
Bucket	reload(Bucket.BucketSourceOption... options) Fetches current bucket's latest information.
Storage	storage() Returns the bucket's Storage object used to issue requests.
Bucket.Builder	toBuilder() Returns a builder for the current bucket.
Bucket	update(Storage.BucketTargetOption... options) Updates the bucket's information.

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

acl, builder, cors, createTime, defaultAcl, deleteRules, etag, generatedId, indexPage, location, metageneration, name, notFoundPage, of, owner, selfLink, storageClass, toString, versioningEnabled

Methods inherited from class java.lang.Object

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

Method Detail

exists

public boolean exists(Bucket.BucketSourceOption... options)

Checks if this bucket exists.

Example of checking if the bucket exists.

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

Returns:

true if this bucket exists, false otherwise

Throws:

StorageException - upon failure

reload

public Bucket reload(Bucket.BucketSourceOption... options)

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

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

 Bucket latestBucket = bucket.reload(BucketSourceOption.metagenerationMatch());
 if (latestBucket == null) {
   // the bucket was not found
 }
 

Parameters:

options - bucket read options

Returns:

a Bucket object with latest information or null if not found

Throws:

StorageException - upon failure

update

public Bucket update(Storage.BucketTargetOption... options)

Updates the bucket's information. Bucket's name cannot be changed. A new Bucket object is returned. By default no checks are made on the metadata generation of the current bucket. If you want to update the information only if the current bucket metadata are at their latest version use the metagenerationMatch option: bucket.update(BucketTargetOption.metagenerationMatch())

Example of updating the bucket's information.

 Bucket updatedBucket = bucket.toBuilder().versioningEnabled(true).build().update();
 

Parameters:

options - update options

Returns:

a Bucket object with updated information

Throws:

StorageException - upon failure

delete

public boolean delete(Bucket.BucketSourceOption... options)

Deletes this bucket.

Example of deleting the bucket, if its metageneration matches the BucketInfo.metageneration() value, otherwise a StorageException is thrown.

 boolean deleted = bucket.delete(BucketSourceOption.metagenerationMatch());
 if (deleted) {
   // the bucket was deleted
 } else {
   // the bucket was not found
 }
 

Parameters:

options - bucket delete options

Returns:

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

Throws:

StorageException - upon failure

list

public Page<Blob> list(Storage.BlobListOption... options)

Returns the paginated list of Blob in this bucket.

Example of listing the blobs in the bucket.

 Iterator<Blob> blobIterator = bucket.list().iterateAll();
 while (blobIterator.hasNext()) {
   Blob blob = blobIterator.next();
   // do something with the blob
 }
 

Parameters:

options - options for listing blobs

Throws:

StorageException - upon failure

get

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

Returns the requested blob in this bucket or null if not found.

Example of getting a blob in the bucket, only if its metageneration matches a value, otherwise a StorageException is thrown.

 String blobName = "my_blob_name";
 long generation = 42;
 Blob blob = bucket.get(blobName, BlobGetOption.generationMatch(generation));
 

Parameters:

blob - name of the requested blob

options - blob search options

Throws:

StorageException - upon failure

get

public List<Blob> get(String blobName1,
             String blobName2,
             String... blobNames)

Returns a list of requested blobs in this bucket. Blobs that do not exist are null.

Example of getting some blobs in the bucket, using a batch request.

 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 List<Blob> blobs = bucket.get(blobName1, blobName2);
 for (Blob blob : blobs) {
   if (blob == null) {
     // the blob was not found
   }
 }
 

Parameters:

blobName1 - first blob to get

blobName2 - second blob to get

blobNames - other blobs to get

Returns:

an immutable list of Blob objects

Throws:

StorageException - upon failure

get

public List<Blob> get(Iterable<String> blobNames)

Returns a list of requested blobs in this bucket. Blobs that do not exist are null.

Example of getting some blobs in the bucket, using a batch request.

 String blobName1 = "my_blob_name1";
 String blobName2 = "my_blob_name2";
 List<String> blobNames = new LinkedList<>();
 blobNames.add(blobName1);
 blobNames.add(blobName2);
 List<Blob> blobs = bucket.get(blobNames);
 for (Blob blob : blobs) {
   if (blob == null) {
     // the blob was not found
   }
 }
 

Parameters:

blobNames - blobs to get

Returns:

an immutable list of Blob objects

Throws:

StorageException - upon failure

create

public Blob create(String blob,
          byte[] content,
          String contentType,
          Bucket.BlobTargetOption... options)

Creates a new blob in this bucket. Direct upload is used to upload content. For large content, Blob.writer(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.

Example of creating a blob in the bucket from a byte array with a content type.

 String blobName = "my_blob_name";
 Blob blob = bucket.create(blobName, "Hello, World!".getBytes(UTF_8), "text/plain");
 

Parameters:

blob - a blob name

content - the blob content

contentType - the blob content type

options - options for blob creation

Returns:

a complete blob information

Throws:

StorageException - upon failure

create

public Blob create(String blob,
          InputStream content,
          String contentType,
          Bucket.BlobWriteOption... options)

Creates a new blob in this bucket. Direct upload is used to upload content. For large content, Blob.writer(com.google.cloud.storage.Storage.BlobWriteOption...) is recommended as it uses resumable upload.

Example of creating a blob in the bucket from an input stream with a content type.

 String blobName = "my_blob_name";
 InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
 Blob blob = bucket.create(blobName, content, "text/plain");
 

Parameters:

blob - a blob name

content - the blob content as a stream

contentType - the blob content type

options - options for blob creation

Returns:

a complete blob information

Throws:

StorageException - upon failure

create

public Blob create(String blob,
          byte[] content,
          Bucket.BlobTargetOption... options)

Creates a new blob in this bucket. Direct upload is used to upload content. For large content, Blob.writer(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.

Example of creating a blob in the bucket from a byte array.

 String blobName = "my_blob_name";
 Blob blob = bucket.create(blobName, "Hello, World!".getBytes(UTF_8));
 

Parameters:

blob - a blob name

content - the blob content

options - options for blob creation

Returns:

a complete blob information

Throws:

StorageException - upon failure

create

public Blob create(String blob,
          InputStream content,
          Bucket.BlobWriteOption... options)

Creates a new blob in this bucket. Direct upload is used to upload content. For large content, Blob.writer(com.google.cloud.storage.Storage.BlobWriteOption...) is recommended as it uses resumable upload.

Example of creating a blob in the bucket from an input stream.

 String blobName = "my_blob_name";
 InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
 Blob blob = bucket.create(blobName, content);
 

Parameters:

blob - a blob name

content - the blob content as a stream

options - options for blob creation

Returns:

a complete blob information

Throws:

StorageException - upon failure

storage

public Storage storage()

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

toBuilder

public Bucket.Builder toBuilder()

Description copied from class: BucketInfo

Returns a builder for the current bucket.

Overrides:

toBuilder in class BucketInfo

equals

public final boolean equals(Object obj)

Overrides:

equals in class BucketInfo

hashCode

public final int hashCode()

Overrides:

hashCode in class BucketInfo