com.google.appengine.tools.cloudstorage

Interface GcsOutputChannel

All Superinterfaces:

AutoCloseable, Channel, Closeable, Serializable, WritableByteChannel

public interface GcsOutputChannel
extends WritableByteChannel, Serializable

A writable byte channel for writing data to Google Cloud Storage. Write calls will either place the data into an internal buffer or make a synchronous RPC call to write the data. Implementations of this class may further buffer data internally to reduce remote calls. Calling close() will cause any buffers to be flushed and all data written to be stored durably. After this point the file can be read but no longer written to. Not calling close will result in the file not ever being written durably and it will automatically disappear from Google Cloud Storage. This class is serializable, this allows for writing part of a file, serializing the GcsOutputChannel deserializing it, and continuing to write to the same file. The time for which a serialized instance is valid is limited and determined by the Google Cloud Storage service. Note that this is not intended as a way to create multiple GcsOutputChannel objects for the same file. Even if one serializes and deserialzes this object, only one of the original instance or the deserialized instance may be used going forward. Using both in parallel will result in undefined behavior.

Method Summary

Modifier and Type	Method and Description
void	close() Flushes any buffers and writes all data to durable storage.
int	getBufferSizeBytes()
GcsFilename	getFilename() Returns the filename.
void	waitForOutstandingWrites() Blocks until all data that can be written has been written.
int	write(ByteBuffer src)

Methods inherited from interface java.nio.channels.Channel

isOpen

Method Detail

getFilename

GcsFilename getFilename()

Returns the filename.

getBufferSizeBytes

int getBufferSizeBytes()

Returns:

The size of the buffer used internally by this class. (0 if the data is unbuffered)

write

int write(ByteBuffer src)
   throws IOException

Specified by:

write in interface WritableByteChannel

Parameters:

src - A byte buffer that should be written to the end of the file. This buffer may be of any size, but writes are not guaranteed to be durable until close() is called.

Returns:

The number of bytes consumed, which will always be equal to bytes available.

Throws:

IOException - An error occurred writing the data. If an IOException is thrown none or part of the data may have been written. For this reason it may be best to start writing the file from the beginning. This can be avoided by providing a retry policy when constructing this class.

See Also:

WritableByteChannel.write(ByteBuffer)

waitForOutstandingWrites

void waitForOutstandingWrites()
                       throws ClosedByInterruptException,
                              IOException

Blocks until all data that can be written has been written. It is possible that not all data can be written as GCS requires non-final writes to be fixed sizes. This method is most useful to call before serialization, as it will minimize the size of the serialized object.

Throws:

ClosedByInterruptException

IOException

close

void close()
    throws IOException

Flushes any buffers and writes all data to durable storage. Once close() is called further calls to #write(ByteBuffer) will fail. This must be called before the file can be read. If close is not called all data written will be automatically deleted after some time. (This may be desirable if an unrecoverable error occurred while writing the file) Note that calling close will also invalidate any serialized instances of this class, so it should NOT be called if one is planning to serialize this object with the intention to resume writing to the file later.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Channel

Specified by:

close in interface Closeable

Throws:

IOException

See Also:

Channel.close()