Package org.forgerock.opendj.ldap

Class ByteString

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static ByteString[] asArray​(Object... objects)
      Returns an array containing the provided objects converted to byte strings using valueOfObject(Object).
      static List<ByteString> asList​(Object... objects)
      Returns a list containing the provided objects converted to byte strings using valueOfObject(Object).
      ByteStringReader asReader()
      Returns a ByteStringReader 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 string with the specified byte array subsequence for order.
      int compareTo​(ByteString o)
      Compares this byte string with the specified byte string for order.
      byte[] copyTo​(byte[] bytes)
      Copies the contents of this byte string to the provided byte array.
      byte[] copyTo​(byte[] bytes, int offset)
      Copies the contents of this byte string to the specified location in the provided byte array.
      OutputStream copyTo​(OutputStream stream)
      Copies the entire contents of this byte string to the provided OutputStream.
      ByteBuffer copyTo​(ByteBuffer byteBuffer)
      Appends the content of this byte string to the provided ByteBuffer starting at it's current position.
      boolean copyTo​(CharBuffer charBuffer, CharsetDecoder decoder)
      Appends the content of this byte string 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 string 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 subsequence is equal to this byte string.
      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.
      int intAt​(int index)
      Returns the big-endian int value at the specified index.
      boolean isEmpty()
      Returns true if this byte string has a length of zero.
      int length()
      Returns the length of this byte string.
      long longAt​(int index)
      Returns the big-endian long value at the specified index.
      short shortAt​(int index)
      Returns the big-endian short value at the specified index.
      boolean startsWith​(ByteString prefix)
      Tests if this ByteString starts with the specified prefix.
      ByteString subSequence​(int start)
      Returns a new byte string that is a subsequence of this byte string.
      ByteString subSequence​(int start, int size)
      Returns a new byte string that is a subsequence of this byte string.
      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 byte string in the same order as this byte string.
      ByteBuffer toByteBuffer()
      Returns the read-only ByteBuffer representation of this byte string.
      char[] toCharArray()
      Returns the UTF-8 decoded char array representation of this byte string.
      String toHexPlusAsciiString​(int indent)
      Returns a string representation of the data in this byte string using the specified indent.
      String toHexString()
      Returns a string representation of the contents of this byte string using hexadecimal characters.
      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 string using hexadecimal characters and a percent prefix (%) before each char.
      String toString()
      Returns the UTF-8 decoded string representation of this byte string.
      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​(CharSequence 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.

    • Method Detail

      • 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 ByteString 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:
        LocalizedIllegalArgumentException - If the provided string does not contain valid Base64 encoded content.
        See Also:
        toBase64String()

      • valueOfHex

        public static ByteString valueOfHex​(CharSequence 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:
        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.

      • asList

        public static List<ByteString> asList​(Object... objects)
        Returns a list containing the provided objects converted to byte strings using valueOfObject(Object).
        Parameters:
        objects - The list of objects to be converted to byte strings.
        Returns:
        The list containing the provided objects converted to byte strings using valueOfObject(Object).

      • asArray

        public static ByteString[] asArray​(Object... objects)
        Returns an array containing the provided objects converted to byte strings using valueOfObject(Object).
        Parameters:
        objects - The list of objects to be converted to byte strings.
        Returns:
        The array containing the provided objects converted to byte strings using valueOfObject(Object).

      • 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 ByteStringReader asReader()
        Returns a ByteStringReader which can be used to incrementally read and decode data from this byte string.
        Returns:
        The ByteStringReader which can be used to incrementally read and decode data from this byte string.

      • byteAt

        public byte byteAt​(int index)
        Returns 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 returned.
        Returns:
        The byte value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length().

      • shortAt

        public short shortAt​(int index)
        Returns the big-endian short value at the specified index.
        Parameters:
        index - The index of the short to be returned.
        Returns:
        The short value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 2.

      • intAt

        public int intAt​(int index)
        Returns the big-endian int value at the specified index.
        Parameters:
        index - The index of the int to be returned.
        Returns:
        The int value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 4.

      • longAt

        public long longAt​(int index)
        Returns the big-endian long value at the specified index.
        Parameters:
        index - The index of the long to be returned.
        Returns:
        The long value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 8.

      • compareTo

        public int compareTo​(byte[] bytes,
                     int offset,
                     int length)
        Compares this byte string with the specified byte array subsequence for order. Returns a negative integer, zero, or a positive integer depending on whether this byte string is less than, equal to, or greater than the specified byte array subsequence.
        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 string is less than, equal to, or greater than the specified byte array subsequence.
        Throws:
        IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.

      • compareTo

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

      • copyTo

        public byte[] copyTo​(byte[] bytes)
        Copies the contents of this byte string to the provided byte array.

        Copying will stop when either the entire content of this byte string 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);
        Parameters:
        bytes - The byte array to which bytes are to be copied.
        Returns:
        The byte array.

      • copyTo

        public byte[] copyTo​(byte[] bytes,
                     int offset)
        Copies the contents of this byte string to the specified location in the provided byte array.

        Copying will stop when either the entire content of this byte string 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.
        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.
        Throws:
        IndexOutOfBoundsException - If offset is negative.

      • copyTo

        public ByteBuffer copyTo​(ByteBuffer byteBuffer)
        Appends the content of this byte string to the provided ByteBuffer starting at it's current position. The position of the buffer is then incremented by the length of this byte string.
        Parameters:
        byteBuffer - The buffer to copy to. It must be large enough to receive all bytes.
        Returns:
        The buffer.
        Throws:
        BufferOverflowException - If there is insufficient space in the provided buffer

      • copyTo

        public boolean copyTo​(CharBuffer charBuffer,
                      CharsetDecoder decoder)
        Appends the content of this byte string 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 byte string.
        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
        Copies the entire contents of this byte string to the provided OutputStream.
        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)
        Indicates whether the provided byte array subsequence is equal to this byte string. In order for it to be considered equal, the provided byte array subsequence must contain the same bytes in the same order.
        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 string, or false if not.
        Throws:
        IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.

      • 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 string containing the same bytes in the same order.
        Overrides:
        equals in class Object
        Parameters:
        o - The object for which to make the determination.
        Returns:
        true if the provided object is a byte string 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.
        Overrides:
        hashCode in class Object
        Returns:
        A hash code for this byte string.

      • isEmpty

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

      • length

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

      • subSequence

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

        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 byte string is length() - start, so if start == length() then an empty byte string is returned.

        NOTE: changes to the underlying byte string (if mutable) may render the returned subsequence invalid.

        Parameters:
        start - The start index, inclusive.
        Returns:
        The newly created byte subsequence.
        Throws:
        IndexOutOfBoundsException - If start is negative, if start is greater than length()

      • subSequence

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

        The subsequence starts with the byte value at the specified start index and is length long.

        NOTE: changes to the underlying byte string (if mutable) may render the returned subsequence invalid.

        Parameters:
        start - The start index, inclusive.
        size - The length of subsequence.
        Returns:
        The newly created byte subsequence.
        Throws:
        IndexOutOfBoundsException - If start is negative, if size is negative, if start + size is greater than length().

      • startsWith

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

      • toBase64String

        public String toBase64String()
        Returns the Base64 encoded string representation of this byte string.
        Returns:
        The Base64 encoded string representation of this byte string.
        See Also:
        valueOfBase64(String)

      • toHexString

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

      • toPercentHexString

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

      • toHexPlusAsciiString

        public String toHexPlusAsciiString​(int indent)
        Returns a string representation of the data in this byte string 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()
        Returns a byte array containing the bytes in this byte string in the same order as this byte string. The length of the byte array will be the length of this byte string.

        An invocation of the form: 

         src.toByteArray()
        Behaves in exactly the same way as the invocation: 
         src.copyTo(new byte[src.length()]);
        Returns:
        A byte array whose content is the same as this byte string.

      • toByteBuffer

        public ByteBuffer toByteBuffer()
        Returns the read-only ByteBuffer representation of this byte string.
        Returns:
        The read-only ByteBuffer representation of this byte string.

      • toCharArray

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

      • 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()
        Returns the UTF-8 decoded string representation of this byte string. 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.