Skip navigation links

oracle.oud.types
Class ByteStringBuilder

java.lang.Object
oracle.oud.types.ByteStringBuilder

All Implemented Interfaces:

java.lang.Comparable<ByteSequence>, ByteSequence

public final class ByteStringBuilder

extends java.lang.Object

implements ByteSequence

A mutable sequence of bytes backed by a byte array.

Constructor Summary

ByteStringBuilder()
Creates a new byte string builder with an initial capacity of 32 bytes.

ByteStringBuilder(int capacity)
Creates a new byte string builder with the specified initial capacity.

Method Summary

ByteStringBuilder	append(byte b) Appends the provided byte to this byte string builder.
ByteStringBuilder	append(byte[] b) Appends the provided byte array to this byte string builder.
ByteStringBuilder	append(byte[] b, int offset, int length) Appends the provided byte array to this byte string builder.
ByteStringBuilder	append(java.nio.ByteBuffer buffer, int length) Appends the provided ByteBuffer to this byte string builder.
ByteStringBuilder	append(ByteSequence bytes) Appends the provided ByteSequence to this byte string builder.
ByteStringBuilder	append(ByteSequenceReader reader, int length) Appends the provided ByteSequenceReader to this byte string builder.
int	append(java.io.InputStream stream, int length) Appends the provided InputStream to this byte string builder.
ByteStringBuilder	append(int i) Appends the big-endian encoded bytes of the provided integer to this byte string builder.
ByteStringBuilder	append(long l) Appends the big-endian encoded bytes of the provided long to this byte string builder.
ByteStringBuilder	append(java.lang.Object o) Appends the provided object to this byte string builder.
ByteStringBuilder	append(short i) Appends the big-endian encoded bytes of the provided short to this byte string builder.
ByteStringBuilder	append(java.lang.String s) Appends the UTF-8 encoded bytes of the provided string to this byte string builder.
ByteStringBuilder	appendBERLength(int length) Appends the ASN.1 BER length encoding representation of the provided integer to this byte string builder.
ByteSequenceReader	asReader() Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte string builder.
byte	byteAt(int index) Returns the byte value at the specified index.
ByteStringBuilder	clear() Sets the length of this byte string builder to zero.
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.
ByteStringBuilder	ensureAdditionalCapacity(int size) Ensures that the specified number of additional bytes will fit in this byte string builder and resizes it if necessary.
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 builder.
byte[]	getBackingArray() Returns the byte array that backs this byte string builder.
int	hashCode() Returns a hash code for this byte string builder.
int	length() Returns the length of this byte sequence.
ByteStringBuilder	setLength(int newLength) Sets the length of this byte string builder.
ByteSequence	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 string builder.
java.lang.String	toString() Returns the UTF-8 decoded string representation of this byte sequence.
ByteStringBuilder	trimToSize() Attempts to reduce storage used for this byte string builder.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ByteStringBuilder

public ByteStringBuilder()

Creates a new byte string builder with an initial capacity of 32 bytes.

ByteStringBuilder

public ByteStringBuilder(int capacity)
                  throws java.lang.IllegalArgumentException

Creates a new byte string builder with the specified initial capacity.

Parameters:

capacity - The initial capacity.

Throws:

java.lang.IllegalArgumentException - If the capacity is negative.

Method Detail

append

public ByteStringBuilder append(byte b)

Appends the provided byte to this byte string builder.

Parameters:

b - The byte to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(byte[] b)

Appends the provided byte array to this byte string builder.

An invocation of the form:

 src.append(b)
 

Behaves in exactly the same way as the invocation:

 src.append(b, 0, b.length);
 

Parameters:

b - The byte array to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(byte[] b,
                                int offset,
                                int length)
                         throws java.lang.IndexOutOfBoundsException

Appends the provided byte array to this byte string builder.

Parameters:

b - The byte array to be appended to this byte string builder.

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:

This byte string builder.

Throws:

java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.length.

append

public ByteStringBuilder append(java.nio.ByteBuffer buffer,
                                int length)
                         throws java.lang.IndexOutOfBoundsException

Appends the provided ByteBuffer to this byte string builder.

Parameters:

buffer - The byte buffer to be appended to this byte string builder.

length - The number of bytes to be appended from buffer.

Returns:

This byte string builder.

Throws:

java.lang.IndexOutOfBoundsException - If length is less than zero or greater than buffer.remaining().

append

public ByteStringBuilder append(ByteSequence bytes)

Appends the provided ByteSequence to this byte string builder.

Parameters:

bytes - The byte sequence to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(ByteSequenceReader reader,
                                int length)
                         throws java.lang.IndexOutOfBoundsException

Appends the provided ByteSequenceReader to this byte string builder.

Parameters:

reader - The byte sequence reader to be appended to this byte string builder.

length - The number of bytes to be appended from reader.

Returns:

This byte string builder.

Throws:

java.lang.IndexOutOfBoundsException - If length is less than zero or greater than reader.remaining().

