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

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

    All Methods Instance Methods Abstract Methods 

    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

Copyright © 2016 Google. All rights reserved.