1 /*
2  * SeekableInputStream
3  *
4  * Author: Lasse Collin <lasse.collin@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      */
skip(long n)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      */
length()60     public abstract long length() throws IOException;
61 
62     /**
63      * Gets the current position in the stream.
64      */
position()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      */
seek(long pos)80     public abstract void seek(long pos) throws IOException;
81 }
82