Home | History | Annotate | Download | only in xz 
      1 /*
      2  * SeekableInputStream
      3  *
      4  * Author: Lasse Collin <lasse.collin (at) tukaani.org>
      5  *
      6  * This file has been put into the public domain.
      7  * You can do whatever you want with this file.
      8  */
      9 
     10 package org.tukaani.xz;
     11 
     12 import java.io.InputStream;
     13 import java.io.IOException;
     14 
     15 /**
     16  * Input stream with random access support.
     17  */
     18 public abstract class SeekableInputStream extends InputStream {
     19     /**
     20      * Seeks <code>n</code> bytes forward in this stream.
     21      * <p>
     22      * This will not seek past the end of the file. If the current position
     23      * is already at or past the end of the file, this doesn't seek at all
     24      * and returns <code>0</code>. Otherwise, if skipping <code>n</code> bytes
     25      * would cause the position to exceed the stream size, this will do
     26      * equivalent of <code>seek(length())</code> and the return value will
     27      * be adjusted accordingly.
     28      * <p>
     29      * If <code>n</code> is negative, the position isn't changed and
     30      * the return value is <code>0</code>. It doesn't seek backward
     31      * because it would conflict with the specification of
     32      * {@link java.io.InputStream#skip(long) InputStream.skip}.
     33      *
     34      * @return      <code>0</code> if <code>n</code> is negative,
     35      *              less than <code>n</code> if skipping <code>n</code>
     36      *              bytes would seek past the end of the file,
     37      *              <code>n</code> otherwise
     38      *
     39      * @throws      IOException might be thrown by {@link #seek(long)}
     40      */
     41     public long skip(long n) throws IOException {
     42         if (n <= 0)
     43             return 0;
     44 
     45         long size = length();
     46         long pos = position();
     47         if (pos >= size)
     48             return 0;
     49 
     50         if (size - pos < n)
     51             n = size - pos;
     52 
     53         seek(pos + n);
     54         return n;
     55     }
     56 
     57     /**
     58      * Gets the size of the stream.
     59      */
     60     public abstract long length() throws IOException;
     61 
     62     /**
     63      * Gets the current position in the stream.
     64      */
     65     public abstract long position() throws IOException;
     66 
     67     /**
     68      * Seeks to the specified absolute position in the stream.
     69      * <p>
     70      * Seeking past the end of the file should be supported by the subclasses
     71      * unless there is a good reason to do otherwise. If one has seeked
     72      * past the end of the stream, <code>read</code> will return
     73      * <code>-1</code> to indicate end of stream.
     74      *
     75      * @param       pos         new read position in the stream
     76      *
     77      * @throws      IOException if <code>pos</code> is negative or if
     78      *                          a stream-specific I/O error occurs
     79      */
     80     public abstract void seek(long pos) throws IOException;
     81 }
     82