BufferedInput (dxlib 3.341)

java.lang.Object
- java.io.InputStream
- - com.devexperts.io.BufferedInput

All Implemented Interfaces:

Closeable, DataInput, ObjectInput, AutoCloseable

Direct Known Subclasses:

BufferedInputPart, ByteArrayInput, ChunkedInput, StreamInput
```
public abstract class BufferedInput
extends InputStream
implements ObjectInput
```
An efficient buffered implementation of data input API. It is attributed with underlying byte buffer, position and limit:
- The underlying byte buffer holds data being read. It is never null.
- The position is an index of the next byte to be read. It is never negative and is never greater than the limit.
- The limit restricts allowed values for position. It usually points to the end of available data.
The BufferedInput supports the notion of total position - an offset of the next byte to be read from the beginning of the stream. It is equal to the number of bytes read from the stream adjusted according to reposition methods like seek(long), skip(long), rewind(long) and other.
All BufferedInput implementations are required to support marking because proper marking plays a vital role in definition and implementation of certain reposition methods.
This class is not thread-safe.

Field Summary

Fields
Modifier and Type	Field and Description
`protected byte[]`	`buffer`
`protected static byte[]`	`EMPTY_BYTE_ARRAY`
`protected int`	`limit`
`protected long`	`markPosition`
`protected int`	`position`
`protected long`	`totalPositionBase`

Constructor Summary

Constructors
Modifier Constructor and Description

protected BufferedInput()
Creates new instance with empty buffer.

Constructors
Modifier	Constructor and Description
`protected`	`BufferedInput()` Creates new instance with empty buffer.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`available()` Returns the number of bytes that can be read without blocking.
`protected void`	`checkEncapsulatedLength(long length, long min, long max)` Validate encapsulated content length according to specified bounds and stream limits.
`protected void`	`checkEOB()` Throws `IllegalStateException` if expression `(position != limit)` is true.
`protected void`	`checkRewind(long n)` Throws appropriate exception if rewind for specified distance is impossible.
`boolean`	`hasAvailable()` Checks if more bytes can be read from this input.
`boolean`	`hasAvailable(int bytes)` Checks if the specified number of bytes can be read from this input.
`void`	`mark()` Marks the current position in this buffered input.
`void`	`mark(int readLimit)` Deprecated. This method is for compatibility with interface of `InputStream` class only, do not use it, because the actual value of `readLimit` is irrelevant for all implementations of `BufferedInput`. Use `mark` and `unmark` methods instead.
`void`	`mark(long readLimit)` Deprecated. This method is for conceptual compatibility with interface of `InputStream` class only, do not use it, because the actual value of `readLimit` is irrelevant for all implementations of `BufferedInput`. Use `mark` and `unmark` methods instead.
`boolean`	`markSupported()` All BufferedInput implementations support `mark` and `reset`, so this method always returns true.
`protected void`	`needData()` This method is invoked when input methods need more bytes to read data.
`int`	`read()`
`int`	`read(byte[] b)`
`int`	`read(byte[] b, int off, int len)`
`boolean`	`readBoolean()`
`byte`	`readByte()`
`byte[]`	`readByteArray()` Reads an array of bytes in a compact encapsulation format.
`char`	`readChar()`
`int`	`readCompactInt()` Reads an `int` value in a compact format (see `IOUtil`).
`long`	`readCompactLong()` Reads a `long` value in a compact format (see `IOUtil`).
`protected abstract int`	`readData()` This method is invoked when input methods need more bytes to read data.
`double`	`readDouble()`
`float`	`readFloat()`
`void`	`readFully(byte[] b)`
`void`	`readFully(byte[] b, int off, int len)`
`int`	`readInt()`
`String`	`readLine()`
`long`	`readLong()`
`<T> Marshalled<T>`	`readMarshalled(Marshaller<T> marshaller)` Reads `Marshalled` object from a byte stream with a specified marshaller.
`<T> Marshalled<T>`	`readMarshalled(Marshaller<T> marshaller, SerialClassContext serialContext)` Reads `Marshalled` object from a byte stream with a specified marshaller.
`Object`	`readObject()` Read and return an object.
`Object`	`readObject(ClassLoader cl)` Read and return an object with a specified class loader.
`Object`	`readObject(SerialClassContext serialContext)` Read and return an object with a specified serial class context.
`short`	`readShort()`
`void`	`readToByteBuffer(ByteBuffer buffer)` Reads data from this buffered input into specified byte buffer.
`long`	`readToDataOutput(DataOutput out, long length)` Reads data from this buffered input into specified data output.
`long`	`readToOutputStream(OutputStream out, long length)` Reads data from this buffered input into specified output stream.
`int`	`readUnsignedByte()`
`int`	`readUnsignedShort()`
`String`	`readUTF()`
`int`	`readUTFBody(long utfLength, char[] chars, int offset)` Reads Unicode body in a UTF-8 format.
`int`	`readUTFChar()` Reads Unicode code point in a UTF-8 format.
`String`	`readUTFString()` Reads Unicode string in a UTF-8 format with compact encapsulation (see `IOUtil`).
`void`	`reset()` Repositions this buffered input to the position at the time the `mark` method was last called on this input.
`abstract void`	`rewind(long n)` Rewinds specified number of bytes.
`void`	`seek(long totalPosition)` Repositions this buffered input to specified total position.
`long`	`skip(long n)`
`int`	`skipBytes(int n)`
`protected void`	`throwEOFException()` Throws `EOFException` when requested by `needData()` method.
`long`	`totalPosition()` Returns total position of this input stream.
`void`	`unmark()` Invalidates `mark` position in this buffered input.

