Package org.forgerock.opendj.ldap

Class ByteStringBuilder

java.lang.Object
java.io.OutputStream
org.forgerock.opendj.ldap.ByteStringBuilder
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable
public final class ByteStringBuilder extends OutputStream
A mutable sequence of bytes backed by a byte array.

  • Field Details

    • MAX_COMPACT_SIZE

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

  • Constructor Details

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

    • 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(byte[] bytes)
      Appends the provided bytes to this byte string builder. Equivalent to appendBytes(byte[]).
      Overrides:
      write in class OutputStream

    • write

      public void write(byte[] bytes, int i, int i1)
      Appends the provided bytes to this byte string builder. Equivalent to appendBytes(byte[], int, int).
      Overrides:
      write in class OutputStream

    • 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

    • flush

      public void flush()
      Implementation of OutputStream.flush() which doesn't do anything because data is written directly to a byte array.
      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class OutputStream

    • close

      public void close()
      Implementation of OutputStream.close() which doesn't do anything because data is written directly to a byte array.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close 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.