Package com.google.cloud.storage (2.24.0)

A client for Cloud Storage - Unified object storage.

Here's a simple usage example the Java Storage client. This example shows how to create a Storage object.


 Storage storage = StorageOptions.getDefaultInstance().getService();
 BlobId blobId = BlobId.of("bucket", "blob_name");
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 Blob blob = storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));

This second example shows how to update an object's content if the object exists.


 Storage storage = StorageOptions.getDefaultInstance().getService();
 BlobId blobId = BlobId.of("bucket", "blob_name");
 Blob blob = storage.get(blobId);
 if (blob != null) {
   byte[] prevContent = blob.getContent();
   System.out.println(new String(prevContent, UTF_8));
   WritableByteChannel channel = blob.writer();
   channel.write(ByteBuffer.wrap("Updated content".getBytes(UTF_8)));
   channel.close();
 }

For more detailed code examples, see the sample library.

When using google-cloud from outside of App/Compute Engine, you have to specify a project ID and provide credentials.

Operations in this library are generally thread safe, except for the use of BlobReadChannel and BlobWriteChannel. See Also: Google Cloud Storage

Classes

Acl

Access Control List for buckets or blobs. See Also: About Access Control Lists

Acl.Entity

Base class for Access Control List entities.

An object in Google Cloud Storage. A Blob object includes the BlobId instance, the set of properties inherited from the BlobInfo class and the Storage instance. The class provides methods to perform operations on the object. Reading a property value does not issue any RPC calls. The object content is not stored within the Blob instance. Operations that access the content issue one or multiple RPC calls, depending on the content size.

Objects of this class are immutable. Operations that modify the blob like #update and #copyTo return a new object. Any changes to the object in Google Cloud Storage made after creation of the Blob are not visible in the Blob. To get a Blob object with the most recent information use #reload.

Example of getting the content of the object in Google Cloud Storage:


 BlobId blobId = BlobId.of(bucketName, blobName);
 Blob blob = storage.get(blobId);
 long size = blob.getSize(); // no RPC call is required
 byte[] content = blob.getContent(); // one or multiple RPC calls will be issued

Blob.BlobSourceOption

Class for specifying blob source options when Blob methods are used.

Blob.Builder

Builder for Blob.

BlobId

Google Storage Object identifier. A BlobId object includes the name of the containing bucket, the blob's name and possibly the blob's generation. If #getGeneration() is null the identifier refers to the latest blob's generation.

BlobInfo

Information about an object in Google Cloud Storage. A BlobInfo object includes the BlobId instance and the set of properties, such as the blob's access control configuration, user provided metadata, the CRC32C checksum, etc. Instances of this class are used to create a new object in Google Cloud Storage or update the properties of an existing object. To deal with existing Storage objects the API includes the Blob class which extends BlobInfo and declares methods to perform operations on the object. Neither BlobInfo nor Blob instances keep the object content, just the object properties.

Example of usage BlobInfo to create an object in Google Cloud Storage:


 BlobId blobId = BlobId.of(bucketName, blobName);
 BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
 Blob blob = storage.create(blobInfo, "Hello, world".getBytes(StandardCharsets.UTF_8));

BlobInfo.Builder

Builder for BlobInfo.

BlobInfo.CustomerEncryption

Objects of this class hold information on the customer-supplied encryption key, if the blob is encrypted using such a key.

BlobInfo.ImmutableEmptyMap<K,V>

This class is meant for internal use only. Users are discouraged from using this class.

Bucket

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.

Bucket.BlobTargetOption

Class for specifying blob target options when Bucket methods are used.

Bucket.BlobWriteOption

Class for specifying blob write options when Bucket methods are used.

Bucket.BucketSourceOption

Class for specifying bucket source options when Bucket methods are used.

Bucket.Builder

Builder for Bucket.

BucketInfo

Google Storage bucket metadata; See Also: Concepts and Terminology

BucketInfo.AgeDeleteRule (deprecated)

Deprecated. Use a LifecycleRule with a DeleteLifecycleAction and use LifecycleCondition.Builder.setAge instead.

For example, new DeleteLifecycleAction(1) is equivalent to new LifecycleRule( LifecycleAction.newDeleteAction(), LifecycleCondition.newBuilder().setAge(1).build()))

