Class Bucket (2.3.0)

public class Bucket extends BucketInfo

A Google cloud storage bucket.

Objects of this class are immutable. Operations that modify the bucket like #update return a new object. To get a Bucket object with the most recent information use #reload. Bucket adds a layer of service-related functionality over BucketInfo.

Inheritance

Object > BucketInfo > Bucket

Inherited Members

BucketInfo.equals(Object)

BucketInfo.getAcl()

BucketInfo.getCors()

BucketInfo.getCreateTime()

BucketInfo.getDefaultAcl()

BucketInfo.getDefaultEventBasedHold()

BucketInfo.getDefaultKmsKeyName()

BucketInfo.getDeleteRules()

BucketInfo.getEtag()

BucketInfo.getGeneratedId()

BucketInfo.getIamConfiguration()

BucketInfo.getIndexPage()

BucketInfo.getLabels()

BucketInfo.getLifecycleRules()

BucketInfo.getLocation()

BucketInfo.getLocationType()

BucketInfo.getLogging()

BucketInfo.getMetageneration()

BucketInfo.getName()

BucketInfo.getNotFoundPage()

BucketInfo.getOwner()

BucketInfo.getRetentionEffectiveTime()

BucketInfo.getRetentionPeriod()

BucketInfo.getRpo()

BucketInfo.getSelfLink()

BucketInfo.getStorageClass()

BucketInfo.getUpdateTime()

BucketInfo.hashCode()

BucketInfo.newBuilder(String)

BucketInfo.of(String)

BucketInfo.requesterPays()

BucketInfo.retentionPolicyIsLocked()

BucketInfo.toBuilder()

BucketInfo.toString()

BucketInfo.versioningEnabled()

Object.clone()

Object.finalize()

Object.getClass()

Object.notify()

Object.notifyAll()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Methods

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

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

Name	Description
blob	`String` a blob name
content	`byte[]` the blob content
options	`BlobTargetOption[]` options for blob creation

Returns

Type	Description
Blob	a complete blob information

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

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

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

Name	Description
blob	`String` a blob name
content	`byte[]` the blob content
contentType	`String` the blob content type
options	`BlobTargetOption[]` options for blob creation

Returns

Type	Description
Blob	a complete blob information

create(String blob, InputStream content, Bucket.BlobWriteOption[] options)

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

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

Name	Description
blob	`String` a blob name
content	`InputStream` the blob content as a stream
options	`BlobWriteOption[]` options for blob creation

Returns

Type	Description
Blob	a complete blob information

create(String blob, InputStream content, String contentType, Bucket.BlobWriteOption[] options)

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

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

Name	Description
blob	`String` a blob name
content	`InputStream` the blob content as a stream
contentType	`String` the blob content type
options	`BlobWriteOption[]` options for blob creation

Returns

Type	Description
Blob	a complete blob information

createAcl(Acl acl)

public Acl createAcl(Acl acl)

Creates a new ACL entry on this bucket.

Example of creating a new ACL entry.


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

Parameter

Name	Description
acl	`Acl`

Returns

Type	Description
Acl

createDefaultAcl(Acl acl)

public Acl createDefaultAcl(Acl acl)

Creates a new default blob ACL entry on this 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.


 Acl acl = bucket.createDefaultAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.READER));

Parameter

Name	Description
acl	`Acl`

Returns

Type	Description
Acl

delete(Bucket.BucketSourceOption[] options)

public boolean delete(Bucket.BucketSourceOption[] options)

Deletes this bucket.

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


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

Parameter

Name	Description
options	`BucketSourceOption[]` bucket delete options

Returns

Type	Description
boolean	`true` if bucket was deleted, `false` if it was not found

deleteAcl(Acl.Entity entity)

public boolean deleteAcl(Acl.Entity entity)

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

Example of deleting the ACL entry for an entity.


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

Parameter

Name	Description
entity	`Acl.Entity`

Returns

Type	Description
boolean	`true` if the ACL was deleted, `false` if it was not found

deleteDefaultAcl(Acl.Entity entity)

public boolean deleteDefaultAcl(Acl.Entity entity)

Deletes the default object ACL entry for the specified entity on this 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.


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

Parameter

Name	Description
entity	`Acl.Entity`

Returns

Type	Description
boolean	`true` if the ACL was deleted, `false` if it was not found

equals(Object obj)

public final boolean equals(Object obj)

Parameter

Name	Description
obj	`Object`

Returns

Type	Description
boolean

Overrides

