Package org.forgerock.opendj.ldap

Class ByteSequenceReader

  • public final class ByteSequenceReader
extends Object
    An interface for iteratively reading data from a ByteSequence . ByteSequenceReader must be created using the associated ByteSequence's asReader() method.

    • 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.

      • readByteSequence

        public ByteSequence readByteSequence​(int length)
        Relative bulk read method. Returns a ByteSequence 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 sequence to be returned.
        Returns:
        The byte sequence 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.

      • 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.

        An invocation of this method of the form: 

         src.readByteString(length);
        Has exactly the same effect as: 
         src.readByteSequence(length).toByteString();
        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 sequence.
        Throws:
        IndexOutOfBoundsException - If the position is negative or larger than the length of the underlying byte sequence.

      • 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 sequence.
        Returns:
        The number of bytes between the current position and the end of the underlying byte sequence.

      • 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 sequence.

      • 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 sequence.

      • 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 sequence.

      • asInputStream

        public InputStream asInputStream()
        Returns an InputStream from the current position in the sequence. There is only a single InputStream for a given ByteSequence, 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 sequence