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 {@link AppEngineFile}.
  10  * <p>
  11  * A {@code FileReadChannel} has a current <i>position</i> within its file which can be both
  12  * {@link #position() queried} and {@link #position(long) modified}.
  13  * <p>
  14  * An instance of {@code FileReadChannel} is obtained via the method
  15  * {@link FileService#openReadChannel(AppEngineFile, boolean)}.
  16  * <p>
  17  * A {@code FileReadChannel} is associated with a single App Engine request and may not be used
  18  * outside of the request in which it is constructed. Therefore an instance of
  19  * {@code FileReadChannel} should not be cached between requests. Instead, {@link #close() close }
  20  * the channel at the end of the request, cache the {@code AppEngineFile} or just the
  21  * {@link AppEngineFile#getFullPath() path}, and create a new {@code FileReadChannel} in a later
  22  * request.
  23  * <p>
  24  * When a {@code FileReadChannel} is constructed the underlying file may optionally be
  25  * <b>locked</b>. Successful aquisition of the lock means that no other App Engine request will be
  26  * able to read the underlying file until the lock is released. If a lock is acquired, it will be
  27  * released when the method {@link #close()} is invoked. When the request terminates,
  28  * {@code close()} will be invoked implicitly if it has not yet been invoked explicitly.
  29  *
  30  * Just like {@link ReadableByteChannel} If one thread initiates a read operation upon a channel
  31  * then any other thread that attempts to initiate another read operation will block until the first
  32  * operation is complete. This also applies to the {@link #position()} and {@link #position(long)}
  33  * apis.
  34  *
  35  */
  36 @Deprecated
  37 public interface FileReadChannel extends ReadableByteChannel {
  38
  39   /**
  40    * Returns this channel's file position;
  41    *
  42    * @return This channel's file position, a non-negative integer counting the
  43    *         number of bytes from the beginning of the file to the current
  44    *         position
  45    * @throws IOException If any problem occurs
  46    */
  47   public long position() throws IOException;
  48
  49   /**
  50    * Sets this channel's file position.
  51    * <p>
  52    * Setting the position to a value that is greater than the file's size will
  53    * not result in an exception. A later attempt to read bytes at such a
  54    * position will immediately return an end-of-file indication.
  55    *
  56    * @param newPosition The new position, a non-negative integer counting the
  57    *        number of bytes from the beginning of the file
  58    * @return This channel
  59    * @throws IllegalArgumentException If the new position is negative
  60    * @throws IOException If any other problem occurs
  61    */
  62   public FileReadChannel position(long newPosition) throws IOException;
  63
  64 }