java/src/main/com/google/appengine/api/files/FileReadChannel.java

   1 // Copyright 2011 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.files;
   4
   5 import java.io.IOException;
   6 import java.nio.channels.ReadableByteChannel;
   7
   8 /**
   9  * A {@code ReadableByteChannel} for reading bytes from an
  10  * {@link AppEngineFile}.
  11  * <p>
  12  * A {@code FileReadChannel} has a current <i>position</i> within its file which
  13  * can be both {@link #position() queried} and {@link #position(long) modified}.
  14  * <p>
  15  * An instance of {@code FileReadChannel} is obtained via the method
  16  * {@link FileService#openReadChannel(AppEngineFile, boolean)}.
  17  * <p>
  18  * A {@code FileReadChannel} is associated with a single App Engine request and
  19  * may not be used outside of the request in which it is constructed. Therefore
  20  * an instance of {@code FileReadChannel} should not be cached between requests.
  21  * Instead, {@link #close() close } the channel at the end of the request, cache
  22  * the {@code AppEngineFile} or just the {@link AppEngineFile#getFullPath()
  23  * path}, and create a new {@code FileReadChannel} in a later request.
  24  * <p>
  25  * When a {@code FileReadChannel} is constructed the underlying file may
  26  * optionally be <b>locked</b>. Successful aquisition of the lock means that no
  27  * other App Engine request will be able to read the underlying file until the
  28  * lock is released. If a lock is acquired, it will be released when the method
  29  * {@link #close()} is invoked. When the request terminates, {@code close()}
  30  * will be invoked implicitly if it has not yet been invoked explicitly.
  31  *
  32  */
  33 public interface FileReadChannel extends ReadableByteChannel {
  34
  35   /**
  36    * Returns this channel's file position;
  37    *
  38    * @return This channel's file position, a non-negative integer counting the
  39    *         number of bytes from the beginning of the file to the current
  40    *         position
  41    * @throws IOException If any problem occurs
  42    */
  43   public long position() throws IOException;
  44
  45   /**
  46    * Sets this channel's file position.
  47    * <p>
  48    * Setting the position to a value that is greater than the file's size will
  49    * not result in an exception. A later attempt to read bytes at such a
  50    * position will immediately return an end-of-file indication.
  51    *
  52    * @param newPosition The new position, a non-negative integer counting the
  53    *        number of bytes from the beginning of the file
  54    * @return This channel
  55    * @throws IllegalArgumentException If the new position is negative
  56    * @throws IOException If any other problem occurs
  57    */
  58   public FileReadChannel position(long newPosition) throws IOException;
  59
  60 }