Delete rule class that sets a Time To Live for blobs in the bucket. See Also: Object Lifecycle Management

BucketInfo.Autoclass

BucketInfo.Autoclass.Builder

BucketInfo.Builder

Builder for BucketInfo.

BucketInfo.CreatedBeforeDeleteRule (deprecated)

Deprecated. Use a LifecycleRule with an action DeleteLifecycleAction and a condition LifecycleCondition.Builder.setCreatedBefore instead.

Delete rule class for blobs in the bucket that have been created before a certain date. See Also: Object Lifecycle Management

BucketInfo.CustomPlacementConfig

The bucket's custom placement configuration for Custom Dual Regions. If using location is also required.

BucketInfo.CustomPlacementConfig.Builder

BucketInfo.DeleteRule (deprecated)

Deprecated. Use a LifecycleRule with a DeleteLifecycleAction and a LifecycleCondition which is equivalent to a subclass of DeleteRule instead.

Base class for bucket's delete rules. Allows to configure automatic deletion of blobs and blobs versions. See Also: Object Lifecycle Management

BucketInfo.IamConfiguration

The Bucket's IAM Configuration. See Also: public-access-prevention, uniform bucket-level access

BucketInfo.IamConfiguration.Builder

Builder for IamConfiguration

BucketInfo.IsLiveDeleteRule (deprecated)

Deprecated. Use a LifecycleRule with a DeleteLifecycleAction and a condition LifecycleCondition.Builder.setIsLive instead.

Delete rule class to distinguish between live and archived blobs. See Also: Object Lifecycle Management

BucketInfo.LifecycleRule

Lifecycle rule for a bucket. Allows supported Actions, such as deleting and changing storage class, to be executed when certain Conditions are met.

Versions 1.50.0-1.111.2 of this library don’t support the CustomTimeBefore, DaysSinceCustomTime, DaysSinceNoncurrentTime and NoncurrentTimeBefore lifecycle conditions. To read GCS objects with those lifecycle conditions, update your Java client library to the latest version. See Also: Object Lifecycle Management

BucketInfo.LifecycleRule.AbortIncompleteMPUAction

BucketInfo.LifecycleRule.DeleteLifecycleAction

BucketInfo.LifecycleRule.LifecycleAction

Base class for the Action to take when a Lifecycle Condition is met. Supported Actions are expressed as subclasses of this class, accessed by static factory methods.

BucketInfo.LifecycleRule.LifecycleCondition

Condition for a Lifecycle rule, specifies under what criteria an Action should be executed. See Also: Object Lifecycle Management

BucketInfo.LifecycleRule.LifecycleCondition.Builder

Builder for LifecycleCondition.

BucketInfo.LifecycleRule.SetStorageClassLifecycleAction

BucketInfo.Logging

The bucket's logging configuration, which defines the destination bucket and optional name prefix for the current bucket's logs.

BucketInfo.Logging.Builder

BucketInfo.NumNewerVersionsDeleteRule (deprecated)

Deprecated. Use a LifecycleRule with a DeleteLifecycleAction and a condition LifecycleCondition.Builder.setNumberOfNewerVersions instead.

Delete rule class for versioned blobs. Specifies when to delete a blob's version according to the number of available newer versions for that blob. See Also: Object Lifecycle Management

CanonicalExtensionHeadersSerializer

Canonical extension header serializer. See Also: Canonical Extension Headers

CopyWriter

Google Storage blob copy writer. A CopyWriter object allows to copy 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 class holds the result of a copy request. If source and destination blobs share the same location and storage class the copy is completed in one RPC call otherwise one or more #copyChunk calls are necessary to complete the copy. In addition, CopyWriter#getResult() can be used to automatically complete the copy and return information on the newly created blob. See Also: Rewrite

Cors

Cross-Origin Resource Sharing (CORS) configuration for a bucket. See Also: Cross-Origin Resource Sharing (CORS)

Cors.Builder

CORS configuration builder.

Cors.Origin

Class for a CORS origin.

GrpcStorageOptions

GrpcStorageOptions.Builder

GrpcStorageOptions.GrpcStorageDefaults

GrpcStorageOptions.GrpcStorageFactory

