RawGcsService (App Engine Client for Google Cloud Storage 0.6 API)

```
public interface RawGcsService
```
Low-level ("raw") interface to Google Cloud Storage. This interface need not be used or seen by users of Google Cloud Storage. Instead the higher level API GcsService should be used.
Methods throw IOException for connection errors etc. that are retryable, and other exceptions for bad requests and similar errors that should not be retried.
Implementing classes handle authentication through mechanisms not exposed in this interface.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`RawGcsService.ListItemBatch` A batch of list items.
`static interface`	`RawGcsService.RawGcsCreationToken` Immutable token that wraps the information a specific implementation of `RawGcsService` needs to write to an object.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`RawGcsService.RawGcsCreationToken`	`beginObjectCreation(GcsFilename filename, GcsFileOptions options, long timeoutMillis)`
`void`	`composeObject(Iterable<String> source, GcsFilename dest, long timeoutMillis)` Compose a file from given files.
`Future<RawGcsService.RawGcsCreationToken>`	`continueObjectCreationAsync(RawGcsService.RawGcsCreationToken token, ByteBuffer chunk, long timeoutMillis)` Reads all remaining bytes from `chunk` and writes them to the object and offset specified by `token` asynchronously.
`void`	`copyObject(GcsFilename source, GcsFilename dest, GcsFileOptions fileOptions, long timeoutMillis)` Copy source file to dest.
`boolean`	`deleteObject(GcsFilename filename, long timeoutMillis)` Returns true if deleted, false if not found.
`void`	`finishObjectCreation(RawGcsService.RawGcsCreationToken token, ByteBuffer chunk, long timeoutMillis)` Reads all remaining bytes from `chunk` and writes them to the object and offset specified by `token`, as the final bytes of the object.
`int`	`getChunkSizeBytes()` Calls to `continueObjectCreationAsync(RawGcsCreationToken, ByteBuffer, long)` need to pass fixed size chunks.
`int`	`getMaxWriteSizeByte()` Returns the max bytes allowed per putObject/finishObject operations.
`GcsFileMetadata`	`getObjectMetadata(GcsFilename filename, long timeoutMillis)` Returns the meta-data for `filename`.
`RawGcsService.ListItemBatch`	`list(String bucket, String prefix, String delimiter, String marker, int maxResults, long timeoutMillis)`
`void`	`putObject(GcsFilename filename, GcsFileOptions options, ByteBuffer content, long timeoutMillis)` Create or replace `filename` with the given `content`.
`Future<GcsFileMetadata>`	`readObjectAsync(ByteBuffer dst, GcsFilename filename, long offset, long timeoutMillis)` Issues a request to the server to retrieve data to fill the provided buffer.

Method Detail

getChunkSizeBytes
```
int getChunkSizeBytes()
```
Calls to continueObjectCreationAsync(RawGcsCreationToken, ByteBuffer, long) need to pass fixed size chunks. This returns the size expected by the implementation.

getMaxWriteSizeByte
```
int getMaxWriteSizeByte()
```
Returns the max bytes allowed per putObject/finishObject operations. Value should always be equal or larger than getChunkSizeBytes().

beginObjectCreation

RawGcsService.RawGcsCreationToken beginObjectCreation(GcsFilename filename,
                                                      GcsFileOptions options,
                                                      long timeoutMillis)
                                               throws IOException

Parameters:: options - null means let Google Cloud Storage use its default
Throws:: IOException

continueObjectCreationAsync
```
Future<RawGcsService.RawGcsCreationToken> continueObjectCreationAsync(RawGcsService.RawGcsCreationToken token,
                                                                      ByteBuffer chunk,
                                                                      long timeoutMillis)
```
Reads all remaining bytes from chunk and writes them to the object and offset specified by token asynchronously.
Returns a future for a new token to be used to continue writing to the object. Does not mutate token.
The number of bytes remaining in chunk must be a nonzero multiple of getChunkSizeBytes() and may be subject to an upper limit that is implementation-dependent.
The calling code is responsible for guaranteeing that the byte sequence written to the object remains identical across retries. (This is because the write may have succeeded on the backend even though an exception was thrown by this method, and writing different data on a retry leaves the object in a bad state.)

finishObjectCreation
```
void finishObjectCreation(RawGcsService.RawGcsCreationToken token,
                          ByteBuffer chunk,
                          long timeoutMillis)
                   throws IOException
```
Reads all remaining bytes from chunk and writes them to the object and offset specified by token, as the final bytes of the object. The object will become readable, and further writes will be rejected.
The number of bytes remaining in chunk may be subject to an upper limit that is implementation-dependent.
On error, does not consume any bytes from chunk. The write may be retried by making another call with the same token. A whole sequence of writes may be retried by using a previous token (this is useful if the calling code crashes and rolls back to an earlier state). In both cases, the calling code is responsible for guaranteeing that the byte sequence written to the object remains identical across retries. (This is because the write may have succeeded on the backend even though an exception was thrown by this method, and writing different data on a retry leaves the object in a bad state.)

Throws:

IOException

putObject

void putObject(GcsFilename filename,
               GcsFileOptions options,
               ByteBuffer content,
               long timeoutMillis)
        throws IOException

Create or replace filename with the given content.

Throws:: IOException

readObjectAsync

Future<GcsFileMetadata> readObjectAsync(ByteBuffer dst,
                                        GcsFilename filename,
                                        long offset,
                                        long timeoutMillis)

Issues a request to the server to retrieve data to fill the provided buffer. The offset may not be negative.

getObjectMetadata

GcsFileMetadata getObjectMetadata(GcsFilename filename,
                                  long timeoutMillis)
                           throws IOException

Returns the meta-data for filename.

Throws:: IOException

deleteObject

boolean deleteObject(GcsFilename filename,
                     long timeoutMillis)
              throws IOException

Returns true if deleted, false if not found.

Throws:: IOException

composeObject

void composeObject(Iterable<String> source,
                   GcsFilename dest,
                   long timeoutMillis)
            throws IOException

Compose a file from given files.

Throws:: IOException

copyObject

void copyObject(GcsFilename source,
                GcsFilename dest,
                GcsFileOptions fileOptions,
                long timeoutMillis)
         throws IOException

Copy source file to dest.

Throws:: IOException

list

RawGcsService.ListItemBatch list(String bucket,
                                 String prefix,
                                 String delimiter,
                                 String marker,
                                 int maxResults,
                                 long timeoutMillis)
                          throws IOException

Throws:: IOException

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2019-11-16.