com.google.appengine.api.files

## Interface FileWriteChannel

- All Superinterfaces:
    java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, java.nio.channels.WritableByteChannel

      public interface FileWriteChannel
      extends java.nio.channels.WritableByteChannel

  A `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 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. Just like `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.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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