Internal implementation detail, only public to allow for java.io.Serializable compatibility in com.google.cloud.ServiceOptions.

To access an instance of this class instead use GrpcStorageOptions.defaults().getDefaultServiceFactory(). See Also: GrpcStorageOptions.GrpcStorageDefaults#getDefaultServiceFactory(), GrpcStorageOptions#defaults()

GrpcStorageOptions.GrpcStorageRpcFactory

Internal implementation detail, only public to allow for java.io.Serializable compatibility in com.google.cloud.ServiceOptions.

To access an instance of this class instead use GrpcStorageOptions.defaults().getDefaultRpcFactory(). See Also: GrpcStorageOptions.GrpcStorageDefaults#getDefaultRpcFactory(), GrpcStorageOptions#defaults()

HmacKey

HMAC key for a service account.

HmacKey.Builder

Builder for HmacKey objects. *

HmacKey.HmacKeyMetadata

The metadata for a service account HMAC key. This class holds all data associated with an HMAC key other than the secret key.

HmacKey.HmacKeyMetadata.Builder

Builder for HmacKeyMetadata objects. *

HttpCopyWriter

HttpMethod

Http method supported by Storage service.

HttpStorageOptions

HttpStorageOptions.Builder

HttpStorageOptions.HttpStorageDefaults

HttpStorageOptions.HttpStorageFactory

Internal implementation detail, only public to allow for java.io.Serializable.

To access an instance of this class instead use HttpStorageOptions.defaults().getDefaultServiceFactory(). See Also: HttpStorageOptions#defaults(), HttpStorageDefaults#getDefaultServiceFactory()

HttpStorageOptions.HttpStorageRpcFactory

Internal implementation detail, only public to allow for java.io.Serializable.

To access an instance of this class instead use HttpStorageOptions.defaults().getDefaultRpcFactory(). See Also: HttpStorageDefaults#getDefaultRpcFactory(), HttpStorageOptions#defaults()

Notification

The class representing Pub/Sub notifications for the Storage. See pubsub-notifications for details.

Notification.Builder

Builder for Notification.

NotificationInfo

The class representing Pub/Sub Notification metadata for the Storage.

NotificationInfo.Builder

Builder for NotificationInfo.

NotificationInfo.BuilderImpl

Builder for NotificationInfo.

Option<O>

Base class for Storage operation option.

PostPolicyV4

Presigned V4 post policy. Instances of PostPolicyV4 include a URL and a map of fields that can be specified in an HTML form to submit a POST request to upload an object.

See POST Object for details of upload by using HTML forms.

See Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4, PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...) for example of usage.

PostPolicyV4.ConditionV4

Class for a specific POST policy document condition. See Also: Policy document

PostPolicyV4.PostConditionsV4

A helper class for specifying conditions in a V4 POST Policy document. Used in: Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4, PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...). See Also: Policy document

PostPolicyV4.PostConditionsV4.Builder

PostPolicyV4.PostFieldsV4

A helper class to define fields to be specified in a V4 POST request. Instance of this class helps to construct PostPolicyV4 objects. Used in: Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4, PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...). See Also: POST Object Form fields


 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

StorageOptions.DefaultStorageFactory (deprecated)

Deprecated. Use HttpStorageFactory

StorageOptions.DefaultStorageRpcFactory (deprecated)

Deprecated. Use HttpStorageRpcFactory

StorageRoles

IAM roles specific to Storage. An overview of the permissions available to Storage and the capabilities they grant can be found in the Google Cloud Storage IAM documentation.

A factory class which is used to provide access to ResultRetryAlgorithm for idempotent and non-idempotent calls made via Storage. Before Storage performs an operation it will determine if the operation is idempotent and select the appropriate ResultRetryAlgorithm to use for that invocation. See Also: #getDefaultStorageRetryStrategy(), #getUniformStorageRetryStrategy()

Exceptions

StorageBatchResult<T>

This class holds a single result of a batch call to Cloud Storage.

StorageException

Storage service exception. See Also: Google Cloud Storage error codes

Annotation Types

TransportCompatibility

Annotation which is used to convey which Cloud Storage API a class or method has compatibility with.

Not all operations are compatible with all transports.