Methods inherited from class java.io.InputStream
close

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.io.ObjectInput
close

- Field Detail
  - EMPTY_BYTE_ARRAY
```
protected static final byte[] EMPTY_BYTE_ARRAY
```
  - buffer
```
protected byte[] buffer
```
  - position
```
protected int position
```
  - limit
```
protected int limit
```
  - totalPositionBase
```
protected long totalPositionBase
```
  - markPosition
```
protected long markPosition
```
- Constructor Detail
  - BufferedInput
```
protected BufferedInput()
```
    Creates new instance with empty buffer.
- Method Detail
  - needData
```
protected void needData()
                 throws IOException
```
    This method is invoked when input methods need more bytes to read data. This method must ensure that expression (position < limit) is true or throw an exception. This method may block if needed. This method is allowed to update buffer, position, limit and totalPositionBase fields as needed.
    This method shall throw an EOFException if the end of stream is reached.
    
    Throws:
    
    IOException - if an I/O error occurs or end of stream is reached
  - readData
```
protected abstract int readData()
                         throws IOException
```
    This method is invoked when input methods need more bytes to read data. This method shall make an attempt to read some bytes into the buffer. This method returns number of bytes actually read or value -1 if no bytes can be read because the end of the stream has been reached. This method may block if needed. This method is allowed to update buffer, position, limit and totalPositionBase fields as needed.
    This method shall never throw an EOFException.
    
    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
  - throwEOFException
```
protected void throwEOFException()
                          throws EOFException
```
    Throws EOFException when requested by needData() method. This implementation throws same reused instance with truncated stack trace to avoid garbage.
    
    Throws:
    
    EOFException
  - checkEOB
```
protected final void checkEOB()
```
    Throws IllegalStateException if expression (position != limit) is true.
  - checkEncapsulatedLength
```
protected void checkEncapsulatedLength(long length,
                                       long min,
                                       long max)
                                throws IOException
```
    Validate encapsulated content length according to specified bounds and stream limits.
    Data retrieval methods getting variable amount of data can invoke this method to check an upper bound of available data for validation.
    
    Parameters:
    
    length - encapsulated length value to be checked
    
    min - minimal theoretically valid length value
    
    max - maximal theoretically valid length value
    
    Throws:
    
    IOException - if length < min || length > max or length bytes definitely cannot be retrieved
  - read
