ByteString (Oracle Fusion Middleware Java API Reference for Oracle Unified Directory)

java.lang.Object
- oracle.oud.types.ByteString

All Implemented Interfaces:

java.lang.Comparable<ByteSequence>, ByteSequence
```
public final class ByteString
extends java.lang.Object
implements ByteSequence
```
An immutable sequence of bytes backed by a byte array.

Method Summary

Methods
Modifier and Type	Method and 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[] b, 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[] b)` Copies the contents of this byte sequence to the provided byte array.
`byte[]`	`copyTo(byte[] b, int offset)` Copies the contents of this byte sequence to the specified location in the provided byte array.
`ByteStringBuilder`	`copyTo(ByteStringBuilder builder)` Appends the entire contents of this byte sequence to the provided `ByteStringBuilder`.
`java.io.OutputStream`	`copyTo(java.io.OutputStream stream)` Copies the entire contents of this byte sequence to the provided `OutputStream`.
`static ByteString`	`empty()` Returns an empty byte string.
`boolean`	`equals(byte[] b, int offset, int length)` Indicates whether the provided byte array sub-sequence is equal to this byte sequence.
`boolean`	`equals(java.lang.Object o)` Indicates whether the provided object is equal to this byte string.
`int`	`hashCode()` Returns a hash code for this byte string.
`static ByteString`	`hexValueOf(int i)` Returns a byte string following those steps: - The integer is transformed into its hexadecimal representation with 8 digits.
`int`	`length()` Returns the length of this byte sequence.
`ByteString`	`subSequence(int start, int end)` Returns a new byte sequence that is a subsequence of this byte sequence.
`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.
`java.lang.String`	`toHex()` Returns a string representation of the contents of this byte sequence using hexadecimal characters and a space between each byte.
`void`	`toHex(java.lang.StringBuilder builder, int indent)` Appends a string representation of the data in this byte sequence to the given buffer using the specified indent.
`void`	`toHexPlusAscii(java.lang.StringBuilder builder, int indent)` Appends a string representation of the data in this byte sequence to the given buffer using the specified indent.
`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.
`java.lang.String`	`toString()` Returns the UTF-8 decoded string representation of this byte sequence.
`static ByteString`	`valueOf(char[] chars)` Returns a byte string containing the UTF-8 encoded bytes of the provided char array.
`static ByteString`	`valueOf(int i)` Returns a byte string containing the big-endian encoded bytes of the provided integer.
`static ByteString`	`valueOf(long l)` Returns a byte string containing the big-endian encoded bytes of the provided long.
`static ByteString`	`valueOf(java.lang.Object o)` Returns a byte string containing the provided object.
`static ByteString`	`valueOf(java.lang.String s)` Returns a byte string containing the UTF-8 encoded bytes of the provided string.
`static ByteString`	`wrap(byte[] b)` Returns a byte string that wraps the provided byte array.
`static ByteString`	`wrap(byte[] b, 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 Detail
  - empty
```
public static ByteString empty()
```
    Returns an empty byte string.
    
    Returns:
    
    An empty byte string.
  - valueOf
```
public static ByteString valueOf(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.
  - hexValueOf
```
public static ByteString hexValueOf(int i)
```
    Returns a byte string following those steps: - The integer is transformed into its hexadecimal representation with 8 digits. For instance 500000 gives 0x0007A120 (using uppercase digits) - The 8 digits are stored in a 8 bytes length byte array with the ascii code of the hexadecimal digit. For instance 0x0007A120 gives the following byte array: [48, 48, 48, 55, 65, 49, 50, 48] (which represents [0 , 0 , 0 , 7 , A , 1 , 2 , 0 ] ) WARNING: ONly positive values are accepted as parameter (transformation does no permit a minus sign). Big-endian is used for this method.
    
    Parameters:
    
    i - The integer to encode.
    
    Returns:
    
    The byte string containing integer in it hexadecimal form as 8 bytes array of ascii codes.
  - valueOf
```
public static ByteString valueOf(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.
  - valueOf
```
public static ByteString valueOf(java.lang.Object o)
```
    Returns a byte string containing the provided object. If the object is an instance of ByteSequence then it is converted to a byte string using the toByteString() method. Otherwise a new byte string is created containing the UTF-8 encoded bytes of the string representation of the provided object.
    
    Parameters:
    
    o - The object to use.
    
    Returns:
    
    The byte string containing the provided object.
  - valueOf
```
public static ByteString valueOf(java.lang.String s)
```
    Returns a byte string containing the UTF-8 encoded bytes of the provided string.
    
    Parameters:
    
    s - The string to use.
    
    Returns:
    
    The byte string with the encoded bytes of the provided string.
  - valueOf
```
public static ByteString valueOf(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[] b)
```
    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:
    
    b - The byte array to wrap.
    
    Returns:
    
    The byte string that wraps the given byte array.
  - wrap
```
public static ByteString wrap(byte[] b,
              int offset,
              int length)
                       throws java.lang.IndexOutOfBoundsException
```
    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:
    
    b - The byte array to wrap.
    
    offset - The offset of the byte array to be used; must be non-negative and no larger than b.length .
    
    length - The length of the byte array to be used; must be non-negative and no larger than b.length - offset.
    
    Returns:
    
    The byte string that wraps the given byte array.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.length.
  - 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)
            throws java.lang.IndexOutOfBoundsException
```
    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.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If the index argument is negative or not less than length().
  - compareTo
```
public int compareTo(byte[] b,
            int offset,
            int length)
              throws java.lang.IndexOutOfBoundsException
```
    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:
    
    b - 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 b.length .
    
    length - The length of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.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.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.length.
  - compareTo
```
public int compareTo(ByteSequence o)
```
    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 java.lang.Comparable<ByteSequence>
    
    Specified by:
    
    compareTo in interface 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[] b)
```
    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(b)
 
```
    Behaves in exactly the same way as the invocation:
```
 src.copyTo(b, 0);
 
```
    Specified by:
    
    copyTo in interface ByteSequence
    
    Parameters:
    
    b - The byte array to which bytes are to be copied.
    
    Returns:
    
    The byte array.
  - copyTo
```
public byte[] copyTo(byte[] b,
            int offset)
              throws java.lang.IndexOutOfBoundsException
```
    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(b, offset)
 
```
    Behaves in exactly the same way as the invocation:
```
 int len = Math.min(src.length(), b.length - offset);
 for (int i = 0; i < len; i++)
   b[offset + i] = src.get(i);
 
```
    Except that it is potentially much more efficient.
    Specified by:
    
    copyTo in interface ByteSequence
    
    Parameters:
    
    b - 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 b.length.
    
    Returns:
    
    The byte array.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If offset is negative.
  - copyTo
```
public ByteStringBuilder copyTo(ByteStringBuilder builder)
```
    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 java.io.OutputStream copyTo(java.io.OutputStream stream)
                            throws java.io.IOException
```
    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:
    
    java.io.IOException - If an error occurs while writing to the OutputStream.
  - equals
```
public boolean equals(byte[] b,
             int offset,
             int length)
               throws java.lang.IndexOutOfBoundsException
```
    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:
    
    b - 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 b.length .
    
    length - The length of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.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.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.length.
  - equals
```
public boolean equals(java.lang.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 java.lang.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 java.lang.Object
    
    Returns:
    
    A hash code for this byte string.
  - length
```
public int length()
```
    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)
                       throws java.lang.IndexOutOfBoundsException
```
    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.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If start or end are negative, if end is greater than length(), or if start is greater than end.
  - toByteArray
```
public byte[] toByteArray()
```
    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 sequence.
    
    Specified by:
    
    toByteString in interface ByteSequence
    
    Returns:
    
    The ByteString representation of this byte sequence.
  - toHex
```
public java.lang.String toHex()
```
    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.
  - toHexPlusAscii
```
public void toHexPlusAscii(java.lang.StringBuilder builder,
                  int indent)
```
    Appends a string representation of the data in this byte sequence to the given buffer 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:
    
    builder - The buffer to which the information is to be appended.
    
    indent - The number of spaces to indent the output.
  - toHex
```
public void toHex(java.lang.StringBuilder builder,
         int indent)
```
    Appends a string representation of the data in this byte sequence to the given buffer using the specified indent.
    The data will be formatted with sixteen hex bytes in a row then wrapping to a new line as necessary. The state of the byte buffer is not changed.
    
    Parameters:
    
    builder - The buffer to which the information is to be appended.
    
    indent - The number of spaces to indent the output.
  - 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()
          throws java.lang.IndexOutOfBoundsException
```
    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:
    
    java.lang.IndexOutOfBoundsException - If this byte string has less than four bytes.
  - toLong
```
public long toLong()
            throws java.lang.IndexOutOfBoundsException
```
    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:
    
    java.lang.IndexOutOfBoundsException - If this byte string has less than eight bytes.
  - toString
```
public java.lang.String toString()
```
    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 java.lang.Object
    
    Returns:
    
    The string representation of this byte sequence.

Class ByteString

Method Summary

Methods inherited from class java.lang.Object

Method Detail

empty

valueOf

hexValueOf

valueOf

valueOf

valueOf

valueOf

wrap

wrap

asReader

byteAt

compareTo

compareTo

copyTo

copyTo

copyTo

copyTo

equals

equals

hashCode

length

subSequence

toByteArray

toByteString

toHex

toHexPlusAscii

toHex

toCharArray

toInt

toLong

toString