Class StorageClient (2.3.0)

public class StorageClient implements BackgroundResource

Service Description: ## API Overview and Naming Syntax

The GCS gRPC API allows applications to read and write data through the abstractions of buckets and objects. For a description of these abstractions please see https://cloud.google.com/storage/docs.

Resources are named as follows: - Projects are referred to as they are defined by the Resource Manager API, using strings like projects/123456 or projects/my-string-id. - Buckets are named using string names of the form: projects/{project}/buckets/{bucket} For globally unique buckets, _ may be substituted for the project. - Objects are uniquely identified by their name along with the name of the bucket they belong to, as separate strings in this API. For example:

ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that object names can contain / characters, which are treated as any other character (no special directory semantics).

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:


 try (StorageClient storageClient = StorageClient.create()) {
   StartResumableWriteRequest request =
       StartResumableWriteRequest.newBuilder()
           .setWriteObjectSpec(WriteObjectSpec.newBuilder().build())
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .build();
   StartResumableWriteResponse response = storageClient.startResumableWrite(request);
 }
 

Note: close() needs to be called on the StorageClient object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

The surface of this class includes several types of Java methods for each of the API's methods:

  1. A "flattened" method. With this type of method, the fields of the request type have been converted into function parameters. It may be the case that not all fields are available as parameters, and not every API method will have a flattened method entry point.
  2. A "request object" method. This type of method only takes one parameter, a request object, which must be constructed before the call. Not every API method will have a request object method.
  3. A "callable" method. This type of method takes no parameters and returns an immutable API callable object, which can be used to initiate calls to the service.

See the individual methods for example code.

Many parameters require resource names to be formatted in a particular way. To assist with these names, this class includes a format method for each type of name, and additionally a parse method to extract the individual identifiers contained within names that are returned.

This class can be customized by passing in a custom instance of StorageSettings to create(). For example:

To customize credentials:


 StorageSettings storageSettings =
     StorageSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 StorageClient storageClient = StorageClient.create(storageSettings);
 

To customize the endpoint:


 StorageSettings storageSettings = StorageSettings.newBuilder().setEndpoint(myEndpoint).build();
 StorageClient storageClient = StorageClient.create(storageSettings);
 

Please refer to the GitHub repository's samples for more quickstart code snippets.

Inheritance

java.lang.Object > StorageClient

Implements

BackgroundResource

Static Methods

create()

public static final StorageClient create()

Constructs an instance of StorageClient with default settings.

Returns
Type Description
StorageClient
Exceptions
Type Description
IOException

create(StorageSettings settings)

public static final StorageClient create(StorageSettings settings)

Constructs an instance of StorageClient, using the given settings. The channels are created based on the settings passed in, or defaults for any settings that are not set.

Parameter
Name Description
settings StorageSettings
Returns
Type Description
StorageClient
Exceptions
Type Description
IOException

create(StorageStub stub)

public static final StorageClient create(StorageStub stub)

Constructs an instance of StorageClient, using the given stub for making calls. This is for advanced usage - prefer using create(StorageSettings).

Parameter
Name Description
stub StorageStub
Returns
Type Description
StorageClient

Constructors

StorageClient(StorageSettings settings)

protected StorageClient(StorageSettings settings)

Constructs an instance of StorageClient, using the given settings. This is protected so that it is easy to make a subclass, but otherwise, the static factory methods should be preferred.

Parameter
Name Description
settings StorageSettings

StorageClient(StorageStub stub)

protected StorageClient(StorageStub stub)
Parameter
Name Description
stub StorageStub

Methods

awaitTermination(long duration, TimeUnit unit)

public boolean awaitTermination(long duration, TimeUnit unit)
Parameters
Name Description
duration long
unit TimeUnit
Returns
Type Description
boolean
Exceptions
Type Description
InterruptedException

close()

public final void close()

getSettings()

public final StorageSettings getSettings()
Returns
Type Description
StorageSettings

getStub()

public StorageStub getStub()
Returns
Type Description
StorageStub

isShutdown()

public boolean isShutdown()
Returns
Type Description
boolean

isTerminated()

public boolean isTerminated()
Returns
Type Description
boolean

queryWriteStatus(QueryWriteStatusRequest request)

public final QueryWriteStatusResponse queryWriteStatus(QueryWriteStatusRequest request)

Determines the persisted_size for an object that is being written, which can then be used as the write_offset for the next Write() call.

If the object does not exist (i.e., the object has been deleted, or the first Write() has not yet reached the service), this method returns the error NOT_FOUND.

The client **may** call QueryWriteStatus() at any time to determine how much data has been processed for this object. This is useful if the client is buffering data and needs to know which data can be safely evicted. For any sequence of QueryWriteStatus() calls for a given object name, the sequence of returned persisted_size values will be non-decreasing.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   QueryWriteStatusRequest request =
       QueryWriteStatusRequest.newBuilder()
           .setUploadId("uploadId1563990780")
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .build();
   QueryWriteStatusResponse response = storageClient.queryWriteStatus(request);
 }
 
Parameter
Name Description
request QueryWriteStatusRequest

The request object containing all of the parameters for the API call.

Returns
Type Description
QueryWriteStatusResponse

queryWriteStatus(String uploadId)

public final QueryWriteStatusResponse queryWriteStatus(String uploadId)

