com.google.appengine.api.files
Interface FileWriteChannel

All Superinterfaces:

java.nio.channels.Channel, java.io.Closeable, java.nio.channels.WritableByteChannel

public interface FileWriteChannel
extends java.nio.channels.WritableByteChannel

An WritableByteChannel for appending bytes to an AppEngineFile. In addition to the behavior specified by WritableByteChannel this class also exposes a sequence key feature which may be used to recover from certain types of failures.

An instance of FileWriteChannel is obtained from the method FileService.openWriteChannel(AppEngineFile, boolean).

A FileWriteChannel is associated with a single App Engine request and may not be used outside of the request in which it is constructed. Therefore an instance of FileWriteChannel should not be cached between requests. Instead, close the channel at the end of the request (without finalizing), cache the AppEngineFile or just the path, and create a new FileWriteChannel in a later request.

When the channel is opened, the underlying underlying file may be locked. Successful aquisition of the lock means that no other App Engine request will be able to read or write the underlying file until the lock is released.

One of the close() methods should be invoked before the request terminates. The version closeFinally() causes the underlying file to be finalized. Once a file is finalized it may be read, and it may not be written. In order to finalize a file it is necessary to hold the lock for the file. If no close() method is invoked before the request terminates then Channel.close() will implicitly be invoked and so the file will not be finalized. All of the close() methods have the side-effect of releasing a lock if one is held.

Method Summary

void	closeFinally() Close the channel and finalize the file.
int	write(java.nio.ByteBuffer src, java.lang.String sequenceKey) As specified by WritableByteChannel.write(ByteBuffer) with the addition of the sequenceKey parameter.

Methods inherited from interface java.nio.channels.WritableByteChannel

write

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

write

int write(java.nio.ByteBuffer src,
          java.lang.String sequenceKey)
          throws java.io.IOException

As specified by WritableByteChannel.write(ByteBuffer) with the addition of the sequenceKey parameter. If this parameter is not null then it will be passed to the back end repository and recorded as the last good sequence key if the back end write succeeds. In this case, if the sequenceKey is not strictly lexicographically greater than the last good sequence key the back end has already recorded (if there is one), a KeyOrderingException will be thrown from which the last good sequence key may be retrieved via the method KeyOrderingException.getLastGoodSequenceKey(). By making use of this feedback system it is possible to recover from certain types of failures that it would otherwise be difficult to recover from. For example, if bytes are being written to a file in a series of App Engine Task Queue tasks and one of the tasks is retried, this technique can be used to avoid writing the same bytes twice. As another example, if during a series of writes the back end loses some of the bytes of a file due to a back end system failure, this feedback system may be used to inform the client of the last write after which the data corruption begins, thus enabling the client to resend all bytes after that point.

Throws:

java.io.IOException

closeFinally

void closeFinally()
                  throws java.lang.IllegalStateException,
                         java.io.IOException

Close the channel and finalize the file. After the file is finalized it may be read, and it may no longer be written.

Throws:

java.lang.IllegalStateException - if the current request does not hold the lock for the file

java.io.IOException - if any unexpected problem occurs