mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/ByteSequence.java
@@ -6,17 +6,16 @@ * (the "License"). You may not use this file except in compliance * with the License. * * You can obtain a copy of the license at * trunk/opendj3/legal-notices/CDDLv1_0.txt * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt * or http://forgerock.org/license/CDDLv1.0.html. * See the License for the specific language governing permissions * and limitations under the License. * * When distributing Covered Code, include this CDDL HEADER in each * file and include the License file at * trunk/opendj3/legal-notices/CDDLv1_0.txt. If applicable, * add the following below this CDDL HEADER, with the fields enclosed * by brackets "[]" replaced with your own identifying information: * file and include the License file at legal-notices/CDDLv1_0.txt. * If applicable, add the following below this CDDL HEADER, with the * fields enclosed by brackets "[]" replaced with your own identifying * information: * Portions Copyright [yyyy] [name of copyright owner] * * CDDL HEADER END @@ -27,301 +26,272 @@ */ package org.forgerock.opendj.ldap; import java.io.IOException; import java.io.OutputStream; /** * 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> { public interface ByteSequence extends Comparable<ByteSequence> { /** * 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. */ ByteSequenceReader asReader(); /** * 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. */ ByteSequenceReader asReader(); /** * 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. * * @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(). */ byte byteAt(int index); /** * 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 bytes * 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 bytes.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 bytes.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 bytes.length}. */ int compareTo(byte[] bytes, int offset, int length); /** * 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. * * @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(). */ byte byteAt(int index); /** * 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. */ int compareTo(ByteSequence o); /** * 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. * <p> * An invocation of the form: * * <pre> * src.copyTo(bytes) * </pre> * * Behaves in exactly the same way as the invocation: * * <pre> * src.copyTo(bytes, 0); * </pre> * * @param bytes * The byte array to which bytes are to be copied. * @return The byte array. */ byte[] copyTo(byte[] bytes); /** * 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. * <p> * An invocation of the form: * * <pre> * src.copyTo(bytes, offset) * </pre> * * Behaves in exactly the same way as the invocation: * * <pre> * int len = Math.min(src.length(), bytes.length - offset); * for (int i = 0; i < len; i++) * bytes[offset + i] = src.get(i); * </pre> * * Except that it is potentially much more efficient. * * @param bytes * 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 bytes.length. * @return The byte array. * @throws IndexOutOfBoundsException * If {@code offset} is negative. */ byte[] copyTo(byte[] bytes, int offset); /** * 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 bytes * 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 bytes.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 bytes.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 bytes.length}. */ int compareTo(byte[] bytes, int offset, int length); /** * Appends the entire contents of this byte sequence to the provided * {@link ByteStringBuilder}. * * @param builder * The builder to copy to. * @return The builder. */ ByteStringBuilder copyTo(ByteStringBuilder builder); /** * 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}. */ 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. * * @param bytes * 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 bytes.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 bytes.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 bytes.length}. */ boolean equals(byte[] bytes, int offset, int length); /** * 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. */ int compareTo(ByteSequence o); /** * 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. */ 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. * * @return A hash code for this byte sequence. */ int hashCode(); /** * Returns the length of this byte sequence. * * @return The length of this byte sequence. */ int length(); /** * 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. * <p> * An invocation of the form: * * <pre> * src.copyTo(bytes) * </pre> * * Behaves in exactly the same way as the invocation: * * <pre> * src.copyTo(bytes, 0); * </pre> * * @param bytes * The byte array to which bytes are to be copied. * @return The byte array. */ byte[] copyTo(byte[] bytes); /** * 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. * <p> * <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}. */ ByteSequence subSequence(int start, int end); /** * 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(); /** * Returns the {@link ByteString} representation of this byte sequence. * * @return The {@link ByteString} representation of this byte sequence. */ ByteString toByteString(); /** * 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. * <p> * An invocation of the form: * * <pre> * src.copyTo(bytes, offset) * </pre> * * Behaves in exactly the same way as the invocation: * * <pre> * int len = Math.min(src.length(), bytes.length - offset); * for (int i = 0; i < len; i++) * bytes[offset + i] = src.get(i); * </pre> * * Except that it is potentially much more efficient. * * @param bytes * 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 bytes.length. * @return The byte array. * @throws IndexOutOfBoundsException * If {@code offset} is negative. */ byte[] copyTo(byte[] bytes, int offset); /** * Appends the entire contents of this byte sequence to the provided * {@link ByteStringBuilder}. * * @param builder * The builder to copy to. * @return The builder. */ ByteStringBuilder copyTo(ByteStringBuilder builder); /** * 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}. */ 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. * * @param bytes * 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 bytes.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 bytes.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 bytes.length}. */ boolean equals(byte[] bytes, int offset, int length); /** * 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. */ 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. * * @return A hash code for this byte sequence. */ int hashCode(); /** * Returns the length of this byte sequence. * * @return The length of this byte sequence. */ int length(); /** * 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. * <p> * <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}. */ ByteSequence subSequence(int start, int end); /** * 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(); /** * 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. * * @return The string representation of this byte sequence. */ 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. * * @return The string representation of this byte sequence. */ String toString(); }
