Package org.forgerock.opendj.ldap

Class ByteStringReader

java.lang.Object

org.forgerock.opendj.ldap.ByteStringReader

public final class ByteStringReader
extends Object

An interface for iteratively reading data from a ByteString . ByteStringReader must be created using the associated ByteString's asReader() method.

Method Summary

Modifier and Type	Method	Description
InputStream	asInputStream()	Returns an InputStream from the current position in the byte string.
boolean	hasRemaining()	Returns true if this reader contains unread bytes or, more specifically, if remaining() > 0.
byte	peek()	Returns the byte situated at the current position.
byte	peek(int offset)	Returns the byte situated at the given offset from current position.
int	position()	Returns this reader's position.
void	position(int pos)	Sets this reader's position.
int	readBerLength()	Relative read method for reading a multi-byte BER length.
byte	readByte()	Relative read method.
void	readBytes(byte[] b)	Relative bulk read method.
void	readBytes(byte[] bytes, int offset, int length)	Relative bulk read method.
ByteString	readByteString(int length)	Relative bulk read method.
int	readCompactUnsignedInt()	Relative read method for reading a compacted int value.
long	readCompactUnsignedLong()	Relative read method for reading a compacted long value.
int	readInt()	Relative read method for reading an integer value.
long	readLong()	Relative read method for reading a long value.
short	readShort()	Relative read method for reading an short value.
String	readStringUtf8(int length)	Relative read method for reading a UTF-8 encoded string.
int	remaining()	Returns the number of bytes between the current position and the end of the underlying byte string.
void	rewind()	Rewinds this reader's position to zero.
void	skip(int length)	Skips the given number of bytes.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

readByte

public byte readByte()

Relative read method. Reads the byte at the current position.

Returns:

The byte at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < 1.

readBytes

public void readBytes(byte[] b)

Relative bulk read method. This method transfers bytes from this reader into the given destination array. An invocation of this method of the form:

 src.readBytes(b);
 

Behaves in exactly the same way as the invocation:

 src.readBytes(b, 0, b.length);
 

Parameters:

b - The byte array into which bytes are to be written.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < b.length.

readBytes

public void readBytes(byte[] bytes,
                      int offset,
                      int length)

Relative bulk read method. Copies length bytes from this reader into the given array, starting at the current position of this reader and at the given offset in the array. The position of this reader is then incremented by length. In other words, an invocation of this method of the form:

 src.read(b, offset, length);
 

Has exactly the same effect as the loop:

 for (int i = offset; i < offset + length; i++)
     b[i] = src.readByte();
 

Except that it first checks that there are sufficient bytes in this buffer and it is potentially much more efficient.

Parameters:

bytes - The byte array into which bytes are to be written.

offset - The offset within the array of the first byte to be written; must be non-negative and no larger than b.length.

length - The number of bytes to be written to the given array; must be non-negative and no larger than b.length .

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < length, if requested bytes will not fit in destination byte array, that is, if offset + length > bytes.length

readBerLength

public int readBerLength()

Relative read method for reading a multi-byte BER length. Reads the next one to five bytes at this reader's current position, composing them into a integer value and then increments the position by the number of bytes read.

Returns:

The integer value representing the length at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request.

readByteString

public ByteString readByteString(int length)

Relative bulk read method. Returns a ByteString whose content is the next length bytes from this reader, starting at the current position of this reader. The position of this reader is then incremented by length.

NOTE: The value returned from this method should NEVER be cached as it prevents the contents of the underlying byte stream from being garbage collected.

Parameters:

length - The length of the byte string to be returned.

Returns:

The byte string whose content is the next length bytes from this reader.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < length.

readInt

public int readInt()

Relative read method for reading an integer value. Reads the next four bytes at this reader's current position, composing them into an integer value according to big-endian byte order, and then increments the position by four.

Returns:

The integer value at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < 4.

readLong

public long readLong()

Relative read method for reading a long value. Reads the next eight bytes at this reader's current position, composing them into a long value according to big-endian byte order, and then increments the position by eight.

Returns:

The long value at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < 8.

readCompactUnsignedLong

public long readCompactUnsignedLong()

Relative read method for reading a compacted long value. Compaction allows to reduce number of bytes needed to hold long types depending on its value (i.e: if value < 128, value will be encoded using one byte only). Reads the next bytes at this reader's current position, composing them into a long value according to big-endian byte order, and then increments the position by the size of the encoded long. Note that the maximum value of a compact long is 2^56.

Returns:

The long value at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request.

readCompactUnsignedInt

public int readCompactUnsignedInt()

Relative read method for reading a compacted int value. Compaction allows to reduce number of bytes needed to hold int types depending on its value (i.e: if value < 128, value will be encoded using one byte only). Reads the next bytes at this reader's current position, composing them into an int value according to big-endian byte order, and then increments the position by the size of the encoded int.

Returns:

The int value at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request.

readShort

public short readShort()

Relative read method for reading an short value. Reads the next 2 bytes at this reader's current position, composing them into an short value according to big-endian byte order, and then increments the position by two.

Returns:

The integer value at this reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < 2.

readStringUtf8

public String readStringUtf8(int length)

Relative read method for reading a UTF-8 encoded string. Reads the next number of specified bytes at this reader's current position, decoding them into a string using UTF-8 and then increments the position by the number of bytes read. If UTF-8 decoding fails, the platform's default encoding will be used.

Parameters:

length - The number of bytes to read and decode.

Returns:

The string value at the reader's current position.

Throws:

IndexOutOfBoundsException - If there are fewer bytes remaining in this reader than are required to satisfy the request, that is, if remaining() < length.

position

public int position()

Returns this reader's position.

Returns:

The position of this reader.

position

public void position(int pos)

Sets this reader's position.

Parameters:

pos - The new position value; must be non-negative and no larger than the length of the underlying byte string.

Throws:

IndexOutOfBoundsException - If the position is negative or larger than the length of the underlying byte string.

hasRemaining

public boolean hasRemaining()

Returns true if this reader contains unread bytes or, more specifically, if remaining() > 0.

Returns:

true if this reader contains unread bytes.

remaining

public int remaining()

Returns the number of bytes between the current position and the end of the underlying byte string.

Returns:

The number of bytes between the current position and the end of the underlying byte string.

rewind

public void rewind()

Rewinds this reader's position to zero.

An invocation of this method of the form:

 src.rewind();
 

Has exactly the same effect as:

 src.position(0);
 

peek

public byte peek()

Returns the byte situated at the current position. The byte is not consumed.

Returns:

the byte situated at the current position

Throws:

IndexOutOfBoundsException - If the position is negative or larger than the length of the underlying byte string.

peek

public byte peek(int offset)

Returns the byte situated at the given offset from current position. The byte is not consumed.

Parameters:

offset - The offset where to look at from current position.

Returns:

the byte situated at the given offset from current position

Throws:

IndexOutOfBoundsException - If the position is negative or larger than the length of the underlying byte string.

skip

public void skip(int length)

Skips the given number of bytes. Negative values are allowed.

An invocation of this method of the form:

 src.skip(length);
 

Has exactly the same effect as:

 src.position(position() + length);
 

Parameters:

length - The number of bytes to skip.

Throws:

IndexOutOfBoundsException - If the new position is less than 0 or greater than the length of the underlying byte string.

toString

public String toString()

Overrides:

toString in class Object

asInputStream

public InputStream asInputStream()

Returns an InputStream from the current position in the byte string. There is only a single InputStream for a given ByteString, so multiple calls to asInputStream() will always return the same object. The returned InputStream does not support mark(). Calling close() does nothing.

Returns:

an InputStream from the current position in the byte string