com.google.appengine.tools.cloudstorage

Interface GcsService

public interface GcsService

Allows creating and accessing files in Google Cloud Storage. This class uses the RetryParams that were passed to GcsServiceFactory. This is used for all of the methods provided by this class. So an RetriesExhaustedException means that these have failed. Retry logic is handled internally to this class, because while writing to the GcsOutputChannel a request can span the boundaries of segments written to RawGcsService. As a result a write call could partly succeed, making error recovery at an application level next to impossible. Reading, deleting, and gettingMetadata are all idempotent operations. However for symmetry and convenience the RetryParams are applied to these calls as well.

Method Summary

Modifier and Type	Method and Description
void	compose(Iterable<String> source, GcsFilename dest) Concatenates a list of existing files into a new file in the same bucket.
void	copy(GcsFilename source, GcsFilename dest) Copies a file to a specified location.
GcsOutputChannel	createOrReplace(GcsFilename filename, GcsFileOptions options) Creates a new object.
void	createOrReplace(GcsFilename filename, GcsFileOptions options, ByteBuffer src) Creates, writes, and closes a new object with a given content.
boolean	delete(GcsFilename filename) Deletes a file.
GcsFileMetadata	getMetadata(GcsFilename filename)
ListResult	list(String bucket, ListOptions options) Retrieves a list of objects.
GcsInputChannel	openPrefetchingReadChannel(GcsFilename filename, long startPosition, int blockSizeBytes) Same as openReadChannel, but buffers data in memory and prefetches it before it is required to avoid blocking on most read calls.
GcsInputChannel	openReadChannel(GcsFilename filename, long startPosition) Note that the implementation may check if the file exists during the call to openReadChannel, or only check it when the first byte is requested.
void	update(GcsFilename source, GcsFileOptions options) Updates a file's metadata with the given options.

Method Detail

createOrReplace

GcsOutputChannel createOrReplace(GcsFilename filename,
                                 GcsFileOptions options)
                          throws IOException

Creates a new object. The content of the file will only be available after the channel was closed.

Throws:

IOException

createOrReplace

void createOrReplace(GcsFilename filename,
                     GcsFileOptions options,
                     ByteBuffer src)
              throws IOException

Creates, writes, and closes a new object with a given content. This is equivalent to calling createOrReplace(GcsFilename, GcsFileOptions), then GcsOutputChannel.write(ByteBuffer), and finally GcsOutputChannel.close(), but will try to minimize the underlying RPC calls.

Throws:

IOException

openReadChannel

GcsInputChannel openReadChannel(GcsFilename filename,
                                long startPosition)
                         throws IOException

Note that the implementation may check if the file exists during the call to openReadChannel, or only check it when the first byte is requested. If buffering is desired openPrefetchingReadChannel should be called instead.

Throws:

IOException

openPrefetchingReadChannel

GcsInputChannel openPrefetchingReadChannel(GcsFilename filename,
                                           long startPosition,
                                           int blockSizeBytes)

Same as openReadChannel, but buffers data in memory and prefetches it before it is required to avoid blocking on most read calls. If some data is already available locally (prefetched), but not enough to fill the dst buffer, the returned channel might fill only part of it, to avoid blocking. If no data is available locally, reading from the returned channel will block.

getMetadata

GcsFileMetadata getMetadata(GcsFilename filename)
                     throws IOException

Parameters:

filename - The name of the file that you wish to read the metadata of.

Returns:

The metadata associated with the file, or null if the file does not exist.

Throws:

IOException - If for any reason the file can't be read.

delete

boolean delete(GcsFilename filename)
        throws IOException

Deletes a file.

Returns:

true if deleted, false if not found.

Throws:

IOException

compose

void compose(Iterable<String> source,
             GcsFilename dest)
      throws IOException

Concatenates a list of existing files into a new file in the same bucket.

Parameters:

source - the files to compose from

dest - the composed file

Throws:

IOException - if for any reason the file can't be composed

copy

void copy(GcsFilename source,
          GcsFilename dest)
   throws IOException

Copies a file to a specified location.

Parameters:

source - the file to copy from

dest - the file to copy to

Throws:

IOException - if for any reason the file can't be copied

update

void update(GcsFilename source,
            GcsFileOptions options)
     throws IOException

Updates a file's metadata with the given options.

Parameters:

source - the file to update

options - the updated metadata

Throws:

IOException - if for any reason the operation failed

list

ListResult list(String bucket,
                ListOptions options)
         throws IOException

Retrieves a list of objects.

Parameters:

bucket - the name of the bucket.

options - optional directions (could be null) on what to include in the result.

Throws:

IOException - if list operation failed