@Deprecated public interface FileWriteChannel extends java.nio.channels.WritableByteChannel
WritableByteChannelfor appending bytes to an
AppEngineFile. In addition to the behavior specified by
WritableByteChannelthis class also exposes a
sequence keyfeature which may be used to recover from certain types of failures.
An instance of
FileWriteChannel is obtained from the method
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
close the channel at the end of the
finalizing), cache the
AppEngineFile or just the
create a new
FileWriteChannel in a later request.
When the channel is
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
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.
WritableByteChannel If one thread initiates a write operation upon a channel
then any other thread that attempts to initiate another write operation will block until the
first operation is complete.
|Modifier and Type||Method and Description|
Close the channel and finalize the file.
As specified by
int write(java.nio.ByteBuffer src, java.lang.String sequenceKey) throws java.io.IOException
WritableByteChannel.write(ByteBuffer)with the addition of the
sequenceKeyparameter. If this parameter is not
nullthen 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
sequenceKeyis not strictly lexicographically greater than the last good sequence key the back end has already recorded (if there is one), a
KeyOrderingExceptionwill 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.
void closeFinally() throws java.lang.IllegalStateException, java.io.IOException
java.lang.IllegalStateException- if the current request does not hold the lock for the file
java.io.IOException- if any unexpected problem occurs