```
public final int read()
               throws IOException
```
    Specified by:
    
    read in interface ObjectInput
    
    Specified by:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public final int read(byte[] b)
               throws IOException
```
    Specified by:
    
    read in interface ObjectInput
    
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b,
                int off,
                int len)
         throws IOException
```
    Specified by:
    
    read in interface ObjectInput
    
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - skip
```
public long skip(long n)
          throws IOException
```
    Specified by:
    
    skip in interface ObjectInput
    
    Overrides:
    
    skip in class InputStream
    
    Throws:
    
    IOException
  - hasAvailable
```
public boolean hasAvailable()
                     throws IOException
```
    Checks if more bytes can be read from this input. This is a faster-working shortcut for available() > 0 check. This implementation returns hasAvailable(1)
    
    Returns:
    
    true if more bytes can be read from this input.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - hasAvailable
```
public boolean hasAvailable(int bytes)
                     throws IOException
```
    Checks if the specified number of bytes can be read from this input. This is a faster-working shortcut for available() >= bytes check. This implementation returns available() >= bytes
    
    Parameters:
    
    bytes - the number of bytes.
    
    Returns:
    
    true if the specified number of bytes can be read from this input.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - available
```
public int available()
              throws IOException
```
    Returns the number of bytes that can be read without blocking.
    
    Specified by:
    
    available in interface ObjectInput
    
    Overrides:
    
    available in class InputStream
    
    Returns:
    
    the number of available bytes.
    
    Throws:
    
    IOException - If an I/O error has occurred.
  - readFully
```
public final void readFully(byte[] b)
                     throws IOException
```
    Specified by:
    
    readFully in interface DataInput
    
    Throws:
    
    IOException
  - readFully
```
public void readFully(byte[] b,
                      int off,
                      int len)
               throws IOException
```
    Specified by:
    
    readFully in interface DataInput
    
    Throws:
    
    IOException
  - skipBytes
```
public final int skipBytes(int n)
                    throws IOException
```
    Specified by:
    
    skipBytes in interface DataInput
    
    Throws:
    
    IOException
  - readBoolean
```
public final boolean readBoolean()
                          throws IOException
```
    Specified by:
    
    readBoolean in interface DataInput
    
    Throws:
    
    IOException
  - readByte
```
public final byte readByte()
                    throws IOException
```
    Specified by:
    
    readByte in interface DataInput
    
    Throws:
    
    IOException
  - readUnsignedByte
```
public final int readUnsignedByte()
                           throws IOException
```
    Specified by:
    
    readUnsignedByte in interface DataInput
    
    Throws:
    
    IOException
  - readShort
```
public final short readShort()
                      throws IOException
```
    Specified by:
    
    readShort in interface DataInput
    
    Throws:
    
    IOException
  - readUnsignedShort
```
public final int readUnsignedShort()
                            throws IOException
```
    Specified by:
    
    readUnsignedShort in interface DataInput
    
    Throws:
    
    IOException
  - readChar
```
public final char readChar()
                    throws IOException
```
    Specified by:
    
    readChar in interface DataInput
    
    Throws:
    
    IOException
  - readInt
```
public final int readInt()
                  throws IOException
```
    Specified by:
    
    readInt in interface DataInput
    
    Throws:
    
    IOException
  - readLong
```
public final long readLong()
                    throws IOException
```
    Specified by:
    
    readLong in interface DataInput
    
    Throws:
    
    IOException
  - readFloat
```
public final float readFloat()
                      throws IOException
```
    Specified by:
    
    readFloat in interface DataInput
    
    Throws:
    
    IOException
  - readDouble
```
public final double readDouble()
                        throws IOException
```
    Specified by:
    
    readDouble in interface DataInput
    
    Throws:
    
    IOException
  - readLine
```
public final String readLine()
                      throws IOException
```
    Specified by:
    
    readLine in interface DataInput
    
    Throws:
    
    IOException
  - readUTF
