Class SeekableStream
- All Implemented Interfaces:
Closeable
,DataInput
,AutoCloseable
- Direct Known Subclasses:
FileCacheSeekableStream
,ForwardSeekableStream
,ImageInputStreamSeekableStreamAdapter
,MemoryCacheSeekableStream
,SeekableStreamAdapter
java.io.InputStream
that allows seeking
within the input, similar to the RandomAccessFile
class.
Additionally, the DataInput
interface is supported and extended
to include support for little-endian representations of fundamental data
types.
In addition to the familiar methods from InputStream
, the
methods getFilePointer()
, seek()
, are defined as in
the RandomAccessFile
class. The canSeekBackwards()
method will return true
if it is permissible to seek to a
position earlier in the stream than the current value of
getFilePointer()
. Some subclasses of
SeekableStream
guarantee the ability to seek backwards while
others may not offer this feature in the interest of providing greater
efficiency for those users who do not require it.
The DataInput
interface is supported as well. This included
the skipBytes()
and readFully()
methods and a
variety of read
methods for various data types.
Three classes are provided for the purpose of adapting a standard
InputStream
to the SeekableStream
interface.
ForwardSeekableStream
does not allows seeking backwards, but is
inexpensive to use. FileCacheSeekableStream
maintains a copy of
all of the data read from the input in a temporary file; this file will be
discarded automatically when the FileSeekableStream
is
finalized, or when the JVM exits normally.
FileCacheSeekableStream
is intended to be reasonably efficient
apart from the unavoidable use of disk space. In circumstances where the
creation of a temporary file is not possible,
MemoryCacheSeekableStream
may be used.
MemoryCacheSeekableStream
creates a potentially large in-memory
buffer to store the stream data and so should be avoided when possible.
The FileSeekableStream
class wraps a File
or
RandomAccessFile
. It forwards requests to the real underlying
file. It performs a limited amount of caching in order to avoid excessive
I/O costs.
The SegmentedSeekableStream
class performs a different sort
of function. It creates a SeekableStream
from another
SeekableStream
by selecting a series of portions or "segments".
Each segment starts at a specified location within the source
SeekableStream
and extends for a specified number of bytes. The
StreamSegmentMapper
interface and StreamSegment
class may be used to compute the segment positions dynamically.
A convenience methods, wrapInputStream
is provided to
construct a suitable SeekableStream
instance whose data is
supplied by a given InputStream
. The caller, by means of the
canSeekBackwards
parameter, determines whether support for
seeking backwards is required.
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returnstrue
if this object supports calls toseek(pos)
with an offsetpos
smaller than the current offset, as returned bygetFilePointer
.protected void
finalize()
Releases any system resources associated with this stream by calling theclose()
method.abstract long
Returns the current offset in this stream.void
mark
(int readLimit) Marks the current file position for later return using thereset()
method.boolean
Returnstrue
if marking is supported.abstract int
read()
Reads the next byte of data from the input stream.abstract int
read
(byte[] b, int off, int len) Reads up tolen
bytes of data from the input stream into an array of bytes.final boolean
Reads aboolean
from this stream.final byte
readByte()
Reads a signed eight-bit value from this stream.final char
readChar()
Reads a Unicode character from this stream.final char
Reads a Unicode character from this stream in little-endian order.final double
Reads adouble
from this stream.final double
Reads adouble
from this stream in little-endian order.final float
Reads afloat
from this stream.final float
Reads afloat
from this stream in little-endian order.final void
readFully
(byte[] b) Readsb.length
bytes from this stream into the byte array, starting at the current stream pointer.final void
readFully
(byte[] b, int off, int len) Reads exactlylen
bytes from this stream into the byte array, starting at the current stream pointer.final int
readInt()
Reads a signed 32-bit integer from this stream.final int
Reads a signed 32-bit integer from this stream in little-endian order.final String
readLine()
Reads the next line of text from this stream.final long
readLong()
Reads a signed 64-bit integer from this stream.final long
Reads a signed 64-bit integer from this stream in little-endian order.final short
Reads a signed 16-bit number from this stream.final short
Reads a signed 16-bit number from this stream in little-endian order.final int
Reads an unsigned eight-bit number from this stream.final long
Reads an unsigned 32-bit integer from this stream.final long
Reads an unsigned 32-bit integer from this stream in little-endian order.final int
Reads an unsigned 16-bit number from this stream.final int
Reads an unsigned 16-bit number from this stream in little-endian order.final String
readUTF()
Reads in a string from this stream.void
reset()
Returns the file position to its position at the time of the immediately previous call to themark()
method.abstract void
seek
(long pos) Sets the offset, measured from the beginning of this stream, at which the next read occurs.int
skipBytes
(int n) Attempts to skip overn
bytes of input discarding the skipped bytes.static SeekableStream
wrapInputStream
(InputStream is, boolean canSeekBackwards) Returns aSeekableStream
that will read from a givenInputStream
, optionally including support for seeking backwards.Methods inherited from class java.io.InputStream
available, close, nullInputStream, read, readAllBytes, readNBytes, readNBytes, skip, skipNBytes, transferTo
-
Field Details
-
markPos
protected long markPosMarked position, shared byForwardSeekableStream
-
-
Constructor Details
-
SeekableStream
public SeekableStream()
-
-
Method Details
-
wrapInputStream
Returns aSeekableStream
that will read from a givenInputStream
, optionally including support for seeking backwards. This is a convenience method that avoids the need to instantiate specific subclasses ofSeekableStream
depending on the current security model.- Parameters:
is
- AnInputStream
.canSeekBackwards
-true
if the ability to seek backwards in the output is required.- Returns:
- An instance of
SeekableStream
.
-
read
Reads the next byte of data from the input stream. The value byte is returned as anint
in the range0
to255
. If no byte is available because the end of the stream has been reached, the value-1
is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.A subclass must provide an implementation of this method.
- Specified by:
read
in classInputStream
- Returns:
- the next byte of data, or
-1
if the end of the stream is reached. - Throws:
IOException
- if an I/O error occurs.
-
read
Reads up tolen
bytes of data from the input stream into an array of bytes. An attempt is made to read as many aslen
bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer.This method blocks until input data is available, end of stream is detected, or an exception is thrown.
If
b
isnull
, aNullPointerException
is thrown.If
off
is negative, orlen
is negative, oroff+len
is greater than the length of the arrayb
, then anIndexOutOfBoundsException
is thrown.If
len
is zero, then no bytes are read and0
is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of stream, the value-1
is returned; otherwise, at least one byte is read and stored intob
.The first byte read is stored into element
b[off]
, the next one intob[off+1]
, and so on. The number of bytes read is, at most, equal tolen
. Let k be the number of bytes actually read; these bytes will be stored in elementsb[off]
throughb[off+
k-1]
, leaving elementsb[off+
k]
throughb[off+len-1]
unaffected.In every case, elements
b[0]
throughb[off]
and elementsb[off+len]
throughb[b.length-1]
are unaffected.If the first byte cannot be read for any reason other than end of stream, then an
IOException
is thrown. In particular, anIOException
is thrown if the input stream has been closed.A subclass must provide an implementation of this method.
- Overrides:
read
in classInputStream
- Parameters:
b
- the buffer into which the data is read.off
- the start offset in arrayb
at which the data is written.len
- the maximum number of bytes to read.- Returns:
- the total number of bytes read into the buffer, or
-1
if there is no more data because the end of the stream has been reached. - Throws:
IOException
- if an I/O error occurs.
-
mark
public void mark(int readLimit) Marks the current file position for later return using thereset()
method.- Overrides:
mark
in classInputStream
-
reset
Returns the file position to its position at the time of the immediately previous call to themark()
method.- Overrides:
reset
in classInputStream
- Throws:
IOException
-
markSupported
public boolean markSupported()Returnstrue
if marking is supported. Marking is automatically supported forSeekableStream
subclasses that support seeking backeards. Subclasses that do not support seeking backwards but do support marking must override this method.- Overrides:
markSupported
in classInputStream
-
canSeekBackwards
public boolean canSeekBackwards()Returnstrue
if this object supports calls toseek(pos)
with an offsetpos
smaller than the current offset, as returned bygetFilePointer
. -
getFilePointer
Returns the current offset in this stream.- Returns:
- the offset from the beginning of the stream, in bytes, at which the next read occurs.
- Throws:
IOException
- if an I/O error occurs.
-
seek
Sets the offset, measured from the beginning of this stream, at which the next read occurs.If
canSeekBackwards()
returnsfalse
, then settingpos
to an offset smaller than the current value ofgetFilePointer()
will have no effect.- Parameters:
pos
- the offset position, measured in bytes from the beginning of the stream, at which to set the stream pointer.- Throws:
IOException
- ifpos
is less than0
or if an I/O error occurs.
-
readFully
Readsb.length
bytes from this stream into the byte array, starting at the current stream pointer. This method reads repeatedly from the stream until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.- Specified by:
readFully
in interfaceDataInput
- Parameters:
b
- the buffer into which the data is read.- Throws:
EOFException
- if this stream reaches the end before reading all the bytes.IOException
- if an I/O error occurs.
-
readFully
Reads exactlylen
bytes from this stream into the byte array, starting at the current stream pointer. This method reads repeatedly from the stream until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.- Specified by:
readFully
in interfaceDataInput
- Parameters:
b
- the buffer into which the data is read.off
- the start offset of the data.len
- the number of bytes to read.- Throws:
EOFException
- if this stream reaches the end before reading all the bytes.IOException
- if an I/O error occurs.
-
skipBytes
Attempts to skip overn
bytes of input discarding the skipped bytes.This method may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of stream before
n
bytes have been skipped is only one possibility. This method never throws anEOFException
. The actual number of bytes skipped is returned. Ifn
is negative, no bytes are skipped.- Specified by:
skipBytes
in interfaceDataInput
- Parameters:
n
- the number of bytes to be skipped.- Returns:
- the actual number of bytes skipped.
- Throws:
IOException
- if an I/O error occurs.
-
readBoolean
Reads aboolean
from this stream. This method reads a single byte from the stream, starting at the current stream pointer. A value of0
representsfalse
. Any other value representstrue
. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.- Specified by:
readBoolean
in interfaceDataInput
- Returns:
- the
boolean
value read. - Throws:
EOFException
- if this stream has reached the end.IOException
- if an I/O error occurs.
-
readByte
Reads a signed eight-bit value from this stream. This method reads a byte from the stream, starting from the current stream pointer. If the byte read isb
, where0 <= b <= 255
, then the result is:(byte)(b)
This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readByte
in interfaceDataInput
- Returns:
- the next byte of this stream as a signed eight-bit
byte
. - Throws:
EOFException
- if this stream has reached the end.IOException
- if an I/O error occurs.
-
readUnsignedByte
Reads an unsigned eight-bit number from this stream. This method reads a byte from this stream, starting at the current stream pointer, and returns that byte.This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readUnsignedByte
in interfaceDataInput
- Returns:
- the next byte of this stream, interpreted as an unsigned eight-bit number.
- Throws:
EOFException
- if this stream has reached the end.IOException
- if an I/O error occurs.
-
readShort
Reads a signed 16-bit number from this stream. The method reads two bytes from this stream, starting at the current stream pointer. If the two bytes read, in order, areb1
andb2
, where each of the two values is between0
and255
, inclusive, then the result is equal to:(short)((b1 << 8) | b2)
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readShort
in interfaceDataInput
- Returns:
- the next two bytes of this stream, interpreted as a signed 16-bit number.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readShortLE
Reads a signed 16-bit number from this stream in little-endian order. The method reads two bytes from this stream, starting at the current stream pointer. If the two bytes read, in order, areb1
andb2
, where each of the two values is between0
and255
, inclusive, then the result is equal to:(short)((b2 << 8) | b1)
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next two bytes of this stream, interpreted as a signed 16-bit number.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readUnsignedShort
Reads an unsigned 16-bit number from this stream. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
andb2
, where0 <= b1, b2 <= 255
, then the result is equal to:(b1 << 8) | b2
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readUnsignedShort
in interfaceDataInput
- Returns:
- the next two bytes of this stream, interpreted as an unsigned 16-bit integer.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readUnsignedShortLE
Reads an unsigned 16-bit number from this stream in little-endian order. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
andb2
, where0 <= b1, b2 <= 255
, then the result is equal to:(b2 << 8) | b1
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next two bytes of this stream, interpreted as an unsigned 16-bit integer.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readChar
Reads a Unicode character from this stream. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
andb2
, where0 <= b1, b2 <= 255
, then the result is equal to:(char)((b1 << 8) | b2)
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readChar
in interfaceDataInput
- Returns:
- the next two bytes of this stream as a Unicode character.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readCharLE
Reads a Unicode character from this stream in little-endian order. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
andb2
, where0 <= b1, b2 <= 255
, then the result is equal to:(char)((b2 << 8) | b1)
This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next two bytes of this stream as a Unicode character.
- Throws:
EOFException
- if this stream reaches the end before reading two bytes.IOException
- if an I/O error occurs.
-
readInt
Reads a signed 32-bit integer from this stream. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
, andb4
, where0 <= b1, b2, b3, b4 <= 255
, then the result is equal to:(b1 << 24) | (b2 << 16) + (b3 << 8) + b4
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readInt
in interfaceDataInput
- Returns:
- the next four bytes of this stream, interpreted as an
int
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readIntLE
Reads a signed 32-bit integer from this stream in little-endian order. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
, andb4
, where0 <= b1, b2, b3, b4 <= 255
, then the result is equal to:(b4 << 24) | (b3 << 16) + (b2 << 8) + b1
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next four bytes of this stream, interpreted as an
int
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readUnsignedInt
Reads an unsigned 32-bit integer from this stream. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
, andb4
, where0 <= b1, b2, b3, b4 <= 255
, then the result is equal to:(b1 << 24) | (b2 << 16) + (b3 << 8) + b4
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next four bytes of this stream, interpreted as a
long
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readUnsignedIntLE
Reads an unsigned 32-bit integer from this stream in little-endian order. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
, andb4
, where0 <= b1, b2, b3, b4 <= 255
, then the result is equal to:(b4 << 24) | (b3 << 16) + (b2 << 8) + b1
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next four bytes of this stream, interpreted as a
long
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readLong
Reads a signed 64-bit integer from this stream. This method reads eight bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
,b4
,b5
,b6
,b7
, andb8,
where:0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,
then the result is equal to:
((long)b1 << 56) + ((long)b2 << 48) + ((long)b3 << 40) + ((long)b4 << 32) + ((long)b5 << 24) + ((long)b6 << 16) + ((long)b7 << 8) + b8
This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readLong
in interfaceDataInput
- Returns:
- the next eight bytes of this stream, interpreted as a
long
. - Throws:
EOFException
- if this stream reaches the end before reading eight bytes.IOException
- if an I/O error occurs.
-
readLongLE
Reads a signed 64-bit integer from this stream in little-endian order. This method reads eight bytes from the stream, starting at the current stream pointer. If the bytes read, in order, areb1
,b2
,b3
,b4
,b5
,b6
,b7
, andb8,
where:0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,
then the result is equal to:
((long)b1 << 56) + ((long)b2 << 48) + ((long)b3 << 40) + ((long)b4 << 32) + ((long)b5 << 24) + ((long)b6 << 16) + ((long)b7 << 8) + b8
This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next eight bytes of this stream, interpreted as a
long
. - Throws:
EOFException
- if this stream reaches the end before reading eight bytes.IOException
- if an I/O error occurs.
-
readFloat
Reads afloat
from this stream. This method reads anint
value, starting at the current stream pointer, as if by thereadInt
method and then converts thatint
to afloat
using theintBitsToFloat
method in classFloat
.This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readFloat
in interfaceDataInput
- Returns:
- the next four bytes of this stream, interpreted as a
float
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readFloatLE
Reads afloat
from this stream in little-endian order. This method reads anint
value, starting at the current stream pointer, as if by thereadInt
method and then converts thatint
to afloat
using theintBitsToFloat
method in classFloat
.This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next four bytes of this stream, interpreted as a
float
. - Throws:
EOFException
- if this stream reaches the end before reading four bytes.IOException
- if an I/O error occurs.
-
readDouble
Reads adouble
from this stream. This method reads along
value, starting at the current stream pointer, as if by thereadLong
method and then converts thatlong
to adouble
using thelongBitsToDouble
method in classDouble
.This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readDouble
in interfaceDataInput
- Returns:
- the next eight bytes of this stream, interpreted as a
double
. - Throws:
EOFException
- if this stream reaches the end before reading eight bytes.IOException
- if an I/O error occurs.
-
readDoubleLE
Reads adouble
from this stream in little-endian order. This method reads along
value, starting at the current stream pointer, as if by thereadLong
method and then converts thatlong
to adouble
using thelongBitsToDouble
method in classDouble
.This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
- Returns:
- the next eight bytes of this stream, interpreted as a
double
. - Throws:
EOFException
- if this stream reaches the end before reading eight bytes.IOException
- if an I/O error occurs.
-
readLine
Reads the next line of text from this stream. This method successively reads bytes from the stream, starting at the current stream pointer, until it reaches a line terminator or the end of the stream. Each byte is converted into a character by taking the byte's value for the lower eight bits of the character and setting the high eight bits of the character to zero. This method does not, therefore, support the full Unicode character set.A line of text is terminated by a carriage-return character (
'\r'
), a newline character ('\n'
), a carriage-return character immediately followed by a newline character, or the end of the stream. Line-terminating characters are discarded and are not included as part of the string returned.This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is reached, or an exception is thrown.
- Specified by:
readLine
in interfaceDataInput
- Returns:
- the next line of text from this stream, or null if end of stream is encountered before even one byte is read.
- Throws:
IOException
- if an I/O error occurs.
-
readUTF
Reads in a string from this stream. The string has been encoded using a modified UTF-8 format.The first two bytes are read, starting from the current stream pointer, as if by
readUnsignedShort
. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readUTF
in interfaceDataInput
- Returns:
- a Unicode string.
- Throws:
EOFException
- if this stream reaches the end before reading all the bytes.IOException
- if an I/O error occurs.UTFDataFormatException
- if the bytes do not represent valid UTF-8 encoding of a Unicode string.
-
finalize
Releases any system resources associated with this stream by calling theclose()
method.
-