Determines the persisted_size for an object that is being written, which can then be used as the write_offset for the next Write() call.

If the object does not exist (i.e., the object has been deleted, or the first Write() has not yet reached the service), this method returns the error NOT_FOUND.

The client **may** call QueryWriteStatus() at any time to determine how much data has been processed for this object. This is useful if the client is buffering data and needs to know which data can be safely evicted. For any sequence of QueryWriteStatus() calls for a given object name, the sequence of returned persisted_size values will be non-decreasing.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   String uploadId = "uploadId1563990780";
   QueryWriteStatusResponse response = storageClient.queryWriteStatus(uploadId);
 }
 
Parameter
Name Description
uploadId String

Required. The name of the resume token for the object whose write status is being requested.

Returns
Type Description
QueryWriteStatusResponse

queryWriteStatusCallable()

public final UnaryCallable<QueryWriteStatusRequest,QueryWriteStatusResponse> queryWriteStatusCallable()

Determines the persisted_size for an object that is being written, which can then be used as the write_offset for the next Write() call.

If the object does not exist (i.e., the object has been deleted, or the first Write() has not yet reached the service), this method returns the error NOT_FOUND.

The client **may** call QueryWriteStatus() at any time to determine how much data has been processed for this object. This is useful if the client is buffering data and needs to know which data can be safely evicted. For any sequence of QueryWriteStatus() calls for a given object name, the sequence of returned persisted_size values will be non-decreasing.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   QueryWriteStatusRequest request =
       QueryWriteStatusRequest.newBuilder()
           .setUploadId("uploadId1563990780")
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .build();
   ApiFuture
Returns
Type Description
UnaryCallable<QueryWriteStatusRequest,QueryWriteStatusResponse>

readObjectCallable()

public final ServerStreamingCallable<ReadObjectRequest,ReadObjectResponse> readObjectCallable()

Reads an object's data.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   ReadObjectRequest request =
       ReadObjectRequest.newBuilder()
           .setBucket("bucket-1378203158")
           .setObject("object-1023368385")
           .setGeneration(305703192)
           .setReadOffset(-715377828)
           .setReadLimit(-164298798)
           .setIfGenerationMatch(-1086241088)
           .setIfGenerationNotMatch(1475720404)
           .setIfMetagenerationMatch(1043427781)
           .setIfMetagenerationNotMatch(1025430873)
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .setReadMask(FieldMask.newBuilder().build())
           .build();
   ServerStream
Returns
Type Description
ServerStreamingCallable<ReadObjectRequest,ReadObjectResponse>

shutdown()

public void shutdown()

shutdownNow()

public void shutdownNow()

startResumableWrite(StartResumableWriteRequest request)

public final StartResumableWriteResponse startResumableWrite(StartResumableWriteRequest request)

Starts a resumable write. How long the write operation remains valid, and what happens when the write operation becomes invalid, are service-dependent.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   StartResumableWriteRequest request =
       StartResumableWriteRequest.newBuilder()
           .setWriteObjectSpec(WriteObjectSpec.newBuilder().build())
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .build();
   StartResumableWriteResponse response = storageClient.startResumableWrite(request);
 }
 
Parameter
Name Description
request StartResumableWriteRequest

The request object containing all of the parameters for the API call.

Returns
Type Description
StartResumableWriteResponse

startResumableWriteCallable()

public final UnaryCallable<StartResumableWriteRequest,StartResumableWriteResponse> startResumableWriteCallable()

Starts a resumable write. How long the write operation remains valid, and what happens when the write operation becomes invalid, are service-dependent.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   StartResumableWriteRequest request =
       StartResumableWriteRequest.newBuilder()
           .setWriteObjectSpec(WriteObjectSpec.newBuilder().build())
           .setCommonObjectRequestParams(CommonObjectRequestParams.newBuilder().build())
           .setCommonRequestParams(CommonRequestParams.newBuilder().build())
           .build();
   ApiFuture
Returns
Type Description
UnaryCallable<StartResumableWriteRequest,StartResumableWriteResponse>

writeObjectCallable()

public final ClientStreamingCallable<WriteObjectRequest,WriteObjectResponse> writeObjectCallable()

Stores a new object and metadata.

An object can be written either in a single message stream or in a resumable sequence of message streams. To write using a single stream, the client should include in the first message of the stream an WriteObjectSpec describing the destination bucket, object, and any preconditions. Additionally, the final message must set 'finish_write' to true, or else it is an error.

For a resumable write, the client should instead call StartResumableWrite() and provide that method an WriteObjectSpec. They should then attach the returned upload_id to the first message of each following call to Create. If there is an error or the connection is broken during the resumable Create(), the client should check the status of the Create() by calling QueryWriteStatus() and continue writing from the returned persisted_size. This may be less than the amount of data the client previously sent.

The service will not view the object as complete until the client has sent a WriteObjectRequest with finish_write set to true. Sending any requests on a stream after sending a request with finish_write set to true will cause an error. The client **should** check the response it receives to determine how much data the service was able to commit and whether the service views the object as complete.

Sample code:


 try (StorageClient storageClient = StorageClient.create()) {
   ApiStreamObserver
Returns
Type Description
ClientStreamingCallable<WriteObjectRequest,WriteObjectResponse>