public final class ByteStringBuilder extends Object implements ByteSequence
Modifier and Type | Field and Description |
---|---|
static int |
MAX_COMPACT_SIZE
Maximum size in bytes of a compact encoded value.
|
BYTE_ARRAY_COMPARATOR, COMPARATOR
Constructor and Description |
---|
ByteStringBuilder()
Creates a new byte string builder with an initial capacity of 32 bytes.
|
ByteStringBuilder(ByteSequence bs)
Creates a new byte string builder with the content of the provided
ByteSequence.
|
ByteStringBuilder(int capacity)
Creates a new byte string builder with the specified initial capacity.
|
Modifier and Type | Method and Description |
---|---|
ByteStringBuilder |
appendBerLength(int length)
Appends the ASN.1 BER length encoding representation of the provided
integer to this byte string builder.
|
ByteStringBuilder |
appendByte(int b)
Appends the provided byte to this byte string builder.
|
ByteStringBuilder |
appendBytes(byte[] bytes)
Appends the provided byte array to this byte string builder.
|
ByteStringBuilder |
appendBytes(byte[] bytes,
int offset,
int length)
Appends the provided byte array to this byte string builder.
|
ByteStringBuilder |
appendBytes(ByteBuffer buffer,
int length)
Appends the provided
ByteBuffer to this byte string builder. |
ByteStringBuilder |
appendBytes(ByteSequence bytes)
Appends the provided
ByteSequence to this byte string builder. |
ByteStringBuilder |
appendBytes(ByteSequenceReader reader,
int length)
Appends the provided
ByteSequenceReader to this byte string builder. |
void |
appendBytes(DataInput stream,
int length)
Appends the provided
DataInput to this byte string
builder. |
int |
appendBytes(InputStream stream,
int length)
Appends the provided
InputStream to this byte string builder. |
ByteStringBuilder |
appendCompactUnsigned(long value)
Appends the compact encoded bytes of the provided unsigned long to this byte
string builder.
|
ByteStringBuilder |
appendInt(int i)
Appends the big-endian encoded bytes of the provided integer to this byte
string builder.
|
ByteStringBuilder |
appendLong(long l)
Appends the big-endian encoded bytes of the provided long to this byte
string builder.
|
ByteStringBuilder |
appendObject(Object o)
Appends the byte string representation of the provided object to this
byte string builder.
|
ByteStringBuilder |
appendShort(int i)
Appends the big-endian encoded bytes of the provided short to this byte
string builder.
|
ByteStringBuilder |
appendUtf8(char[] chars)
Appends the UTF-8 encoded bytes of the provided char array to this byte
string builder.
|
ByteStringBuilder |
appendUtf8(String s)
Appends the UTF-8 encoded bytes of the provided string to this byte
string builder.
|
OutputStream |
asOutputStream()
Returns an
OutputStream whose write operations append data 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.
|
int |
capacity()
Returns the current capacity of this byte string builder.
|
ByteStringBuilder |
clear()
Sets the length of this byte string builder to zero.
|
ByteStringBuilder |
clearAndTruncate(int thresholdCapacity,
int newCapacity)
Sets the length of this byte string builder to zero, and resets the
capacity to the specified size if above provided threshold.
|
int |
compareTo(byte[] bytes,
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[] bytes)
Copies the contents of this byte sequence to the provided byte array.
|
byte[] |
copyTo(byte[] bytes,
int offset)
Copies the contents of this byte sequence to the specified location in
the provided byte array.
|
ByteBuffer |
copyTo(ByteBuffer byteBuffer)
Appends the content of this byte sequence to the provided
ByteBuffer starting at it's current position. |
ByteStringBuilder |
copyTo(ByteStringBuilder builder)
Appends the entire contents of this byte sequence to the provided
ByteStringBuilder . |
boolean |
copyTo(CharBuffer charBuffer,
CharsetDecoder decoder)
Appends the content of this byte sequence decoded using provided charset decoder to the provided
CharBuffer starting at it's current position. |
OutputStream |
copyTo(OutputStream stream)
Copies the entire contents of this byte sequence to the provided
OutputStream . |
int |
copyTo(WritableByteChannel channel)
Copies the entire contents of this byte string to the provided
WritableByteChannel . |
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[] bytes,
int offset,
int length)
Indicates whether the provided byte array sub-sequence is equal to this
byte sequence.
|
boolean |
equals(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.
|
boolean |
isEmpty()
Returns
true if this byte sequence has a length of zero. |
int |
length()
Returns the length of this byte sequence.
|
void |
setByte(int index,
byte b)
Sets the byte value at the specified index.
|
ByteStringBuilder |
setLength(int newLength)
Sets the length of this byte string builder.
|
boolean |
startsWith(ByteSequence prefix)
Tests if this ByteSequence starts with the specified prefix.
|
ByteSequence |
subSequence(int start,
int end)
Returns a new byte sequence that is a subsequence of this byte sequence.
|
String |
toBase64String()
Returns the Base64 encoded string representation of this byte string.
|
byte[] |
toByteArray()
Returns a byte array containing the bytes in this sequence in the same
order as this sequence.
|
ByteBuffer |
toByteBuffer()
Returns the read-only
ByteBuffer representation of this byte string builder. |
ByteString |
toByteString()
Returns the
ByteString representation of this byte string
builder. |
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.
|
public static final int MAX_COMPACT_SIZE
public ByteStringBuilder()
public ByteStringBuilder(int capacity)
capacity
- The initial capacity.IllegalArgumentException
- If the capacity
is negative.public ByteStringBuilder(ByteSequence bs)
bs
- The ByteSequence to copypublic ByteStringBuilder appendByte(int b)
Note: this method accepts an int
for ease of reading and writing.
This method only keeps the lowest 8-bits of the provided int
.
Higher bits will be truncated. This method performs the equivalent of:
int i = ...;
int i8bits = i & 0xFF;
// only use "i8bits"
OR
int i = ...;
byte b = (byte) i;
// only use "b"
b
- The byte to be appended to this byte string builder.public ByteStringBuilder appendBytes(byte[] bytes)
An invocation of the form:
src.append(bytes)Behaves in exactly the same way as the invocation:
src.append(bytes, 0, bytes.length);
bytes
- The byte array to be appended to this byte string builder.public ByteStringBuilder appendBytes(byte[] bytes, int offset, int length)
bytes
- 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 bytes.length
.length
- The length of the byte array to be used; must be non-negative
and no larger than bytes.length - offset
.IndexOutOfBoundsException
- If offset
is negative or if length
is
negative or if offset + length
is greater than
bytes.length
.public ByteStringBuilder appendBytes(ByteBuffer buffer, int length)
ByteBuffer
to this byte string builder.buffer
- The byte buffer to be appended to this byte string builder.length
- The number of bytes to be appended from buffer
.IndexOutOfBoundsException
- If length
is less than zero or greater than
buffer.remaining()
.public ByteStringBuilder appendBytes(ByteSequence bytes)
ByteSequence
to this byte string builder.bytes
- The byte sequence to be appended to this byte string builder.public ByteStringBuilder appendBytes(ByteSequenceReader reader, int length)
ByteSequenceReader
to this byte string builder.reader
- The byte sequence reader to be appended to this byte string
builder.length
- The number of bytes to be appended from reader
.IndexOutOfBoundsException
- If length
is less than zero or greater than
reader.remaining()
.public ByteStringBuilder appendUtf8(char[] chars)
chars
- The char array whose UTF-8 encoding is to be appended to this
byte string builder.public void appendBytes(DataInput stream, int length) throws EOFException, IOException
DataInput
to this byte string
builder.stream
- The data input stream to be appended to this byte string
builder.length
- The maximum number of bytes to be appended from input
.IndexOutOfBoundsException
- If length
is less than zero.EOFException
- If this stream reaches the end before reading all the bytes.IOException
- If an I/O error occurs.public int appendBytes(InputStream stream, int length) throws IOException
InputStream
to this byte string builder.stream
- The input stream to be appended to this byte string builder.length
- The maximum number of bytes to be appended from buffer
.-1
if
the end of the input stream has been reached.IndexOutOfBoundsException
- If length
is less than zero.IOException
- If an I/O error occurs.public ByteStringBuilder appendInt(int i)
i
- The integer whose big-endian encoding is to be appended to
this byte string builder.public ByteStringBuilder appendLong(long l)
l
- The long whose big-endian encoding is to be appended to this
byte string builder.public ByteStringBuilder appendCompactUnsigned(long value)
value
- The long whose compact encoding is to be appended to this
byte string builder.public ByteStringBuilder appendObject(Object o)
ByteSequence
then this method
is equivalent to calling appendBytes(ByteSequence)
byte[]
then this method is equivalent to
calling appendBytes(byte[])
char[]
then this method is equivalent to
calling appendUtf8(char[])
appendUtf8(String)
with the toString()
representation of the
provided object.
Long
and Integer
objects
like any other type of Object
. More specifically, the following
invocations are not equivalent:
append(0)
is not equivalent to append((Object) 0)
append(0L)
is not equivalent to append((Object) 0L)
o
- The object to be appended to this byte string builder.public ByteStringBuilder appendShort(int i)
Note: this method accepts an int
for ease of reading and writing.
This method only keeps the lowest 16-bits of the provided int
.
Higher bits will be truncated. This method performs the equivalent of:
int i = ...;
int i16bits = i & 0xFFFF;
// only use "i16bits"
OR
int i = ...;
short s = (short) i;
// only use "s"
i
- The short whose big-endian encoding is to be appended to this
byte string builder.public ByteStringBuilder appendUtf8(String s)
s
- The string whose UTF-8 encoding is to be appended to this byte
string builder.public ByteStringBuilder appendBerLength(int length)
length
- The value to encode using the BER length encoding rules.public OutputStream asOutputStream()
OutputStream
whose write operations append data to
this byte string builder. The returned output stream will never throw an
IOException
and its close
method
does not do anything.OutputStream
whose write operations append data to
this byte string builder.public ByteSequenceReader asReader()
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()
.
asReader
in interface ByteSequence
ByteSequenceReader
which can be used to incrementally
read and decode data from this byte string builder.clear()
public byte byteAt(int index)
ByteSequence
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.
byteAt
in interface ByteSequence
index
- The index of the byte to be returned.public int capacity()
public ByteStringBuilder clear()
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.
asReader()
public ByteStringBuilder clearAndTruncate(int thresholdCapacity, int newCapacity)
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.
thresholdCapacity
- The threshold capacity triggering a truncatenewCapacity
- The new capacity.IllegalArgumentException
- If the newCapacity
is negative or the newCapacity
is bigger than the thresholdCapacity
.asReader()
public int compareTo(byte[] bytes, int offset, int length)
ByteSequence
compareTo
in interface ByteSequence
bytes
- 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
bytes.length
.length
- The length of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length - offset
.public int compareTo(ByteSequence o)
ByteSequence
compareTo
in interface Comparable<ByteSequence>
compareTo
in interface ByteSequence
o
- The byte sequence to be compared.public byte[] copyTo(byte[] bytes)
ByteSequence
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(bytes)Behaves in exactly the same way as the invocation:
src.copyTo(bytes, 0);
copyTo
in interface ByteSequence
bytes
- The byte array to which bytes are to be copied.public byte[] copyTo(byte[] bytes, int offset)
ByteSequence
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(bytes, offset)Behaves in exactly the same way as the invocation:
int len = Math.min(src.length(), bytes.length - offset); for (int i = 0; i < len; i++) bytes[offset + i] = src.get(i);Except that it is potentially much more efficient.
copyTo
in interface ByteSequence
bytes
- 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 bytes.length.public ByteBuffer copyTo(ByteBuffer byteBuffer)
ByteSequence
ByteBuffer
starting at it's current position.
The position of the buffer is then incremented by the length of this sequence.copyTo
in interface ByteSequence
byteBuffer
- The buffer to copy to.
It must be large enough to receive all bytes.public ByteStringBuilder copyTo(ByteStringBuilder builder)
ByteSequence
ByteStringBuilder
.copyTo
in interface ByteSequence
builder
- The builder to copy to.public boolean copyTo(CharBuffer charBuffer, CharsetDecoder decoder)
ByteSequence
CharBuffer
starting at it's current position. The position of charBuffer is then incremented by the
length of this sequence.copyTo
in interface ByteSequence
charBuffer
- The buffer to copy to, if decoding is successful.
It must be large enough to receive all decoded characters.decoder
- The charset decoder to use for decoding.true
if byte string was successfully decoded and charBuffer is
large enough to receive the resulting string, false
otherwisepublic OutputStream copyTo(OutputStream stream) throws IOException
ByteSequence
OutputStream
.copyTo
in interface ByteSequence
stream
- The OutputStream
to copy to.OutputStream
.IOException
- If an error occurs while writing to the OutputStream
.public int copyTo(WritableByteChannel channel) throws IOException
WritableByteChannel
.channel
- The WritableByteChannel
to copy to.IOException
- If some other I/O error occursWritableByteChannel.write(java.nio.ByteBuffer)
public ByteStringBuilder ensureAdditionalCapacity(int size)
size
- The number of additional bytes.public boolean equals(byte[] bytes, int offset, int length)
ByteSequence
equals
in interface ByteSequence
bytes
- 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
bytes.length
.length
- The length of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length - offset
.true
if the content of the provided byte array
sub-sequence is equal to that of this byte sequence, or
false
if not.public boolean equals(Object o)
equals
in interface ByteSequence
equals
in class Object
o
- The object for which to make the determination.true
if the provided object is a byte sequence whose
content is equal to that of this byte string builder, or
false
if not.public byte[] getBackingArray()
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.
public int hashCode()
NOTE: subsequent changes to this byte string builder will invalidate the returned hash code.
hashCode
in interface ByteSequence
hashCode
in class Object
public boolean isEmpty()
ByteSequence
true
if this byte sequence has a length of zero.isEmpty
in interface ByteSequence
true
if this byte sequence has a length of zero.public int length()
ByteSequence
length
in interface ByteSequence
public void setByte(int index, byte b)
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.
index
- The index of the byte to be set.b
- The byte to set on this byte string builder.IndexOutOfBoundsException
- If the index argument is negative or not less than length().public ByteStringBuilder setLength(int newLength)
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
.
newLength
- The new length.IndexOutOfBoundsException
- If the newLength
argument is negative.public ByteSequence subSequence(int start, int end)
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.
subSequence
in interface ByteSequence
start
- The start index, inclusive.end
- The end index, exclusive.public boolean startsWith(ByteSequence prefix)
ByteSequence
startsWith
in interface ByteSequence
prefix
- The prefix.public String toBase64String()
ByteSequence
toBase64String
in interface ByteSequence
ByteString.valueOfBase64(String)
public byte[] toByteArray()
ByteSequence
An invocation of the form:
src.toByteArray()Behaves in exactly the same way as the invocation:
src.copyTo(new byte[src.length()]);
toByteArray
in interface ByteSequence
public ByteString toByteString()
ByteString
representation of this byte string
builder. Subsequent changes to this byte string builder will not modify
the returned ByteString
.toByteString
in interface ByteSequence
ByteString
representation of this byte sequence.public ByteBuffer toByteBuffer()
ByteBuffer
representation of this byte string builder.
Because the ByteBuffer
will share the same underlying byte array,
subsequent changes to this byte string builder will modify the returned
ByteBuffer
.toByteBuffer
in interface ByteSequence
ByteBuffer
representation of this byte sequence.public String toString()
ByteSequence
toString
in interface ByteSequence
toString
in class Object
public ByteStringBuilder trimToSize()
Copyright 2010-2022 ForgeRock AS.