/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* 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 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
|
*
|
*
|
* Copyright 2009 Sun Microsystems, Inc.
|
* Portions copyright 2011-2012 ForgeRock AS
|
*/
|
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> {
|
|
/**
|
* 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);
|
|
/**
|
* 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);
|
|
/**
|
* 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 the Base64 encoded string representation of this byte string.
|
*
|
* @return The Base64 encoded string representation of this byte string.
|
* @see ByteString#valueOfBase64(String)
|
*/
|
String toBase64String();
|
|
/**
|
* 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();
|
}
|
