FileWriteChannel (Google App Engine API for Java)

com.google.appengine.api.files

Interface FileWriteChannel

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

    @Deprecated
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

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method and Description
      void closeFinally()
      Deprecated. 
      Close the channel and finalize the file.
      int write(java.nio.ByteBuffer src, java.lang.String sequenceKey)
      Deprecated. 
      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
        Deprecated. 
        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
        Deprecated. 
        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