# FileWriteChannel
Date: 2012-02-24

## 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