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​(ByteString bs)
        Creates a new byte string builder with the content of the provided ByteString. Its capacity is set to the length of the provided ByteString.
        Parameters:
        bs - The ByteString to copy

      • ByteStringBuilder

        public ByteStringBuilder​(ByteStringBuilder bs)
        Creates a new byte string builder with the content of the provided byte string builder. Its capacity is set to the capacity of the provided byte string builder.
        Parameters:
        bs - The ByteStringBuilder 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​(ByteString bytes)
        Appends the provided ByteString to this byte string builder.
        Parameters:
        bytes - The byte string to be appended to this byte string builder.
        Returns:
        This byte string builder.

      • appendBytes

        public ByteStringBuilder appendBytes​(ByteStringReader reader,
                                     int length)
        Appends the provided ByteStringReader to this byte string builder.
        Parameters:
        reader - The byte string 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 ByteString then this method is equivalent to calling appendBytes(ByteString)
        • 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.

      • write

        public void write​(int i)
        Appends the provided byte to this byte string builder. Equivalent to appendByte(int).
        Specified by:
        write in class OutputStream

      • isEmpty

        public boolean isEmpty()
        Returns true if this byte string builder has a length of zero.
        Returns:
        true if this byte string builder has a length of zero.

      • length

        public int length()
        Returns the length of this byte string builder.
        Returns:
        The length of this byte string builder.

      • setByte

        public ByteStringBuilder 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 byte string 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.
        Returns:
        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.

      • toByteArray

        public byte[] toByteArray()
        Returns a byte array containing the contents of this byte string builder. On return, this byte string builder will be reset to a capacity of 0. Subsequent changes to this byte string builder will not impact the returned byte array and vice versa.
        Returns:
        A byte array containing the contents of this byte string builder.

      • toByteString

        public ByteString toByteString()
        Returns a ByteString containing the contents of this byte string builder. On return, this byte string builder will be reset to a capacity of 0. Subsequent changes to this byte string builder will not impact the returned ByteString.
        Returns:
        The ByteString containing the contents of this byte string builder.

      • toByteBuffer

        public ByteBuffer toByteBuffer()
        Returns a modifiable ByteBuffer containing the contents of this byte string builder. On return, this byte string builder will be reset to a capacity of 0. Subsequent changes to this byte string builder will not impact the returned ByteBuffer and vice versa.
        Returns:
        The ByteBuffer containing the contents of this byte string builder.

      • toString

        public String toString()
        Returns the UTF-8 decoded string representation of this byte string builder. If UTF-8 decoding fails, the platform's default encoding will be used.
        Overrides:
        toString in class Object
        Returns:
        The string representation of this byte string builder.