Package org.forgerock.opendj.ldap

Class ByteStringBuilder

    • Field Detail

      • MAX_COMPACT_SIZE

        public static final int MAX_COMPACT_SIZE
        Maximum size in bytes of a compact encoded value.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ByteStringBuilder

        public ByteStringBuilder()
        Creates a new byte string builder with an initial capacity of 32 bytes.

      • ByteStringBuilder

        public ByteStringBuilder​(int capacity)
        Creates a new byte string builder with the specified initial capacity.
        Parameters:
        capacity - The initial capacity.
        Throws:
        IllegalArgumentException - If the capacity is negative.

      • ByteStringBuilder

        public ByteStringBuilder​(ByteSequence bs)
        Creates a new byte string builder with the content of the provided ByteSequence. Its capacity is set to the length of the provided ByteSequence.
        Parameters:
        bs - The ByteSequence to copy

    • Method Detail

      • appendByte

        public ByteStringBuilder appendByte​(int b)
        Appends the provided byte to this byte string builder.

        Note: this method accepts an int for ease of reading and writing.

        This method only keeps the lowest 8-bits of the provided int. Higher bits will be truncated. This method performs the equivalent of: 

         
 int i = ...;
 int i8bits = i & 0xFF;
 // only use "i8bits"
        OR 
         
 int i = ...;
 byte b = (byte) i;
 // only use "b"
        Parameters:
        b - The byte to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public ByteStringBuilder appendBytes​(byte[] bytes)
        Appends the provided byte array to this byte string builder.

        An invocation of the form: 

         src.append(bytes)
        Behaves in exactly the same way as the invocation: 
         src.append(bytes, 0, bytes.length);
        Parameters:
        bytes - The byte array to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public ByteStringBuilder appendBytes​(byte[] bytes,
                                     int offset,
                                     int length)
        Appends the provided byte array to this byte string builder.
        Parameters:
        bytes - The byte array to be appended to this byte string builder.
        offset - The offset of the byte array to be used; must be non-negative and no larger than bytes.length .
        length - The length of the byte array to be used; must be non-negative and no larger than bytes.length - offset.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.

      • appendBytes

        public ByteStringBuilder appendBytes​(ByteBuffer buffer)
        Appends the provided ByteBuffer to this byte string builder.
        Parameters:
        buffer - The byte buffer to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public ByteStringBuilder appendBytes​(ByteBuffer buffer,
                                     int length)
        Appends the provided ByteBuffer to this byte string builder.
        Parameters:
        buffer - The byte buffer to be appended to this byte string builder.
        length - The number of bytes to be appended from buffer.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If length is less than zero or greater than buffer.remaining().

      • appendBytes

        public ByteStringBuilder appendBytes​(ByteSequence bytes)
        Appends the provided ByteSequence to this byte string builder.
        Parameters:
        bytes - The byte sequence to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public ByteStringBuilder appendBytes​(ByteSequenceReader reader,
                                     int length)
        Appends the provided ByteSequenceReader to this byte string builder.
        Parameters:
        reader - The byte sequence reader to be appended to this byte string builder.
        length - The number of bytes to be appended from reader.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If length is less than zero or greater than reader.remaining().

      • appendUtf8

        public ByteStringBuilder appendUtf8​(char[] chars)
        Appends the UTF-8 encoded bytes of the provided char array to this byte string builder.
        Parameters:
        chars - The char array whose UTF-8 encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public void appendBytes​(DataInput stream,
                        int length)
                 throws EOFException,
                        IOException
        Appends the provided DataInput to this byte string builder.
        Parameters:
        stream - The data input stream to be appended to this byte string builder.
        length - The maximum number of bytes to be appended from stream.
        Throws:
        IndexOutOfBoundsException - If length is less than zero.
        EOFException - If this stream reaches the end before reading all the bytes.
        IOException - If an I/O error occurs.

      • appendBytes

        public int appendBytes​(InputStream stream,
                       int length)
                throws IOException
        Appends the provided InputStream to this byte string builder.
        Parameters:
        stream - The input stream to be appended to this byte string builder.
        length - The maximum number of bytes to be appended from buffer .
        Returns:
        The number of bytes read from the input stream, or -1 if the end of the input stream has been reached.
        Throws:
        IndexOutOfBoundsException - If length is less than zero.
        IOException - If an I/O error occurs.

      • appendInt

        public ByteStringBuilder appendInt​(int i)
        Appends the big-endian encoded bytes of the provided integer to this byte string builder.
        Parameters:
        i - The integer whose big-endian encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendLong

        public ByteStringBuilder appendLong​(long l)
        Appends the big-endian encoded bytes of the provided long to this byte string builder.
        Parameters:
        l - The long whose big-endian encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendCompactUnsigned

        public ByteStringBuilder appendCompactUnsigned​(long value)
        Appends the compact encoded bytes of the provided unsigned long to this byte string builder. This method allows to encode unsigned long up to 56 bits using fewer bytes (from 1 to 8) than append(long). The encoding has the important property that it preserves ordering, so it can be used for keys.
        Parameters:
        value - The long whose compact encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendObject

        public ByteStringBuilder appendObject​(Object o)
        Appends the byte string representation of the provided object to this byte string builder. The object is converted to a byte string as follows:
        • if the object is an instance of ByteSequence then this method is equivalent to calling appendBytes(ByteSequence)
        • if the object is a byte[] then this method is equivalent to calling appendBytes(byte[])
        • if the object is a char[] then this method is equivalent to calling appendUtf8(char[])
        • for all other types of object this method is equivalent to calling appendUtf8(String) with the toString() representation of the provided object.
        Note: this method treats Long and Integer objects like any other type of Object. More specifically, the following invocations are not equivalent:
        • append(0) is not equivalent to append((Object) 0)
        • append(0L) is not equivalent to append((Object) 0L)
        Parameters:
        o - The object to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendShort

        public ByteStringBuilder appendShort​(int i)
        Appends the big-endian encoded bytes of the provided short to this byte string builder.

        Note: this method accepts an int for ease of reading and writing.

        This method only keeps the lowest 16-bits of the provided int. Higher bits will be truncated. This method performs the equivalent of: 

         
 int i = ...;
 int i16bits = i & 0xFFFF;
 // only use "i16bits"
        OR 
         
 int i = ...;
 short s = (short) i;
 // only use "s"
        Parameters:
        i - The short whose big-endian encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendUtf8

        public ByteStringBuilder appendUtf8​(String s)
        Appends the UTF-8 encoded bytes of the provided string to this byte string builder.
        Parameters:
        s - The string whose UTF-8 encoding is to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBerLength

        public ByteStringBuilder appendBerLength​(int length)
        Appends the ASN.1 BER length encoding representation of the provided integer to this byte string builder.
        Parameters:
        length - The value to encode using the BER length encoding rules.
        Returns:
        This byte string builder.

      • asOutputStream

        public OutputStream asOutputStream()
        Returns an OutputStream whose write operations append data to this byte string builder. The returned output stream will never throw an IOException and its close method does not do anything.
        Returns:
        An OutputStream whose write operations append data to this byte string builder.

      • asReader

        public ByteSequenceReader asReader()
        Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte string builder.

        NOTE: all concurrent updates to this byte string builder are supported with the exception of clear(). Any invocations of clear() must be accompanied by a subsequent call to ByteSequenceReader.rewind().

        Specified by:
        asReader in interface ByteSequence
        Returns:
        The ByteSequenceReader which can be used to incrementally read and decode data from this byte string builder.
        See Also:
        clear()

      • byteAt

        public byte byteAt​(int index)
        Description copied from interface: ByteSequence
        Returns the byte value at the specified index.

        An index ranges from zero to length() - 1. The first byte value of the sequence is at index zero, the next at index one, and so on, as for array indexing.

        Specified by:
        byteAt in interface ByteSequence
        Parameters:
        index - The index of the byte to be returned.
        Returns:
        The byte value at the specified index.

      • shortAt

        public short shortAt​(int index)
        Description copied from interface: ByteSequence
        Returns the big-endian short value at the specified index.
        Specified by:
        shortAt in interface ByteSequence
        Parameters:
        index - The index of the short to be returned.
        Returns:
        The short value at the specified index.

      • intAt

        public int intAt​(int index)
        Description copied from interface: ByteSequence
        Returns the big-endian int value at the specified index.
        Specified by:
        intAt in interface ByteSequence
        Parameters:
        index - The index of the int to be returned.
        Returns:
        The int value at the specified index.

      • longAt

        public long longAt​(int index)
        Description copied from interface: ByteSequence
        Returns the big-endian long value at the specified index.
        Specified by:
        longAt in interface ByteSequence
        Parameters:
        index - The index of the long to be returned.
        Returns:
        The long value at the specified index.

      • capacity

        public int capacity()
        Returns the current capacity of this byte string builder. The capacity may increase as more data is appended.
        Returns:
        The current capacity of this byte string builder.

      • clear

        public ByteStringBuilder clear()
        Sets the length of this byte string builder to zero.

        NOTE: if this method is called, then ByteSequenceReader.rewind() must also be called on any associated byte sequence readers in order for them to remain valid.

        Returns:
        This byte string builder.
        See Also:
        asReader()

      • clearAndTruncate

        public ByteStringBuilder clearAndTruncate​(int thresholdCapacity,
                                          int newCapacity)
        Sets the length of this byte string builder to zero, and resets the capacity to the specified size if above provided threshold.

        NOTE: if this method is called, then ByteSequenceReader.rewind() must also be called on any associated byte sequence readers in order for them to remain valid.

        Parameters:
        thresholdCapacity - The threshold capacity triggering a truncate
        newCapacity - The new capacity.
        Returns:
        This byte string builder.
        Throws:
        IllegalArgumentException - If the newCapacity is negative or the newCapacity is bigger than the thresholdCapacity.
        See Also:
        asReader()

      • compact

        public ByteStringBuilder compact​(int index)
        Compacts this byte string builder so that all the bytes between index and the end of the builder are relocated to the front of the builder. That is to say that the byte at index will end up at index 0, the byte at index+1 at index 1, and so on. The final length of the builder will be length() - index.
        Parameters:
        index - The index of the first byte to be moved.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If index is negative or not less than length().

      • compact

        public ByteStringBuilder compact​(int index,
                                 int length)
        Compacts this byte string builder so that length bytes beginning at index index are relocated to the front of the builder. That is to say that the byte at index will end up at index 0, the byte at index+1 at index 1, and so on. The final length of the builder will be length.
        Parameters:
        index - The index of the first byte to be moved.
        length - The number of bytes to be moved.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If index is negative or if index + length is greater than length().

      • compareTo

        public int compareTo​(byte[] bytes,
                     int offset,
                     int length)
        Description copied from interface: ByteSequence
        Compares this byte sequence with the specified byte array subsequence for order. Returns a negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified byte array subsequence.
        Specified by:
        compareTo in interface ByteSequence
        Parameters:
        bytes - The byte array to compare.
        offset - The offset of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
        length - The length of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length - offset.
        Returns:
        A negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified byte array subsequence.

      • compareTo

        public int compareTo​(ByteSequence o)
        Description copied from interface: ByteSequence
        Compares this byte sequence with the specified byte sequence for order. Returns a negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified object.
        Specified by:
        compareTo in interface ByteSequence
        Specified by:
        compareTo in interface Comparable<ByteSequence>
        Parameters:
        o - The byte sequence to be compared.
        Returns:
        A negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified object.

      • copyTo

        public byte[] copyTo​(byte[] bytes)
        Description copied from interface: ByteSequence
        Copies the contents of this byte sequence to the provided byte array.

        Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.

        An invocation of the form: 

         src.copyTo(bytes)
        Behaves in exactly the same way as the invocation: 
         src.copyTo(bytes, 0);
        Specified by:
        copyTo in interface ByteSequence
        Parameters:
        bytes - The byte array to which bytes are to be copied.
        Returns:
        The byte array.

      • copyTo

        public byte[] copyTo​(byte[] bytes,
                     int offset)
        Description copied from interface: ByteSequence
        Copies the contents of this byte sequence to the specified location in the provided byte array.

        Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.

        An invocation of the form: 

         src.copyTo(bytes, offset)
        Behaves in exactly the same way as the invocation: 
         int len = Math.min(src.length(), bytes.length - offset);
 for (int i = 0; i < len; i++)
     bytes[offset + i] = src.get(i);
        Except that it is potentially much more efficient.
        Specified by:
        copyTo in interface ByteSequence
        Parameters:
        bytes - The byte array to which bytes are to be copied.
        offset - The offset within the array of the first byte to be written; must be non-negative and no larger than bytes.length.
        Returns:
        The byte array.

      • copyTo

        public ByteBuffer copyTo​(ByteBuffer byteBuffer)
        Description copied from interface: ByteSequence
        Appends the content of this byte sequence to the provided ByteBuffer starting at it's current position. The position of the buffer is then incremented by the length of this sequence.
        Specified by:
        copyTo in interface ByteSequence
        Parameters:
        byteBuffer - The buffer to copy to. It must be large enough to receive all bytes.
        Returns:
        The buffer.

      • copyTo

        public boolean copyTo​(CharBuffer charBuffer,
                      CharsetDecoder decoder)
        Description copied from interface: ByteSequence
        Appends the content of this byte sequence decoded using provided charset decoder to the provided CharBuffer starting at it's current position. The position of charBuffer is then incremented by the length of this sequence.
        Specified by:
        copyTo in interface ByteSequence
        Parameters:
        charBuffer - The buffer to copy to, if decoding is successful. It must be large enough to receive all decoded characters.
        decoder - The charset decoder to use for decoding.
        Returns:
        true if byte string was successfully decoded and charBuffer is large enough to receive the resulting string, false otherwise

      • copyTo

        public OutputStream copyTo​(OutputStream stream)
                    throws IOException
        Description copied from interface: ByteSequence
        Copies the entire contents of this byte sequence to the provided OutputStream.
        Specified by:
        copyTo in interface ByteSequence
        Parameters:
        stream - The OutputStream to copy to.
        Returns:
        The OutputStream.
        Throws:
        IOException - If an error occurs while writing to the OutputStream.

      • ensureAdditionalCapacity

        public ByteStringBuilder ensureAdditionalCapacity​(int size)
        Ensures that the specified number of additional bytes will fit in this byte string builder and resizes it if necessary.
        Parameters:
        size - The number of additional bytes.
        Returns:
        This byte string builder.

      • equals

        public boolean equals​(byte[] bytes,
                      int offset,
                      int length)
        Description copied from interface: ByteSequence
        Indicates whether the provided byte array subsequence is equal to this byte sequence. In order for it to be considered equal, the provided byte array subsequence must contain the same bytes in the same order.
        Specified by:
        equals in interface ByteSequence
        Parameters:
        bytes - The byte array for which to make the determination.
        offset - The offset of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
        length - The length of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length - offset.
        Returns:
        true if the content of the provided byte array subsequence is equal to that of this byte sequence, or false if not.

      • equals

        public boolean equals​(Object o)
        Indicates whether the provided object is equal to this byte string builder. In order for it to be considered equal, the provided object must be a byte sequence containing the same bytes in the same order.
        Specified by:
        equals in interface ByteSequence
        Overrides:
        equals in class Object
        Parameters:
        o - The object for which to make the determination.
        Returns:
        true if the provided object is a byte sequence whose content is equal to that of this byte string builder, or false if not.

      • hashCode

        public int hashCode()
        Returns a hash code for this byte string builder. It will be the sum of all of the bytes contained in the byte string builder.

        NOTE: subsequent changes to this byte string builder will invalidate the returned hash code.

        Specified by:
        hashCode in interface ByteSequence
        Overrides:
        hashCode in class Object
        Returns:
        A hash code for this byte string builder.

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: ByteSequence
        Returns true if this byte sequence has a length of zero.
        Specified by:
        isEmpty in interface ByteSequence
        Returns:
        true if this byte sequence has a length of zero.

      • length

        public int length()
        Description copied from interface: ByteSequence
        Returns the length of this byte sequence.
        Specified by:
        length in interface ByteSequence
        Returns:
        The length of this byte sequence.

      • setByte

        public void setByte​(int index,
                    byte b)
        Sets the byte value at the specified index.

        An index ranges from zero to length() - 1. The first byte value of the sequence is at index zero, the next at index one, and so on, as for array indexing.

        Parameters:
        index - The index of the byte to be set.
        b - The byte to set on this byte string builder.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length().

      • setLength

        public ByteStringBuilder setLength​(int newLength)
        Sets the length of this byte string builder.

        If the newLength argument is less than the current length, the length is changed to the specified length.

        If the newLength argument is greater than or equal to the current length, then the capacity is increased and sufficient null bytes are appended so that length becomes the newLength argument.

        The newLength argument must be greater than or equal to 0.

        Parameters:
        newLength - The new length.
        Returns:
        This byte string builder.
        Throws:
        IndexOutOfBoundsException - If the newLength argument is negative.

      • subSequence

        public ByteSequence subSequence​(int start)
        Returns a new byte sequence that is a subsequence of this byte sequence.

        The subsequence starts with the byte value at the specified start index and ends with the last byte value. The length (in bytes) of the returned sequence is length() - start, so if start == length() then an empty sequence is returned.

        NOTE: the returned subsequence will be robust against all updates to the byte string builder except for invocations of the method clear(). If a permanent immutable byte sequence is required then callers should invoke toByteString() on the returned byte sequence.

        Specified by:
        subSequence in interface ByteSequence
        Parameters:
        start - The start index, inclusive.
        Returns:
        The newly created byte subsequence.

      • subSequence

        public ByteSequence subSequence​(int start,
                                int size)
        Returns a new byte sequence that is a subsequence of this byte sequence.

        The subsequence starts with the byte value at the specified start index and with size.

        NOTE: the returned subsequence will be robust against all updates to the byte string builder except for invocations of the method clear(). If a permanent immutable byte sequence is required then callers should invoke toByteString() on the returned byte sequence.

        Specified by:
        subSequence in interface ByteSequence
        Parameters:
        start - The start index, inclusive.
        size - The subsequence length.
        Returns:
        The newly created byte subsequence.

      • startsWith

        public boolean startsWith​(ByteSequence prefix)
        Description copied from interface: ByteSequence
        Tests if this ByteSequence starts with the specified prefix.
        Specified by:
        startsWith in interface ByteSequence
        Parameters:
        prefix - The prefix.
        Returns:
        true if the byte sequence represented by the argument is a prefix of the byte sequence represented by this ByteSequence; false otherwise. Note also that true will be returned if the argument is an empty sequence or is equal to this ByteSequence object as determined by the equals(Object) method.

      • toByteArray

        public byte[] toByteArray()
        Description copied from interface: ByteSequence
        Returns a byte array containing the bytes in this sequence in the same order as this sequence. The length of the byte array will be the length of this sequence.

        An invocation of the form: 

         src.toByteArray()
        Behaves in exactly the same way as the invocation: 
         src.copyTo(new byte[src.length()]);
        Specified by:
        toByteArray in interface ByteSequence
        Returns:
        A byte array consisting of exactly this sequence of bytes.

      • toByteString

        public ByteString toByteString()
        Returns the ByteString representation of this byte string builder. Subsequent changes to this byte string builder will not modify the returned ByteString.
        Specified by:
        toByteString in interface ByteSequence
        Returns:
        The ByteString representation of this byte sequence.

      • toByteStringAndClear

        public ByteString toByteStringAndClear()
        Returns the ByteString representation of this byte string builder, while resetting it to an empty byte string builder with a capacity of 0. Subsequent changes to this byte string builder will not modify the returned ByteString.

        When using this method, it is strongly advised to presize this builder to the final size if possible. This will make the resulting byte string use the minimal amount of memory.

        The differences between toByteString() and toByteStringAndClear() are as follows:

        • toByteString() copies the backing array, toByteStringAndClear() does not
        • toByteString() leaves the content of the backing array intact, toByteStringAndClear() clears the backing array, and reduces the capacity (contrary to clear())
        • toByteString() returns a ByteString where the backing array which has the exact same size as the length, toByteStringAndClear() reuses the backing array as-is without trimming it avoiding the array copy. Choosing one over the other is a trade-off between lower memory usage (toByteString()) and lower CPU usage (toByteStringAndClear()).
        Returns:
        The ByteString representation of this byte sequence.

      • toByteBuffer

        public ByteBuffer toByteBuffer()
        Returns the read-only ByteBuffer representation of this byte string builder. Because the ByteBuffer will share the same underlying byte array, subsequent changes to this byte string builder will modify the returned ByteBuffer.
        Specified by:
        toByteBuffer in interface ByteSequence
        Returns:
        The ByteBuffer representation of this byte sequence.

      • toString

        public String toString()
        Description copied from interface: ByteSequence
        Returns the UTF-8 decoded string representation of this byte sequence. If UTF-8 decoding fails, the platform's default encoding will be used.
        Specified by:
        toString in interface ByteSequence
        Overrides:
        toString in class Object
        Returns:
        The string representation of this byte sequence.