mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
sdk/src/org/opends/sdk/ByteSequence.java
@@ -33,24 +33,22 @@ /** * A {@code ByteSequence} is a readable sequence of byte values. This * interface provides uniform, read-only access to many different kinds * of byte sequences. * A {@code ByteSequence} is a readable sequence of byte values. This interface * provides uniform, read-only access to many different kinds of byte sequences. */ public interface ByteSequence extends Comparable<ByteSequence> { /** * Returns a {@link ByteSequenceReader} which can be used to * incrementally read and decode data from this byte sequence. * Returns a {@link ByteSequenceReader} which can be used to incrementally * read and decode data from this byte sequence. * <p> * <b>NOTE:</b> any concurrent changes to the underlying byte sequence * (if mutable) may cause subsequent reads to overrun and fail. * * @return The {@link ByteSequenceReader} which can be used to * incrementally read and decode data from this byte sequence. * <b>NOTE:</b> any concurrent changes to the underlying byte sequence (if * mutable) may cause subsequent reads to overrun and fail. * * @return The {@link ByteSequenceReader} which can be used to incrementally * read and decode data from this byte sequence. */ ByteSequenceReader asReader(); @@ -59,45 +57,40 @@ /** * Returns the byte value at the specified index. * <p> * An index ranges from zero to {@code 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. * * An index ranges from zero to {@code 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. * * @param index * The index of the byte to be returned. * @return The byte value at the specified index. * @throws IndexOutOfBoundsException * If the index argument is negative or not less than * length(). * If the index argument is negative or not less than length(). */ byte byteAt(int index) throws 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. * * 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. * * @param b * The byte array to compare. * @param offset * The offset of the sub-sequence in the byte array to be * compared; must be non-negative and no larger than {@code * b.length} . * The offset of the sub-sequence in the byte array to be compared; * must be non-negative and no larger than {@code b.length} . * @param length * The length of the sub-sequence in the byte array to be * compared; must be non-negative and no larger than {@code * b.length - offset}. * @return 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. * The length of the sub-sequence in the byte array to be compared; * must be non-negative and no larger than {@code b.length - offset}. * @return 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 IndexOutOfBoundsException * If {@code offset} is negative or if {@code length} is * negative or if {@code offset + length} is greater than * {@code b.length}. * If {@code offset} is negative or if {@code length} is negative or * if {@code offset + length} is greater than {@code b.length}. */ int compareTo(byte[] b, int offset, int length) throws IndexOutOfBoundsException; @@ -105,41 +98,39 @@ /** * 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. * * 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. * * @param o * The byte sequence to be compared. * @return 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. * @return 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. */ int compareTo(ByteSequence o); /** * Copies the contents of this byte sequence to the provided byte * array. * Copies the contents of this byte sequence to the provided byte array. * <p> * 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. * 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. * <p> * An invocation of the form: * * * <pre> * src.copyTo(b) * </pre> * * * Behaves in exactly the same way as the invocation: * * * <pre> * src.copyTo(b, 0); * </pre> * * * @param b * The byte array to which bytes are to be copied. * @return The byte array. @@ -149,34 +140,33 @@ /** * Copies the contents of this byte sequence to the specified location * in the provided byte array. * Copies the contents of this byte sequence to the specified location in the * provided byte array. * <p> * 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. * 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. * <p> * An invocation of the form: * * * <pre> * src.copyTo(b, offset) * </pre> * * * Behaves in exactly the same way as the invocation: * * * <pre> * int len = Math.min(src.length(), b.length - offset); * for (int i = 0; i < len; i++) * b[offset + i] = src.get(i); * </pre> * * * Except that it is potentially much more efficient. * * * @param b * The byte array to which bytes are to be copied. * @param offset * The offset within the array of the first byte to be * written; must be non-negative and no larger than b.length. * The offset within the array of the first byte to be written; must * be non-negative and no larger than b.length. * @return The byte array. * @throws IndexOutOfBoundsException * If {@code offset} is negative. @@ -188,7 +178,7 @@ /** * Appends the entire contents of this byte sequence to the provided * {@link ByteStringBuilder}. * * * @param builder * The builder to copy to. * @return The builder. @@ -198,43 +188,37 @@ /** * Copies the entire contents of this byte sequence to the provided * {@code OutputStream}. * * Copies the entire contents of this byte sequence to the provided {@code * OutputStream}. * * @param stream * The {@code OutputStream} to copy to. * @return The {@code OutputStream}. * @throws IOException * If an error occurs while writing to the {@code * OutputStream}. * If an error occurs while writing to the {@code OutputStream}. */ OutputStream copyTo(OutputStream stream) throws IOException; /** * 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. * * 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. * * @param b * The byte array for which to make the determination. * @param offset * The offset of the sub-sequence in the byte array to be * compared; must be non-negative and no larger than {@code * b.length} . * The offset of the sub-sequence in the byte array to be compared; * must be non-negative and no larger than {@code b.length} . * @param length * The length of the sub-sequence in the byte array to be * compared; must be non-negative and no larger than {@code * b.length - offset}. * @return {@code true} if the content of the provided byte array * sub-sequence is equal to that of this byte sequence, or * {@code false} if not. * The length of the sub-sequence in the byte array to be compared; * must be non-negative and no larger than {@code b.length - offset}. * @return {@code true} if the content of the provided byte array sub-sequence * is equal to that of this byte sequence, or {@code false} if not. * @throws IndexOutOfBoundsException * If {@code offset} is negative or if {@code length} is * negative or if {@code offset + length} is greater than * {@code b.length}. * If {@code offset} is negative or if {@code length} is negative or * if {@code offset + length} is greater than {@code b.length}. */ boolean equals(byte[] b, int offset, int length) throws IndexOutOfBoundsException; @@ -242,25 +226,24 @@ /** * Indicates whether the provided object is equal to this byte * sequence. In order for it to be considered equal, the provided * object must be a byte sequence containing the same bytes in the * same order. * * Indicates whether the provided object is equal to this byte sequence. In * order for it to be considered equal, the provided object must be a byte * sequence containing the same bytes in the same order. * * @param o * The object for which to make the determination. * @return {@code true} if the provided object is a byte sequence * whose content is equal to that of this byte sequence, or * {@code false} if not. * @return {@code true} if the provided object is a byte sequence whose * content is equal to that of this byte sequence, or {@code false} if * not. */ boolean equals(Object o); /** * Returns a hash code for this byte sequence. It will be the sum of * all of the bytes contained in the byte sequence. * * Returns a hash code for this byte sequence. It will be the sum of all of * the bytes contained in the byte sequence. * * @return A hash code for this byte sequence. */ int hashCode(); @@ -269,7 +252,7 @@ /** * Returns the length of this byte sequence. * * * @return The length of this byte sequence. */ int length(); @@ -277,50 +260,47 @@ /** * Returns a new byte sequence that is a subsequence of this byte * sequence. * Returns a new byte sequence that is a subsequence of this byte sequence. * <p> * The subsequence starts with the byte value at the specified {@code * start} index and ends with the byte value at index {@code end - 1}. * The length (in bytes) of the returned sequence is {@code end - * start}, so if {@code start == end} then an empty sequence is * returned. * The subsequence starts with the byte value at the specified {@code start} * index and ends with the byte value at index {@code end - 1}. The length (in * bytes) of the returned sequence is {@code end - start}, so if {@code start * == end} then an empty sequence is returned. * <p> * <b>NOTE:</b> changes to the underlying byte sequence (if mutable) * may render the returned sub-sequence invalid. * * <b>NOTE:</b> changes to the underlying byte sequence (if mutable) may * render the returned sub-sequence invalid. * * @param start * The start index, inclusive. * @param end * The end index, exclusive. * @return The newly created byte subsequence. * @throws IndexOutOfBoundsException * If {@code start} or {@code end} are negative, if {@code * end} is greater than {@code length()}, or if {@code * start} is greater than {@code end}. * If {@code start} or {@code end} are negative, if {@code end} is * greater than {@code length()}, or if {@code start} is greater * than {@code end}. */ ByteSequence subSequence(int start, int end) throws IndexOutOfBoundsException; ByteSequence subSequence(int start, int end) throws IndexOutOfBoundsException; /** * 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. * 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. * <p> * An invocation of the form: * * * <pre> * src.toByteArray() * </pre> * * * Behaves in exactly the same way as the invocation: * * * <pre> * src.copyTo(new byte[src.length()]); * </pre> * * * @return A byte array consisting of exactly this sequence of bytes. */ byte[] toByteArray(); @@ -328,21 +308,18 @@ /** * Returns the {@link ByteString} representation of this byte * sequence. * * @return The {@link ByteString} representation of this byte * sequence. * Returns the {@link ByteString} representation of this byte sequence. * * @return The {@link ByteString} representation of this byte sequence. */ ByteString toByteString(); /** * Returns the UTF-8 decoded string representation of this byte * sequence. If UTF-8 decoding fails, the platform's default encoding * will be used. * * Returns the UTF-8 decoded string representation of this byte sequence. If * UTF-8 decoding fails, the platform's default encoding will be used. * * @return The string representation of this byte sequence. */ String toString();
