java/src/main/com/google/appengine/api/files/RecordReadChannel.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.ByteBuffer;
   7
   8 /**
   9  * A channel for reading records from a {@link FileReadChannel}.
  10  * <p>
  11  * The format of these records is defined by the leveldb log format:
  12  * http://leveldb.googlecode.com/svn/trunk/doc/log_format.txt
  13  * </p>
  14  * <p>
  15  * An instance of {@link RecordReadChannel} may be obtained from the method:
  16  * {@link FileService#openRecordReadChannel(AppEngineFile, boolean)}.
  17  * </p>
  18  *
  19  */
  20 public interface RecordReadChannel {
  21
  22   /**
  23    * Reads a record from the file and returns it in a {@link ByteBuffer}. This ByteBuffer is
  24    * reused, so if the user would like to save the result of {@link #readRecord()}, they need
  25    * to copy the output of this method.
  26    * @return a {@link ByteBuffer} containing the record.
  27    * @throws IOException
  28    */
  29   ByteBuffer readRecord() throws IOException;
  30
  31   /**
  32    * Returns the position in the underlying {@link FileReadChannel}.
  33    * @return the position.
  34    * @throws IOException
  35    */
  36   long position() throws IOException;
  37
  38   /**
  39    * Sets the read position of the underlying {@link FileReadChannel}. The position value should
  40    * only be set using the value obtained from a previous {@link #position()} call.
  41    * @param newPosition the position at which to set the reader.
  42    * @throws IOException
  43    */
  44   void position(long newPosition) throws IOException;
  45 }