net.freeutils.tnef

Class RawInputStream

public class RawInputStream extends InputStream

The RawInputStream class is an InputStream which can provide raw byte data from several underlying sources, including a byte array, a partial section of a byte array, a file, a partial section of a file, another RawInputStream, or a partial section of another RawInputStream.

Since: 2003-04-29

Constructor Summary
RawInputStream(byte[] buf, long offset, long length)
Constructs a RawInputStream which provides data from a byte array.
RawInputStream(byte[] buf)
Constructs a RawInputStream which provides data from a byte array.
RawInputStream(String filename, long offset, long length)
Constructs a RawInputStream which provides data from a file.
RawInputStream(String filename)
Constructs a RawInputStream which provides data from a file.
RawInputStream(File file)
Constructs a RawInputStream which provides data from a file.
RawInputStream(File file, long offset, long length)
Constructs a RawInputStream which provides data from a file.
RawInputStream(RawInputStream ris)
Constructs a RawInputStream which provides data from another RawInputStream.
RawInputStream(RawInputStream ris, long offset, long length)
Constructs a RawInputStream which provides data from another RawInputStream.
Method Summary
intavailable()
Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream.
voidclose()
Closes this input stream and releases any system resources associated with the stream.
protected voidfinalize()
Finalizes this object and frees its resources (called by the JVM garbage collector when this object is discarded).
longgetLength()
Gets the length of the raw data in bytes.
longgetPosition()
Return the current position in the InputStream, as an offset from the beginning of the underlying InputStream.
voidmark(int readlimit)
Marks the current position in this input stream.
booleanmarkSupported()
Tests if this input stream supports the mark and reset methods.
InputStreamnewStream(long start, long end)
Return a new InputStream representing a subset of the data from this InputStream, starting at start (inclusive) up to end (exclusive).
intread()
Reads the next byte of data from the input stream.
byte[]readBytes(int length)
Reads a given number of bytes from the stream.
StringreadString(int length)
Reads a C-style null terminated byte sequence from the stream, as a standard String.
StringreadStringUnicode(int length)
Reads a C-style null terminated Unicode byte sequence from the stream, as a standard String.
intreadU16()
Reads an unsigned 16-bit value (little-endian ordered) from the stream.
longreadU32()
Reads an unsigned 32-bit value (little-endian ordered) from the stream.
longreadU64()
Reads a 64-bit value (little-endian ordered) from the stream.
intreadU8()
Reads an unsigned 8-bit value from the stream.
voidreset()
Repositions this stream to the position at the time the mark method was last called on this input stream.
longskip(long n)
Skips over and discards n bytes of data from this input stream.
byte[]toByteArray(int max)
Gets the raw data as a byte array, starting at the current position and ending either at the end of the stream, or after the given maximum number of bytes, whichever comes first.
byte[]toByteArray()
Gets the raw data as a byte array, starting at the current position and ending at the end of the stream.
StringtoString()
Returns a string representation of this object.

Constructor Detail

RawInputStream

public RawInputStream(byte[] buf, long offset, long length)
Constructs a RawInputStream which provides data from a byte array.

Parameters: buf the byte array to retrieve data from offset the offset within the array to start getting data at length the length of the partial stream to create (in bytes)

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(byte[] buf)
Constructs a RawInputStream which provides data from a byte array.

Parameters: buf the byte array to retrieve data from

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(String filename, long offset, long length)
Constructs a RawInputStream which provides data from a file.

Parameters: filename the fully qualified path of the file to retrieve data from offset the offset within the file to start getting data at length the length of the partial stream to create (in bytes)

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(String filename)
Constructs a RawInputStream which provides data from a file.

Parameters: filename the fully qualified path of the file to retrieve data from

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(File file)
Constructs a RawInputStream which provides data from a file.

Parameters: file the file to retrieve data from

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(File file, long offset, long length)
Constructs a RawInputStream which provides data from a file.

Parameters: file the file to retrieve data from offset the offset within the file to start getting data at length the length of the partial stream to create (in bytes)

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(RawInputStream ris)
Constructs a RawInputStream which provides data from another RawInputStream. The new stream begins at the current position of the original stream, and contains all of the remaining bytes.

Parameters: ris the RawInputStream to retrieve data from

Throws: IOException if an I/O error occurs

RawInputStream

public RawInputStream(RawInputStream ris, long offset, long length)
Constructs a RawInputStream which provides data from another RawInputStream. The new stream begins at the current position of the original stream plus the given offset, and its length is set to given length.

Parameters: ris the RawInputStream to retrieve data from offset the offset from the current position at which the new stream will begin length the length of the partial stream to create (in bytes)

Throws: IOException if an I/O error occurs

Method Detail

available

public int available()
Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream. The next caller might be the same thread or another thread.

Returns: the number of bytes that can be read from this input stream without blocking