append

public int append(java.io.InputStream stream,
                  int length)
           throws java.lang.IndexOutOfBoundsException,
                  java.io.IOException

Appends the provided InputStream to this byte string builder.

Parameters:

stream - The input stream to be appended to this byte string builder.

length - The maximum number of bytes to be appended from buffer.

Returns:

The number of bytes read from the input stream, or -1 if the end of the input stream has been reached.

Throws:

java.lang.IndexOutOfBoundsException - If length is less than zero.

java.io.IOException - If an I/O error occurs.

append

public ByteStringBuilder append(int i)

Appends the big-endian encoded bytes of the provided integer to this byte string builder.

Parameters:

i - The integer whose big-endian encoding is to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(long l)

Appends the big-endian encoded bytes of the provided long to this byte string builder.

Parameters:

l - The long whose big-endian encoding is to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(java.lang.Object o)

Appends the provided object to this byte string builder. If the object is an instance of ByteSequence then its contents will be appended directly to this byte string builder using the append(ByteSequence) method. Otherwise the string representation of the object will be appended using the append(String) method.

Parameters:

o - The object to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(short i)

Appends the big-endian encoded bytes of the provided short to this byte string builder.

Parameters:

i - The short whose big-endian encoding is to be appended to this byte string builder.

Returns:

This byte string builder.

append

public ByteStringBuilder append(java.lang.String s)

Appends the UTF-8 encoded bytes of the provided string to this byte string builder.

Parameters:

s - The string whose UTF-8 encoding is to be appended to this byte string builder.

Returns:

This byte string builder.

appendBERLength

public ByteStringBuilder appendBERLength(int length)

Appends the ASN.1 BER length encoding representation of the provided integer to this byte string builder.

Parameters:

length - The value to encode using the BER length encoding rules.

Returns:

This byte string builder.

asReader

public ByteSequenceReader asReader()

Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte string builder.

NOTE: all concurrent updates to this byte string builder are supported with the exception of clear(). Any invocations of clear() must be accompanied by a subsequent call to ByteSequenceReader.rewind().

Specified by:

asReader in interface ByteSequence

Returns:

The ByteSequenceReader which can be used to incrementally read and decode data from this byte string builder.

See Also:

clear()

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().

clear

public ByteStringBuilder clear()

Sets the length of this byte string builder to zero.

NOTE: if this method is called, then ByteSequenceReader.rewind() must also be called on any associated byte sequence readers in order for them to remain valid.

Returns:

This byte string builder.

See Also:

asReader()

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.

ensureAdditionalCapacity

public ByteStringBuilder ensureAdditionalCapacity(int size)

Ensures that the specified number of additional bytes will fit in this byte string builder and resizes it if necessary.

Parameters:

size - The number of additional bytes.

Returns:

This byte string builder.

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 builder. 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 builder, or false if not.

getBackingArray

public byte[] getBackingArray()

Returns the byte array that backs this byte string builder. Modifications to this byte string builder's content may cause the returned array's content to be modified, and vice versa.

Note that the length of the returned array is only guaranteed to be the same as the length of this byte string builder immediately after a call to trimToSize().

In addition, subsequent modifications to this byte string builder may cause the backing byte array to be reallocated thus decoupling the returned byte array from this byte string builder.

Returns:

The byte array that backs this byte string builder.

hashCode

public int hashCode()

Returns a hash code for this byte string builder. It will be the sum of all of the bytes contained in the byte string builder.

NOTE: subsequent changes to this byte string builder will invalidate the returned hash code.

Specified by:

hashCode in interface ByteSequence

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code for this byte string builder.

length

public int length()

Returns the length of this byte sequence.

Specified by:

length in interface ByteSequence

Returns:

The length of this byte sequence.

setLength

public ByteStringBuilder setLength(int newLength)
                            throws java.lang.IndexOutOfBoundsException

Sets the length of this byte string builder.

If the newLength argument is less than the current length, the length is changed to the specified length.

If the newLength argument is greater than or equal to the current length, then the capacity is increased and sufficient null bytes are appended so that length becomes the newLength argument.

The newLength argument must be greater than or equal to 0.

Parameters:

newLength - The new length.

Returns:

This byte string builder.

Throws:

java.lang.IndexOutOfBoundsException - If the newLength argument is negative.

subSequence

public ByteSequence 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: the returned sub-sequence will be robust against all updates to the byte string builder except for invocations of the method clear(). If a permanent immutable byte sequence is required then callers should invoke toByteString() on the returned byte sequence.

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 string builder. Subsequent changes to this byte string builder will not modify the returned ByteString.

Specified by:

toByteString in interface ByteSequence

Returns:

The ByteString representation of this byte sequence.

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.

trimToSize

public ByteStringBuilder trimToSize()

Attempts to reduce storage used for this byte string builder. If the buffer is larger than necessary to hold its current sequence of bytes, then it may be resized to become more space efficient.

Returns:

This byte string builder.

Skip navigation links