# FileReadChannel
Date: 2012-02-24

## com.google.appengine.api.files
Interface FileReadChannel

All Superinterfaces:
  java.nio.channels.Channel, java.io.Closeable, java.nio.channels.ReadableByteChannel

    public interface FileReadChannel

extends java.nio.channels.ReadableByteChannel

An `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.

Method Summary
`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