```
public final String readUTF()
                     throws IOException
```
    Specified by:
    
    readUTF in interface DataInput
    
    Throws:
    
    IOException
  - readObject
```
public final Object readObject()
                        throws IOException
```
    Read and return an object. This methods loads classes using a context class loader (see Thread.getContextClassLoader) or using the same classloader that loaded classes for this com.devexperts.io package when context class loader is not defined. This is a shortcut for readObject(null).
    
    Specified by:
    
    readObject in interface ObjectInput
    
    Returns:
    
    the object read from the stream
    
    Throws:
    
    IOException - if an I/O error occurs or if object cannot be deserialized
  - readObject
```
public final Object readObject(ClassLoader cl)
                        throws IOException
```
    Read and return an object with a specified class loader.
    
    Parameters:
    
    cl - the ClassLoader that will be used to load classes; null for context class loader.
    
    Returns:
    
    the object read from the stream
    
    Throws:
    
    IOException - if an I/O error occurs or if object cannot be deserialized
  - readObject
```
public final Object readObject(SerialClassContext serialContext)
                        throws IOException
```
    Read and return an object with a specified serial class context.
    
    Parameters:
    
    serialContext - the serial class context.
    
    Returns:
    
    the object read from the stream
    
    Throws:
    
    IOException - if an I/O error occurs or if object cannot be deserialized
  - readMarshalled
```
public final <T> Marshalled<T> readMarshalled(Marshaller<T> marshaller)
                                       throws IOException
```
    Reads Marshalled object from a byte stream with a specified marshaller. This method determines the number of marshalled bytes using Marshaller.readMarshalledLength, reads the corresponding number of bytes, and wraps them into Marshalled object instance. The result of this method is not null.
    When the serialization marshaller is used, then this method reads the same bytes as would have been been read by readObject method, so in.readObject() is mostly equivalent to in.readMarshalled(Marshaller.SERIALIZATION).getObject().
    To read an arbitrary marshalled object, this method must specify the same marshaller that was used in a marshalled object that was written by a corresponding BufferedOutput.writeMarshalled method invocation.
    
    Parameters:
    
    marshaller - a strategy that defines how an object is represented in a byte array
    
    Returns:
    
    the marshalled object
    
    Throws:
    
    IOException - if an I/O error occurs
  - readMarshalled
```
public final <T> Marshalled<T> readMarshalled(Marshaller<T> marshaller,
                                              SerialClassContext serialContext)
                                       throws IOException
```
    Reads Marshalled object from a byte stream with a specified marshaller. This method determines the number of marshalled bytes using Marshaller.readMarshalledLength, reads the corresponding number of bytes, and wraps them into Marshalled object instance. The result of this method is not null.
    When the serialization marshaller is used, then this method reads the same bytes as would have been been read by readObject method, so in.readObject() is mostly equivalent to in.readMarshalled(Marshaller.SERIALIZATION).getObject().
    To read an arbitrary marshalled object, this method must specify the same marshaller that was used in a marshalled object that was written by a corresponding BufferedOutput.writeMarshalled method invocation.
    
    Parameters:
    
    marshaller - a strategy that defines how an object is represented in a byte array
    
    serialContext - a serial class context that will be used to load classes;
    
    Returns:
    
    the marshalled object
    
    Throws:
    
    IOException - if an I/O error occurs
  - readCompactInt
```
public final int readCompactInt()
                         throws IOException
```
    Reads an int value in a compact format (see IOUtil). If actual encoded value does not fit into an int data type, then it is truncated to int value (only lower 32 bits are returned); the number is read entirely in this case. Equivalent to IOUtil.readCompactInt(java.io.DataInput) method.
    
    Returns:
    
    the int value read
    
    Throws:
    
    IOException - if an I/O error occurs
  - readCompactLong
```
public final long readCompactLong()
                           throws IOException
```
    Reads a long value in a compact format (see IOUtil). Equivalent to IOUtil.readCompactLong(java.io.DataInput) method.
    
    Returns:
    
    the long value read
    
    Throws:
    
    IOException - if an I/O error occurs
  - readByteArray