Throws: IOException if an I/O error occurs

close

public void close()
Closes this input stream and releases any system resources associated with the stream.

Throws: IOException if an I/O error occurs

finalize

protected void finalize()
Finalizes this object and frees its resources (called by the JVM garbage collector when this object is discarded).

Throws: Throwable the Exception raised by this method

getLength

public long getLength()
Gets the length of the raw data in bytes. Unlike the available() method, this method is not affected by reading or skipping, and always returns the total number of bytes that this stream contains.

Returns: the length of the raw data in bytes

getPosition

public long getPosition()
Return the current position in the InputStream, as an offset from the beginning of the underlying InputStream.

Returns: the current position

mark

public void mark(int readlimit)
Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

The readlimit arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated.

The general contract of mark is that, if the method markSupported returns true, the stream somehow remembers all the bytes read after the call to mark and stands ready to supply those same bytes again if and whenever the method reset is called. However, the stream is not required to remember any data at all if more than readlimit bytes are read from the stream before reset is called.

Parameters: readlimit the maximum limit of bytes that can be read before the mark position becomes invalid

See Also: java.io.InputStream#reset()

markSupported

public boolean markSupported()
Tests if this input stream supports the mark and reset methods.

Returns: true if this true type supports the mark and reset method; false otherwise

See Also: java.io.InputStream#mark(int) java.io.InputStream#reset()

newStream

public InputStream newStream(long start, long end)
Return a new InputStream representing a subset of the data from this InputStream, starting at start (inclusive) up to end (exclusive). start must be non-negative. If end is -1, the new stream ends at the same place as this stream.

Parameters: start the starting position, relative to current position end the ending position + 1

Returns: the new stream, or null if an error occurs

Throws: IllegalArgumentException if start < 0

read

public int read()
Reads the next byte of data from the input stream. The value byte is returned as an 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.

Returns: the next byte of data, or -1 if the end of the stream is reached

Throws: IOException if an I/O error occurs

readBytes

public byte[] readBytes(int length)
Reads a given number of bytes from the stream.

Parameters: length the number of bytes to read

Returns: the read bytes

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readString

public String readString(int length)
Reads a C-style null terminated byte sequence from the stream, as a standard String. The null terminated byte sequence is interpreted as 8-bit ISO-8859-1 characters (a.k.a. ISO-Latin-1), which is a superset of US-ASCII. This way we don't lose any 8-bit values and remain fully compatible: If the source charset is unknown, a str.getBytes("ISO8859_1") will reconstruct the exact original byte sequence which the application can then process in any charset it sees fit.

Parameters: length the length of the C-style string in bytes, which may include any number of terminating null ('\0') characters

Returns: a String containing the C-style string's characters, interpreted as ISO-8859-1 characters

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readStringUnicode

public String readStringUnicode(int length)
Reads a C-style null terminated Unicode byte sequence from the stream, as a standard String. The null terminated byte sequence is interpreted as 16-bit Unicode characters (UTF-16), stored in Little Endian order.

Parameters: length the length of the C-style string in bytes, which may include any number of terminating null ('\0') characters

Returns: a String containing the C-style string's characters, interpreted as Unicode (UTF-16 Little Endian) characters

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readU16

public int readU16()
Reads an unsigned 16-bit value (little-endian ordered) from the stream.

Returns: an unsigned 16-bit value as an int

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readU32

public long readU32()
Reads an unsigned 32-bit value (little-endian ordered) from the stream.

Returns: an unsigned 32-bit value as a long

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readU64

public long readU64()
Reads a 64-bit value (little-endian ordered) from the stream.

Returns: a 64-bit value as a long

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

readU8

public int readU8()
Reads an unsigned 8-bit value from the stream.

Returns: an unsigned 8-bit value as an int

Throws: IOException if the end of stream has been reached, or if an I/O error occurs

reset

public void reset()
Repositions this stream to the position at the time the mark method was last called on this input stream.

The general contract of reset is:

Throws: IOException if this stream has not been marked or if the mark has been invalidated

See Also: java.io.InputStream#mark(int) java.io.IOException

skip

public long skip(long n)
Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

Parameters: n the number of bytes to be skipped

Returns: the actual number of bytes skipped

Throws: IOException if an I/O error occurs

toByteArray

public byte[] toByteArray(int max)
Gets the raw data as a byte array, starting at the current position and ending either at the end of the stream, or after the given maximum number of bytes, whichever comes first.

Parameters: max the maximum number of returned bytes; if negative, there is no limit

Returns: the raw data as a byte array

Throws: IOException if an I/O error occurs

toByteArray

public byte[] toByteArray()
Gets the raw data as a byte array, starting at the current position and ending at the end of the stream.

Returns: the raw data as a byte array

Throws: IOException if an I/O error occurs

toString

public String toString()
Returns a string representation of this object.

Returns: a string representation of this object