BucketInfo.equals(Object obj)

exists(Bucket.BucketSourceOption[] options)

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
 }

Parameter

Name	Description
options	`BucketSourceOption[]`

Returns

Type	Description
boolean	true if this bucket exists, false otherwise

get(Iterable<String> blobNames)

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

Parameter

Name	Description
blobNames	`Iterable<String>` blobs to get

Returns

Type	Description
List<Blob>	an immutable list of `Blob` objects

get(String blob, Storage.BlobGetOption[] options)

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

Name	Description
blob	`String` name of the requested blob
options	`BlobGetOption[]` blob search options

Returns

Type	Description
Blob

get(String blobName1, String blobName2, String[] blobNames)

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

Name	Description
blobName1	`String` first blob to get
blobName2	`String` second blob to get
blobNames	`String[]` other blobs to get

Returns

Type	Description
List<Blob>	an immutable list of `Blob` objects

getAcl(Acl.Entity entity)

public Acl getAcl(Acl.Entity entity)

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

Example of getting the ACL entry for an entity.


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

Parameter

Name	Description
entity	`Acl.Entity`

Returns

Type	Description
Acl

getDefaultAcl(Acl.Entity entity)

public Acl getDefaultAcl(Acl.Entity entity)

Returns the default object ACL entry for the specified entity on this 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.


 Acl acl = bucket.getDefaultAcl(User.ofAllAuthenticatedUsers());

Parameter

Name	Description
entity	`Acl.Entity`

Returns

Type	Description
Acl

getStorage()

public Storage getStorage()

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

Returns

Type	Description
Storage

hashCode()

public final int hashCode()

Returns

Type	Description
int

Overrides

BucketInfo.hashCode()

list(Storage.BlobListOption[] options)

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

Returns the paginated list of Blob in this bucket.

Example of listing the blobs in the bucket.


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

Parameter

Name	Description
options	`BlobListOption[]` options for listing blobs

Returns

Type	Description
Page<Blob>

listAcls()

public List<Acl> listAcls()

Lists the ACL entries for this bucket.

Example of listing the ACL entries.


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

Returns

Type	Description
List<Acl>

listDefaultAcls()

public List<Acl> listDefaultAcls()

Lists the default blob ACL entries for this 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.


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

Returns

Type	Description
List<Acl>

lockRetentionPolicy(Storage.BucketTargetOption[] options)

public Bucket lockRetentionPolicy(Storage.BucketTargetOption[] options)

Locks bucket retention policy. Requires a local metageneration value in the request. Review example below.

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

Warning: Once a retention policy is locked, it can't be unlocked, removed, or shortened.

Example of locking a retention policy on a bucket, only if its local metageneration value matches the bucket's service metageneration otherwise a StorageException is thrown.


 String bucketName = "my_unique_bucket";
 Bucket bucket = storage.get(bucketName, BucketGetOption.fields(BucketField.METAGENERATION));
 storage.lockRetentionPolicy(bucket, BucketTargetOption.metagenerationMatch());

Parameter

Name	Description
options	`BucketTargetOption[]`

Returns

Type	Description
Bucket	a `Bucket` object of the locked bucket

reload(Bucket.BucketSourceOption[] options)

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 Bucket#getMetageneration() value, otherwise a StorageException is thrown.


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

Parameter

Name	Description
options	`BucketSourceOption[]` bucket read options

Returns

Type	Description
Bucket	a `Bucket` object with latest information or `null` if not found

toBuilder()

public Bucket.Builder toBuilder()

Returns a builder for the current bucket.

Returns

Type	Description
Bucket.Builder

Overrides

BucketInfo.toBuilder()

update(Storage.BucketTargetOption[] options)

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().setVersioningEnabled(true).build().update();

Parameter

Name	Description
options	`BucketTargetOption[]` update options

Returns

Type	Description
Bucket	a `Bucket` object with updated information

updateAcl(Acl acl)

public Acl updateAcl(Acl acl)

Updates an ACL entry on this bucket.

Example of updating a new ACL entry.


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

Parameter

Name	Description
acl	`Acl`

Returns

Type	Description
Acl

updateDefaultAcl(Acl acl)

public Acl updateDefaultAcl(Acl acl)

Updates a default blob ACL entry on this 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.


 Acl acl = bucket.updateDefaultAcl(Acl.of(User.ofAllAuthenticatedUsers(), Acl.Role.OWNER));

Parameter

Name	Description
acl	`Acl`

Returns

Type	Description
Acl