```
public final byte[] readByteArray()
                           throws IOException
```
    Reads an array of bytes in a compact encapsulation format. This method defines length as a number of bytes. Equivalent to IOUtil.readByteArray(java.io.DataInput) method.
    
    Returns:
    
    the byte array read
    
    Throws:
    
    IOException - if an I/O error occurs
  - readUTFChar
```
public final int readUTFChar()
                      throws IOException
```
    Reads Unicode code point in a UTF-8 format. Overlong UTF-8 and CESU-8-encoded surrogates are accepted and read without errors. Equivalent to IOUtil.readUTFChar(java.io.DataInput) method.
    
    Returns:
    
    the Unicode code point read
    
    Throws:
    
    UTFDataFormatException - if the bytes do not represent a valid UTF-8 encoding of a character
    
    IOException - if an I/O error occurs
  - readUTFString
```
public final String readUTFString()
                           throws IOException
```
    Reads Unicode string in a UTF-8 format with compact encapsulation (see IOUtil). Overlong UTF-8 and CESU-8-encoded surrogates are accepted and read without errors. This method defines length as a number of bytes. Equivalent to IOUtil.readUTFString(java.io.DataInput) method.
    
    Returns:
    
    the Unicode string read
    
    Throws:
    
    UTFDataFormatException - if the bytes do not represent a valid UTF-8 encoding of a string
    
    IOException - if an I/O error occurs
  - readUTFBody
```
public final int readUTFBody(long utfLength,
                             char[] chars,
                             int offset)
                      throws IOException
```
    Reads Unicode body in a UTF-8 format. Overlong UTF-8 and CESU-8-encoded surrogates are accepted and read without errors. This method defines length as a number of bytes. Equivalent to IOUtil.readUTFBody(java.io.DataInput, long, char[], int) method.
    
    Parameters:
    
    utfLength - the number of bytes to read
    
    chars - the char array in which read characters are stored in UTF-16 format
    
    offset - the start offset into the chars array where read characters are stored
    
    Returns:
    
    the number of read characters stored in the chars array
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if the chars array is too small to accommodate read characters
    
    UTFDataFormatException - if the bytes do not represent a valid UTF-8 encoding of a string
    
    IOException - if an I/O error occurs
  - totalPosition
```
public final long totalPosition()
```
    Returns total position of this input stream. The total position is defined as an offset of the next byte to be read from the beginning of the stream. It is equal to the number of read bytes adjusted according to outcome of repositioning methods like seek(long), skip(long), rewind(long), reset(), etc.
  - seek
```
public final void seek(long totalPosition)
                throws IOException
```
    Repositions this buffered input to specified total position. If specified total position is smaller than current total position, then rewind(long) operation for appropriate distance is performed; the stream has to be properly marked to support this operation. If specified total position is larger than current total position, then skip(long) operation for appropriate distance is performed until requested total position is reached; if end of stream happens before this operation can be completed then EOFException is thrown.
    
    Throws:
    
    IllegalArgumentException - if total position is negative
    
    IllegalStateException - if this stream is not marked or if attempting to rewind past the marked position
    
    IOException - if an I/O error occurs
    
    EOFException - if end of stream is reached
  - markSupported
```
public final boolean markSupported()
```
    All BufferedInput implementations support mark and reset, so this method always returns true.
    
    Overrides:
    
    markSupported in class InputStream
  - mark
```
public void mark()
```
    Marks the current position in this buffered input. A subsequent call to the reset method repositions this input at the last marked position so that subsequent reads re-read the same bytes. A subsequent call to unmark method invalidates mark without changing input position.
  - unmark
```
public void unmark()
```
    Invalidates mark position in this buffered input. This method does nothing is this input was not marked.
  - mark
