com.google.appengine.api.files

## Interface FileReadChannel

- All Superinterfaces:
    java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, java.nio.channels.ReadableByteChannel
  All Known Implementing Classes:
    BufferedFileReadChannelImpl

      public interface FileReadChannel
      extends java.nio.channels.ReadableByteChannel

  A `ReadableByteChannel` for reading bytes from an `AppEngineFile`.

  A `FileReadChannel` has a current position within its file which can be both `queried` and `modified`.

  An instance of `FileReadChannel` is obtained via the method `FileService.openReadChannel(AppEngineFile, boolean)`.

  A `FileReadChannel` 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 `FileReadChannel` should not be cached between requests. Instead, `close` the channel at the end of the request, cache the `AppEngineFile` or just the `path`, and create a new `FileReadChannel` in a later request.

  When a `FileReadChannel` is constructed the underlying file may optionally be locked. Successful aquisition of the lock means that no other App Engine request will be able to read the underlying file until the lock is released. If a lock is acquired, it will be released when the method `Channel.close()` is invoked. When the request terminates, `close()` will be invoked implicitly if it has not yet been invoked explicitly. Just like `ReadableByteChannel` If one thread initiates a read operation upon a channel then any other thread that attempts to initiate another read operation will block until the first operation is complete. This also applies to the `position()` and `position(long)` apis.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `position()` Returns this channel's file position;
    `FileReadChannel` | `position(long newPosition)` Sets this channel's file position.

    - ### Methods inherited from interface java.nio.channels.ReadableByteChannel

      `read`

    - ### Methods inherited from interface java.nio.channels.Channel

      `close, isOpen`

- - ### Method Detail

    - #### position

          long position()
                        throws java.io.IOException

      Returns this channel's file position;
      Returns:
        This channel's file position, a non-negative integer counting the number of bytes from the beginning of the file to the current position
      Throws:
        `java.io.IOException` - If any problem occurs

    - #### position

          FileReadChannel position(long newPosition)
                                   throws java.io.IOException

      Sets this channel's file position.

      Setting the position to a value that is greater than the file's size will not result in an exception. A later attempt to read bytes at such a position will immediately return an end-of-file indication.

      Parameters:
        `newPosition` - The new position, a non-negative integer counting the number of bytes from the beginning of the file
      Returns:
        This channel
      Throws:
        `java.lang.IllegalArgumentException` - If the new position is negative
        `java.io.IOException` - If any other problem occurs