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