```
public final void mark(int readLimit)
```
    Deprecated. This method is for compatibility with interface of InputStream class only, do not use it, because the actual value of readLimit is irrelevant for all implementations of BufferedInput. Use mark and unmark methods instead.
    
    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 argument tells this input stream to allow that many bytes to be read before the mark position gets invalidated. Negative value for readLimit may be used in order to invalidate the mark.
    This implementation calls mark() when readLimit >= 0 and unmark() otherwise.
    
    Overrides:
    
    mark in class InputStream
  - mark
```
public final void mark(long readLimit)
```
    Deprecated. This method is for conceptual compatibility with interface of InputStream class only, do not use it, because the actual value of readLimit is irrelevant for all implementations of BufferedInput. Use mark and unmark methods instead.
    
    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 argument tells this input stream to allow that many bytes to be read before the mark position gets invalidated. Negative value for readLimit may be used in order to invalidate the mark.
    This implementation calls mark() when readLimit >= 0 and unmark() otherwise.
  - reset
```
public final void reset()
                 throws IllegalStateException
```
    Repositions this buffered input to the position at the time the mark method was last called on this input. If the mark method has not been called since the buffered input was created, then an IllegalStateException is thrown. Otherwise the input is reset to a state such that all the bytes read since the most recent call to mark will be resupplied to subsequent callers of the read methods, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset.
    NOTE: This buffered input continues to be marked. Use unmark() after reset if mark on this input is no longer needed.
    
    Overrides:
    
    reset in class InputStream
    
    Throws:
    
    IllegalStateException - if this stream is not marked
  - rewind
```
public abstract void rewind(long n)
                     throws IllegalStateException
```
    Rewinds specified number of bytes. The input cannot be rewound past the marked position.
    
    Parameters:
    
    n - the number of bytes to rewind
    
    Throws:
    
    IllegalStateException - if this stream is not marked or if attempting to rewind past the marked position
  - checkRewind
```
protected final void checkRewind(long n)
```
    Throws appropriate exception if rewind for specified distance is impossible.
  - readToOutputStream
```
public long readToOutputStream(OutputStream out,
                               long length)
                        throws IOException
```
    Reads data from this buffered input into specified output stream. The number of bytes actually read is returned as an integer.
    
    Parameters:
    
    out - the destination output stream to write to
    
    length - maximum number of bytes to read
    
    Returns:
    
    total number of bytes read to the output stream
    
    Throws:
    
    IOException - if an I/O error occurs
  - readToDataOutput
```
public long readToDataOutput(DataOutput out,
                             long length)
                      throws IOException
```
    Reads data from this buffered input into specified data output. The number of bytes actually read is returned as an integer.
    
    Parameters:
    
    out - the destination data output to write to
    
    length - maximum number of bytes to read
    
    Returns:
    
    total number of bytes read to the data output
    
    Throws:
    
    IOException - if an I/O error occurs
  - readToByteBuffer
```
public void readToByteBuffer(ByteBuffer buffer)
                      throws IOException
```
    Reads data from this buffered input into specified byte buffer.
    
    Parameters:
    
    buffer - the destination byte buffer to write to
    
    Throws:
    
    IOException

Class BufferedInput

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.io.InputStream

Methods inherited from class java.lang.Object

Methods inherited from interface java.io.ObjectInput

Field Detail

EMPTY_BYTE_ARRAY

buffer

position

limit

totalPositionBase

markPosition

Constructor Detail

BufferedInput

Method Detail

needData

readData

throwEOFException

checkEOB

checkEncapsulatedLength

read

read

read

skip

hasAvailable

hasAvailable

available

readFully

readFully

skipBytes

readBoolean

readByte

readUnsignedByte

readShort

readUnsignedShort

readChar

readInt

readLong

readFloat

readDouble

readLine

readUTF

readObject

readObject

readObject

readMarshalled

readMarshalled

readCompactInt

readCompactLong

readByteArray

readUTFChar

readUTFString

readUTFBody

totalPosition

seek

markSupported

mark

unmark

mark

mark

reset

rewind

checkRewind

readToOutputStream

readToDataOutput

readToByteBuffer