public abstract class SeekableStream
extends java.io.InputStream
implements java.io.DataInput
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.
A number of concrete subclasses of SeekableStream
are
supplied in the com.sun.media.jai.codec
package.
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.
Modifier and Type | Field and Description |
---|---|
protected long |
markPos
Marked position, shared by
ForwardSeekableStream |
Constructor and Description |
---|
SeekableStream() |
Modifier and Type | Method and Description |
---|---|
boolean |
canSeekBackwards()
Returns
true if this object supports calls to
seek(pos) with an offset pos smaller
than the current offset, as returned by getFilePointer . |
protected void |
finalize()
Releases any system resources associated with this stream
by calling the
close() method. |
abstract long |
getFilePointer()
Returns the current offset in this stream.
|
void |
mark(int readLimit)
Marks the current file position for later return using
the
reset() method. |
boolean |
markSupported()
Returns
true 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 to
len bytes of data from the input stream into
an array of bytes. |
boolean |
readBoolean()
Reads a
boolean from this stream. |
byte |
readByte()
Reads a signed eight-bit value from this stream.
|
char |
readChar()
Reads a Unicode character from this stream.
|
char |
readCharLE()
Reads a Unicode character from this stream in little-endian order.
|
double |
readDouble()
Reads a
double from this stream. |
double |
readDoubleLE()
Reads a
double from this stream in little-endian order. |
float |
readFloat()
Reads a
float from this stream. |
float |
readFloatLE()
Reads a
float from this stream in little-endian order. |
void |
readFully(byte[] b)
Reads
b.length bytes from this stream into the byte
array, starting at the current stream pointer. |
void |
readFully(byte[] b,
int off,
int len)
Reads exactly
len bytes from this stream into the byte
array, starting at the current stream pointer. |
int |
readInt()
Reads a signed 32-bit integer from this stream.
|
int |
readIntLE()
Reads a signed 32-bit integer from this stream in little-endian order.
|
java.lang.String |
readLine()
Reads the next line of text from this stream.
|
long |
readLong()
Reads a signed 64-bit integer from this stream.
|
long |
readLongLE()
Reads a signed 64-bit integer from this stream in little-endian
order.
|
short |
readShort()
Reads a signed 16-bit number from this stream.
|
short |
readShortLE()
Reads a signed 16-bit number from this stream in little-endian order.
|
int |
readUnsignedByte()
Reads an unsigned eight-bit number from this stream.
|
long |
readUnsignedInt()
Reads an unsigned 32-bit integer from this stream.
|
long |
readUnsignedIntLE()
Reads an unsigned 32-bit integer from this stream in little-endian
order.
|
int |
readUnsignedShort()
Reads an unsigned 16-bit number from this stream.
|
int |
readUnsignedShortLE()
Reads an unsigned 16-bit number from this stream in little-endian order.
|
java.lang.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 the
mark()
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 over
n bytes of input discarding the
skipped bytes. |
static SeekableStream |
wrapInputStream(java.io.InputStream is,
boolean canSeekBackwards)
Returns a
SeekableStream that will read from a
given InputStream , optionally including support
for seeking backwards. |
protected long markPos
ForwardSeekableStream
public static SeekableStream wrapInputStream(java.io.InputStream is, boolean canSeekBackwards)
SeekableStream
that will read from a
given InputStream
, optionally including support
for seeking backwards. This is a convenience method that
avoids the need to instantiate specific subclasses of
SeekableStream
depending on the current security
model.is
- An InputStream
.canSeekBackwards
- true
if the ability to seek
backwards in the output is required.SeekableStream
.public abstract int read() throws java.io.IOException
int
in the range 0
to
255
. 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.
read
in class java.io.InputStream
-1
if the end of the
stream is reached.java.io.IOException
- if an I/O error occurs.public abstract int read(byte[] b, int off, int len) throws java.io.IOException
len
bytes of data from the input stream into
an array of bytes. An attempt is made to read as many as
len
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
is null
, a
NullPointerException
is thrown.
If off
is negative, or len
is negative, or
off+len
is greater than the length of the array
b
, then an IndexOutOfBoundsException
is
thrown.
If len
is zero, then no bytes are read and
0
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 into b
.
The first byte read is stored into element b[off]
, the
next one into b[off+1]
, and so on. The number of bytes read
is, at most, equal to len
. Let k be the number of
bytes actually read; these bytes will be stored in elements
b[off]
through b[off+
k-1]
,
leaving elements b[off+
k]
through
b[off+len-1]
unaffected.
In every case, elements b[0]
through
b[off]
and elements b[off+len]
through
b[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, an
IOException
is thrown if the input stream has been closed.
A subclass must provide an implementation of this method.
read
in class java.io.InputStream
b
- the buffer into which the data is read.off
- the start offset in array b
at which the data is written.len
- the maximum number of bytes to read.-1
if there is no more data because the end of
the stream has been reached.java.io.IOException
- if an I/O error occurs.public void mark(int readLimit)
reset()
method.mark
in class java.io.InputStream
public void reset() throws java.io.IOException
mark()
method.reset
in class java.io.InputStream
java.io.IOException
public boolean markSupported()
true
if marking is supported.
Marking is automatically supported for SeekableStream
subclasses that support seeking backeards. Subclasses that do
not support seeking backwards but do support marking must override
this method.markSupported
in class java.io.InputStream
public boolean canSeekBackwards()
true
if this object supports calls to
seek(pos)
with an offset pos
smaller
than the current offset, as returned by getFilePointer
.public abstract long getFilePointer() throws java.io.IOException
java.io.IOException
- if an I/O error occurs.public abstract void seek(long pos) throws java.io.IOException
If canSeekBackwards()
returns false
,
then setting pos
to an offset smaller than
the current value of getFilePointer()
will have
no effect.
pos
- the offset position, measured in bytes from the
beginning of the stream, at which to set the stream
pointer.java.io.IOException
- if pos
is less than
0
or if an I/O error occurs.public final void readFully(byte[] b) throws java.io.IOException
b.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.readFully
in interface java.io.DataInput
b
- the buffer into which the data is read.java.io.EOFException
- if this stream reaches the end before reading
all the bytes.java.io.IOException
- if an I/O error occurs.public final void readFully(byte[] b, int off, int len) throws java.io.IOException
len
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.readFully
in interface java.io.DataInput
b
- the buffer into which the data is read.off
- the start offset of the data.len
- the number of bytes to read.java.io.EOFException
- if this stream reaches the end before reading
all the bytes.java.io.IOException
- if an I/O error occurs.public int skipBytes(int n) throws java.io.IOException
n
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 an EOFException
.
The actual number of bytes skipped is returned. If n
is negative, no bytes are skipped.
skipBytes
in interface java.io.DataInput
n
- the number of bytes to be skipped.java.io.IOException
- if an I/O error occurs.public final boolean readBoolean() throws java.io.IOException
boolean
from this stream. This method reads a
single byte from the stream, starting at the current stream pointer.
A value of 0
represents
false
. Any other value represents true
.
This method blocks until the byte is read, the end of the stream
is detected, or an exception is thrown.readBoolean
in interface java.io.DataInput
boolean
value read.java.io.EOFException
- if this stream has reached the end.java.io.IOException
- if an I/O error occurs.public final byte readByte() throws java.io.IOException
b
, where
0 <= 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.
readByte
in interface java.io.DataInput
byte
.java.io.EOFException
- if this stream has reached the end.java.io.IOException
- if an I/O error occurs.public final int readUnsignedByte() throws java.io.IOException
This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.
readUnsignedByte
in interface java.io.DataInput
java.io.EOFException
- if this stream has reached the end.java.io.IOException
- if an I/O error occurs.public final short readShort() throws java.io.IOException
b1
and b2
, where each of the two values is
between 0
and 255
, 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.
readShort
in interface java.io.DataInput
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final short readShortLE() throws java.io.IOException
b1
and b2
, where each of the two values is
between 0
and 255
, 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.
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final int readUnsignedShort() throws java.io.IOException
b1
and b2
, where
0 <= 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.
readUnsignedShort
in interface java.io.DataInput
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final int readUnsignedShortLE() throws java.io.IOException
b1
and b2
, where
0 <= 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.
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final char readChar() throws java.io.IOException
b1
and b2
, where
0 <= 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.
readChar
in interface java.io.DataInput
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final char readCharLE() throws java.io.IOException
b1
and b2
, where
0 <= 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.
java.io.EOFException
- if this stream reaches the end before reading
two bytes.java.io.IOException
- if an I/O error occurs.public final int readInt() throws java.io.IOException
b1
,
b2
, b3
, and b4
, where
0 <= 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.
readInt
in interface java.io.DataInput
int
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final int readIntLE() throws java.io.IOException
b1
,
b2
, b3
, and b4
, where
0 <= 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.
int
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final long readUnsignedInt() throws java.io.IOException
b1
,
b2
, b3
, and b4
, where
0 <= 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.
long
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final long readUnsignedIntLE() throws java.io.IOException
b1
,
b2
, b3
, and b4
, where
0 <= 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.
long
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final long readLong() throws java.io.IOException
b1
, b2
, b3
,
b4
, b5
, b6
,
b7
, and b8,
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.
readLong
in interface java.io.DataInput
long
.java.io.EOFException
- if this stream reaches the end before reading
eight bytes.java.io.IOException
- if an I/O error occurs.public final long readLongLE() throws java.io.IOException
b1
, b2
, b3
,
b4
, b5
, b6
,
b7
, and b8,
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.
long
.java.io.EOFException
- if this stream reaches the end before reading
eight bytes.java.io.IOException
- if an I/O error occurs.public final float readFloat() throws java.io.IOException
float
from this stream. This method reads an
int
value, starting at the current stream pointer,
as if by the readInt
method
and then converts that int
to a float
using the intBitsToFloat
method in class
Float
.
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
readFloat
in interface java.io.DataInput
float
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final float readFloatLE() throws java.io.IOException
float
from this stream in little-endian order.
This method reads an
int
value, starting at the current stream pointer,
as if by the readInt
method
and then converts that int
to a float
using the intBitsToFloat
method in class
Float
.
This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.
float
.java.io.EOFException
- if this stream reaches the end before reading
four bytes.java.io.IOException
- if an I/O error occurs.public final double readDouble() throws java.io.IOException
double
from this stream. This method reads a
long
value, starting at the current stream pointer,
as if by the readLong
method
and then converts that long
to a double
using the longBitsToDouble
method in
class Double
.
This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
readDouble
in interface java.io.DataInput
double
.java.io.EOFException
- if this stream reaches the end before reading
eight bytes.java.io.IOException
- if an I/O error occurs.public final double readDoubleLE() throws java.io.IOException
double
from this stream in little-endian order.
This method reads a
long
value, starting at the current stream pointer,
as if by the readLong
method
and then converts that long
to a double
using the longBitsToDouble
method in
class Double
.
This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.
double
.java.io.EOFException
- if this stream reaches the end before reading
eight bytes.java.io.IOException
- if an I/O error occurs.public final java.lang.String readLine() throws java.io.IOException
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.
readLine
in interface java.io.DataInput
java.io.IOException
- if an I/O error occurs.public final java.lang.String readUTF() throws java.io.IOException
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.
readUTF
in interface java.io.DataInput
java.io.EOFException
- if this stream reaches the end before
reading all the bytes.java.io.IOException
- if an I/O error occurs.java.io.UTFDataFormatException
- if the bytes do not represent
valid UTF-8 encoding of a Unicode string.protected void finalize() throws java.lang.Throwable
close()
method.finalize
in class java.lang.Object
java.lang.Throwable
Copyright © 2022 Apache Software Foundation. All Rights Reserved.