Class Bucket
- All Implemented Interfaces:
Serializable
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:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Class for specifying blob target options whenBucket
methods are used.static class
Class for specifying blob write options whenBucket
methods are used.static class
Class for specifying bucket source options whenBucket
methods are used.static class
Builder forBucket
.Nested classes/interfaces inherited from class com.google.cloud.storage.BucketInfo
BucketInfo.AgeDeleteRule, BucketInfo.Autoclass, BucketInfo.CreatedBeforeDeleteRule, BucketInfo.CustomPlacementConfig, BucketInfo.DeleteRule, BucketInfo.HierarchicalNamespace, BucketInfo.IamConfiguration, BucketInfo.IsLiveDeleteRule, BucketInfo.LifecycleRule, BucketInfo.Logging, BucketInfo.NumNewerVersionsDeleteRule, BucketInfo.ObjectRetention, BucketInfo.PublicAccessPrevention, BucketInfo.SoftDeletePolicy
-
Method Summary
Modifier and TypeMethodDescriptionDrop the heldStorage
instance.create
(String blob, byte[] content, Bucket.BlobTargetOption... options) Creates a new blob in this bucket.create
(String blob, byte[] content, String contentType, Bucket.BlobTargetOption... options) Creates a new blob in this bucket.create
(String blob, InputStream content, Bucket.BlobWriteOption... options) Creates a new blob in this bucket.create
(String blob, InputStream content, String contentType, Bucket.BlobWriteOption... options) Creates a new blob in this bucket.Creates a new ACL entry on this bucket.createDefaultAcl
(Acl acl) Creates a new default blob ACL entry on this bucket.boolean
delete
(Bucket.BucketSourceOption... options) Deletes this bucket.boolean
deleteAcl
(Acl.Entity entity) Deletes the ACL entry for the specified entity on this bucket.boolean
deleteDefaultAcl
(Acl.Entity entity) Deletes the default object ACL entry for the specified entity on this bucket.final boolean
boolean
exists
(Bucket.BucketSourceOption... options) Checks if this bucket exists.Returns a list of requested blobs in this bucket.get
(String blob, Storage.BlobGetOption... options) Returns the requested blob in this bucket ornull
if not found.get
(String blob, Long generation, Storage.BlobGetOption... options) Returns the requested blob in this bucket of a specific generation ornull
if not found.Returns a list of requested blobs in this bucket.getAcl
(Acl.Entity entity) Returns the ACL entry for the specified entity on this bucket ornull
if not found.getDefaultAcl
(Acl.Entity entity) Returns the default object ACL entry for the specified entity on this bucket ornull
if not found.Returns the bucket'sStorage
object used to issue requests.final int
hashCode()
com.google.api.gax.paging.Page<Blob>
list
(Storage.BlobListOption... options) Returns the paginated list ofBlob
in this bucket.listAcls()
Lists the ACL entries for this bucket.Lists the default blob ACL entries for this bucket.lockRetentionPolicy
(Storage.BucketTargetOption... options) Locks bucket retention policy.reload
(Bucket.BucketSourceOption... options) Fetches current bucket's latest information.Returns a builder for the current bucket.update
(Storage.BucketTargetOption... options) Updates the bucket's information.Updates an ACL entry on this bucket.updateDefaultAcl
(Acl acl) Updates a default blob ACL entry on this bucket.Methods inherited from class com.google.cloud.storage.BucketInfo
getAcl, getAutoclass, getCors, getCreateTime, getCreateTimeOffsetDateTime, getCustomPlacementConfig, getDefaultAcl, getDefaultEventBasedHold, getDefaultKmsKeyName, getDeleteRules, getEtag, getGeneratedId, getHierarchicalNamespace, getIamConfiguration, getIndexPage, getLabels, getLifecycleRules, getLocation, getLocationType, getLogging, getMetageneration, getName, getNotFoundPage, getObjectRetention, getOwner, getRetentionEffectiveTime, getRetentionEffectiveTimeOffsetDateTime, getRetentionPeriod, getRetentionPeriodDuration, getRpo, getSelfLink, getSoftDeletePolicy, getStorageClass, getUpdateTime, getUpdateTimeOffsetDateTime, newBuilder, of, requesterPays, retentionPolicyIsLocked, toString, versioningEnabled
-
Method Details
-
exists
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
Fetches current bucket's latest information. Returnsnull
if the bucket does not exist.Example of getting the bucket's latest information, if its generation does not match the
BucketInfo.getMetageneration()
value, otherwise aStorageException
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 ornull
if not found - Throws:
StorageException
- upon failure
-
update
Updates the bucket's information. Bucket's name cannot be changed. A newBucket
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 themetagenerationMatch
option:bucket.update(BucketTargetOption.metagenerationMatch())
Example of updating the bucket's information.
Bucket updatedBucket = bucket.toBuilder().setVersioningEnabled(true).build().update();
- Parameters:
options
- update options- Returns:
- a
Bucket
object with updated information - Throws:
StorageException
- upon failure
-
delete
Deletes this bucket.Example of deleting the bucket, if its metageneration matches the
BucketInfo.getMetageneration()
value, otherwise aStorageException
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
@TransportCompatibility({HTTP,GRPC}) public com.google.api.gax.paging.Page<Blob> list(Storage.BlobListOption... options) Returns the paginated list ofBlob
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 }
- Parameters:
options
- options for listing blobs- Throws:
StorageException
- upon failure
-
get
Returns the requested blob in this bucket ornull
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 bloboptions
- blob search options- Throws:
StorageException
- upon failure
-
get
@TransportCompatibility({HTTP,GRPC}) public Blob get(String blob, Long generation, Storage.BlobGetOption... options) Returns the requested blob in this bucket of a specific generation ornull
if not found.Example of getting a blob of a specific in the bucket.
String blobName = "my_blob_name"; long generation = 42; Blob blob = bucket.get(blobName, generation);
- Parameters:
blob
- name of the requested blobgeneration
- the generation to getoptions
- blob search options- Throws:
StorageException
- upon failure
-
get
@TransportCompatibility(HTTP) 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 getblobName2
- second blob to getblobNames
- other blobs to get- Returns:
- an immutable list of
Blob
objects - Throws:
StorageException
- upon failure
-
get
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
@TransportCompatibility({HTTP,GRPC}) public Blob create(String blob, byte[] content, String contentType, Bucket.BlobTargetOption... options) Creates a new blob in this bucket. Direct upload is used to uploadcontent
. For large content,Blob.writer(com.google.cloud.storage.Storage.BlobWriteOption...)
is recommended as it uses resumable upload. MD5 and CRC32C hashes ofcontent
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 namecontent
- the blob contentcontentType
- the blob content typeoptions
- options for blob creation- Returns:
- a complete blob information
- Throws:
StorageException
- upon failure
-
create
@TransportCompatibility({HTTP,GRPC}) public Blob create(String blob, InputStream content, String contentType, Bucket.BlobWriteOption... options) Creates a new blob in this bucket. Direct upload is used to uploadcontent
. 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 namecontent
- the blob content as a streamcontentType
- the blob content typeoptions
- options for blob creation- Returns:
- a complete blob information
- Throws:
StorageException
- upon failure
-
create
@TransportCompatibility({HTTP,GRPC}) public Blob create(String blob, byte[] content, Bucket.BlobTargetOption... options) Creates a new blob in this bucket. Direct upload is used to uploadcontent
. For large content,Blob.writer(com.google.cloud.storage.Storage.BlobWriteOption...)
is recommended as it uses resumable upload. MD5 and CRC32C hashes ofcontent
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 namecontent
- the blob contentoptions
- options for blob creation- Returns:
- a complete blob information
- Throws:
StorageException
- upon failure
-
create
@TransportCompatibility({HTTP,GRPC}) public Blob create(String blob, InputStream content, Bucket.BlobWriteOption... options) Creates a new blob in this bucket. Direct upload is used to uploadcontent
. 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 namecontent
- the blob content as a streamoptions
- options for blob creation- Returns:
- a complete blob information
- Throws:
StorageException
- upon failure
-
getAcl
Returns the ACL entry for the specified entity on this bucket ornull
if not found.Example of getting the ACL entry for an entity.
Acl acl = bucket.getAcl(User.ofAllAuthenticatedUsers());
- Throws:
StorageException
- upon failure
-
deleteAcl
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 }
- Returns:
true
if the ACL was deleted,false
if it was not found- Throws:
StorageException
- upon failure
-
createAcl
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));
- Throws:
StorageException
- upon failure
-
updateAcl
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));
- Throws:
StorageException
- upon failure
-
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 }
- Throws:
StorageException
- upon failure
-
getDefaultAcl
Returns the default object ACL entry for the specified entity on this bucket ornull
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());
- Throws:
StorageException
- upon failure
-
deleteDefaultAcl
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 }
- Returns:
true
if the ACL was deleted,false
if it was not found- Throws:
StorageException
- upon failure
-
createDefaultAcl
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));
- Throws:
StorageException
- upon failure
-
updateDefaultAcl
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));
- Throws:
StorageException
- upon failure
-
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 }
- Throws:
StorageException
- upon failure
-
lockRetentionPolicy
@TransportCompatibility({HTTP,GRPC}) 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
Storage.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());
- Returns:
- a
Bucket
object of the locked bucket - Throws:
StorageException
- upon failure
-
getStorage
Returns the bucket'sStorage
object used to issue requests. -
toBuilder
Description copied from class:BucketInfo
Returns a builder for the current bucket.- Overrides:
toBuilder
in classBucketInfo
-
equals
- Overrides:
equals
in classBucketInfo
-
hashCode
public final int hashCode()- Overrides:
hashCode
in classBucketInfo
-
asBucketInfo
Drop the heldStorage
instance.- Since:
- 2.14.0 This new api is in preview and is subject to breaking changes.
-