Package org.forgerock.opendj.ldap

Class ByteString

java.lang.Object
org.forgerock.opendj.ldap.ByteString
All Implemented Interfaces:
Comparable<ByteSequence>, ByteSequence
public final class ByteString extends Object implements ByteSequence
An immutable sequence of bytes backed by a byte array.

  • Field Summary

    Fields inherited from interface org.forgerock.opendj.ldap.ByteSequence

    BYTE_ARRAY_COMPARATOR, COMPARATOR

  • Method Summary

    Modifier and Type
    Method
    Description
    ByteSequenceReader
    asReader()
    Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte string.
    byte
    byteAt(int index)
    Returns the byte value at the specified index.
    int
    compareTo(byte[] bytes, int offset, int length)
    Compares this byte sequence with the specified byte array sub-sequence for order.
    int
    compareTo(ByteSequence o)
    Compares this byte sequence with the specified byte sequence for order.
    byte[]
    copyTo(byte[] bytes)
    Copies the contents of this byte sequence to the provided byte array.
    byte[]
    copyTo(byte[] bytes, int offset)
    Copies the contents of this byte sequence to the specified location in the provided byte array.
    OutputStream
    copyTo(OutputStream stream)
    Copies the entire contents of this byte sequence to the provided OutputStream.
    ByteBuffer
    copyTo(ByteBuffer byteBuffer)
    Appends the content of this byte sequence to the provided ByteBuffer starting at it's current position.
    boolean
    copyTo(CharBuffer charBuffer, CharsetDecoder decoder)
    Appends the content of this byte sequence decoded using provided charset decoder to the provided CharBuffer starting at it's current position.
    ByteStringBuilder
    copyTo(ByteStringBuilder builder)
    Appends the entire contents of this byte sequence to the provided ByteStringBuilder.
    static ByteString
    empty()
    Returns an empty byte string.
    boolean
    equals(byte[] bytes, int offset, int length)
    Indicates whether the provided byte array sub-sequence is equal to this byte sequence.
    boolean
    equals(Object o)
    Indicates whether the provided object is equal to this byte string.
    int
    hashCode()
    Returns a hash code for this byte string.
    boolean
    isEmpty()
    Returns true if this byte sequence has a length of zero.
    int
    length()
    Returns the length of this byte sequence.
    boolean
    startsWith(ByteSequence prefix)
    Tests if this ByteSequence starts with the specified prefix.
    ByteString
    subSequence(int start, int end)
    Returns a new byte sequence that is a subsequence of this byte sequence.
    String
    toASCIIString()
    Returns a 7-bit ASCII string representation.
    String
    toBase64String()
    Returns the Base64 encoded string representation of this byte string.
    byte[]
    toByteArray()
    Returns a byte array containing the bytes in this sequence in the same order as this sequence.
    ByteString
    toByteString()
    Returns the ByteString representation of this byte sequence.
    char[]
    toCharArray()
    Returns the UTF-8 decoded char array representation of this byte sequence.
    String
    toHexPlusAsciiString(int indent)
    Returns a string representation of the data in this byte sequence using the specified indent.
    String
    toHexString()
    Returns a string representation of the contents of this byte sequence using hexadecimal characters and a space between each byte.
    int
    toInt()
    Returns the integer value represented by the first four bytes of this byte string in big-endian order.
    long
    toLong()
    Returns the long value represented by the first eight bytes of this byte string in big-endian order.
    String
    toPercentHexString()
    Returns a string representation of the contents of this byte sequence using hexadecimal characters and a percent prefix (%) before each char.
    String
    toString()
    Returns the UTF-8 decoded string representation of this byte sequence.
    static ByteString
    valueOfBase64(String s)
    Returns a byte string containing the Base64 decoded bytes of the provided string.
    static ByteString
    valueOfBytes(byte[] bytes)
    Returns a byte string containing the contents of the provided byte array.
    static ByteString
    valueOfBytes(byte[] bytes, int offset, int length)
    Returns a byte string containing a subsequence of the contents of the provided byte array.
    static ByteString
    valueOfHex(String hexString)
    Returns a byte string containing the bytes of the provided hexadecimal string.
    static ByteString
    valueOfInt(int i)
    Returns a byte string containing the big-endian encoded bytes of the provided integer.
    static ByteString
    valueOfLong(long l)
    Returns a byte string containing the big-endian encoded bytes of the provided long.
    static ByteString
    valueOfObject(Object o)
    Returns a byte string representation of the provided object.
    static ByteString
    valueOfUtf8(char[] chars)
    Returns a byte string containing the UTF-8 encoded bytes of the provided char array.
    static ByteString
    valueOfUtf8(CharSequence s)
    Returns a byte string containing the UTF-8 encoded bytes of the provided char sequence.
    static ByteString
    wrap(byte[] bytes)
    Returns a byte string that wraps the provided byte array.
    static ByteString
    wrap(byte[] bytes, int offset, int length)
    Returns a byte string that wraps a subsequence of the provided byte array.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • empty

      public static ByteString empty()
      Returns an empty byte string.
      Returns:
      An empty byte string.

    • valueOfInt

      public static ByteString valueOfInt(int i)
      Returns a byte string containing the big-endian encoded bytes of the provided integer.
      Parameters:
      i - The integer to encode.
      Returns:
      The byte string containing the big-endian encoded bytes of the provided integer.

    • valueOfLong

      public static ByteString valueOfLong(long l)
      Returns a byte string containing the big-endian encoded bytes of the provided long.
      Parameters:
      l - The long to encode.
      Returns:
      The byte string containing the big-endian encoded bytes of the provided long.

    • valueOfObject

      public static ByteString valueOfObject(Object o)
      Returns a byte string representation of the provided object. 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 o.toByteString()
      • if the object is a byte[] then this method is equivalent to calling valueOfBytes(byte[])
      • if the object is a char[] then this method is equivalent to calling valueOfUtf8(char[])
      • for all other types of object this method is equivalent to calling valueOfUtf8(CharSequence) 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:
      • valueOf(0) is not equivalent to valueOf((Object) 0)
      • valueOf(0L) is not equivalent to valueOf((Object) 0L)
      Parameters:
      o - The object to use.
      Returns:
      The byte string containing the provided object.

    • valueOfUtf8

      public static ByteString valueOfUtf8(CharSequence s)
      Returns a byte string containing the UTF-8 encoded bytes of the provided char sequence.
      Parameters:
      s - The char sequence to use.
      Returns:
      The byte string with the encoded bytes of the provided string.

    • valueOfBase64

      public static ByteString valueOfBase64(String s)
      Returns a byte string containing the Base64 decoded bytes of the provided string.
      Parameters:
      s - The string to use.
      Returns:
      The byte string containing the Base64 decoded bytes of the provided string.
      Throws:
      org.forgerock.i18n.LocalizedIllegalArgumentException - If the provided string does not contain valid Base64 encoded content.
      See Also:

    • valueOfHex

      public static ByteString valueOfHex(String hexString)
      Returns a byte string containing the bytes of the provided hexadecimal string.
      Parameters:
      hexString - The hexadecimal string to convert to a byte array.
      Returns:
      The byte string containing the binary representation of the provided hex string.
      Throws:
      org.forgerock.i18n.LocalizedIllegalArgumentException - If the provided string contains invalid hexadecimal digits or does not contain an even number of digits.

    • valueOfBytes

      public static ByteString valueOfBytes(byte[] bytes)
      Returns a byte string containing the contents of the provided byte array.

      This method differs from wrap(byte[]) in that it defensively copies the provided byte array.

      Parameters:
      bytes - The byte array to use.
      Returns:
      A byte string containing a copy of the provided byte array.

    • valueOfBytes

      public static ByteString valueOfBytes(byte[] bytes, int offset, int length)
      Returns a byte string containing a subsequence of the contents of the provided byte array.

      This method differs from wrap(byte[], int, int) in that it defensively copies the provided byte array.

      Parameters:
      bytes - The byte array to use.
      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:
      A byte string containing a copy of the subsequence of the provided byte array.

    • valueOfUtf8

      public static ByteString valueOfUtf8(char[] chars)
      Returns a byte string containing the UTF-8 encoded bytes of the provided char array.
      Parameters:
      chars - The char array to use.
      Returns:
      A byte string containing the UTF-8 encoded bytes of the provided char array.

    • wrap

      public static ByteString wrap(byte[] bytes)
      Returns a byte string that wraps the provided byte array.

      NOTE: this method takes ownership of the provided byte array and, therefore, the byte array MUST NOT be altered directly after this method returns.

      Parameters:
      bytes - The byte array to wrap.
      Returns:
      The byte string that wraps the given byte array.

    • wrap

      public static ByteString wrap(byte[] bytes, int offset, int length)
      Returns a byte string that wraps a subsequence of the provided byte array.

      NOTE: this method takes ownership of the provided byte array and, therefore, the byte array MUST NOT be altered directly after this method returns.

      Parameters:
      bytes - The byte array to wrap.
      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:
      The byte string that wraps the given byte array.
      Throws:
      IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.

    • toASCIIString

      public String toASCIIString()
      Returns a 7-bit ASCII string representation. Non-ASCII characters will be expanded to percent (%) hexadecimal value.
      Returns:
      a 7-bit ASCII string representation

    • asReader

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

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

    • compareTo

      public int compareTo(byte[] bytes, int offset, int length)
      Description copied from interface: ByteSequence
      Compares this byte sequence with the specified byte array sub-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 byte array sub-sequence.
      Specified by:
      compareTo in interface ByteSequence
      Parameters:
      bytes - The byte array to compare.
      offset - The offset of the sub-sequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
      length - The length of the sub-sequence 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 sub-sequence.

    • 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 ByteStringBuilder copyTo(ByteStringBuilder builder)
      Description copied from interface: ByteSequence
      Appends the entire contents of this byte sequence to the provided ByteStringBuilder.
      Specified by:
      copyTo in interface ByteSequence
      Parameters:
      builder - The builder to copy to.
      Returns:
      The builder.

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

    • equals

      public boolean equals(byte[] bytes, int offset, int length)
      Description copied from interface: ByteSequence
      Indicates whether the provided byte array sub-sequence is equal to this byte sequence. In order for it to be considered equal, the provided byte array sub-sequence 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 sub-sequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
      length - The length of the sub-sequence 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 sub-sequence 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. 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, or false if not.

    • hashCode

      public int hashCode()
      Returns a hash code for this byte string. It will be the sum of all of the bytes contained in the byte string.
      Specified by:
      hashCode in interface ByteSequence
      Overrides:
      hashCode in class Object
      Returns:
      A hash code for this byte string.

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

    • subSequence

      public ByteString subSequence(int start, int end)
      Description copied from interface: ByteSequence
      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 byte value at index end - 1. The length (in bytes) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

      NOTE: changes to the underlying byte sequence (if mutable) may render the returned sub-sequence invalid.

      Specified by:
      subSequence in interface ByteSequence
      Parameters:
      start - The start index, inclusive.
      end - The end index, exclusive.
      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.

    • toBase64String

      public String toBase64String()
      Description copied from interface: ByteSequence
      Returns the Base64 encoded string representation of this byte string.
      Specified by:
      toBase64String in interface ByteSequence
      Returns:
      The Base64 encoded string representation of this byte string.
      See Also:

    • toHexString

      public String toHexString()
      Returns a string representation of the contents of this byte sequence using hexadecimal characters and a space between each byte.
      Returns:
      A string representation of the contents of this byte sequence using hexadecimal characters.

    • toPercentHexString

      public String toPercentHexString()
      Returns a string representation of the contents of this byte sequence using hexadecimal characters and a percent prefix (%) before each char.
      Returns:
      A string representation of the contents of this byte sequence using percent + hexadecimal characters.

    • toHexPlusAsciiString

      public String toHexPlusAsciiString(int indent)
      Returns a string representation of the data in this byte sequence using the specified indent.

      The data will be formatted with sixteen hex bytes in a row followed by the ASCII representation, then wrapping to a new line as necessary. The state of the byte buffer is not changed.

      Parameters:
      indent - The number of spaces to indent the output.
      Returns:
      the string representation of this byte string

    • 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()
      Description copied from interface: ByteSequence
      Returns the ByteString representation of this byte sequence.
      Specified by:
      toByteString in interface ByteSequence
      Returns:
      The ByteString representation of this byte sequence.

    • toCharArray

      public char[] toCharArray()
      Returns the UTF-8 decoded char array representation of this byte sequence.
      Returns:
      The UTF-8 decoded char array representation of this byte sequence.

    • toInt

      public int toInt()
      Returns the integer value represented by the first four bytes of this byte string in big-endian order.
      Returns:
      The integer value represented by the first four bytes of this byte string in big-endian order.
      Throws:
      IndexOutOfBoundsException - If this byte string has less than four bytes.

    • toLong

      public long toLong()
      Returns the long value represented by the first eight bytes of this byte string in big-endian order.
      Returns:
      The long value represented by the first eight bytes of this byte string in big-endian order.
      Throws:
      IndexOutOfBoundsException - If this byte string has less than eight bytes.

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