public abstract class Binary extends Object implements Iterable<Byte>, Comparable<Binary>
String (previous to Java 7). Concatenation is likewise supported without copying (long strings) by
building a tree of pieces in RopeBinary.
Like String, the contents of a Binary can never be observed to change, not even in the presence of a
data race or incorrect API usage in the client code.
| Modifier and Type | Class and Description |
|---|---|
static interface |
Binary.ByteIterator
This interface extends
Iterator<Byte>, so that we can return an unboxed byte. |
static class |
Binary.Output
Outputs to a
Binary instance. |
| Modifier and Type | Field and Description |
|---|---|
static Binary |
EMPTY
An empty
Binary with size = 0. |
| Modifier and Type | Method and Description |
|---|---|
abstract ByteBuffer |
asReadOnlyByteBuffer()
Constructs a read-only
java.nio.ByteBuffer whose content is equal to the contents of this byte string. |
abstract List<ByteBuffer> |
asReadOnlyByteBufferList()
Constructs a list of read-only
java.nio.ByteBuffer objects such that the concatenation of their contents
is equal to the contents of this byte string. |
String |
base64encode() |
abstract byte |
byteAt(int index)
Gets the byte at the given index.
|
int |
compareTo(Binary o) |
Binary |
concat(Binary other)
Concatenate the given
Binary to this one. |
static Binary |
copyFrom(byte... bytes)
Copies the given bytes into a
Binary. |
static Binary |
copyFrom(byte[] bytes,
int offset,
int size)
Copies the given bytes into a
Binary. |
static Binary |
copyFrom(ByteBuffer bytes)
Copies the remaining bytes from a
java.nio.ByteBuffer into a Binary. |
static Binary |
copyFrom(ByteBuffer bytes,
int size)
Copies the next
size bytes from a java.nio.ByteBuffer into a Binary. |
static Binary |
copyFrom(Iterable<Binary> byteStrings)
Concatenates all byte strings in the iterable and returns the result.
|
static Binary |
copyFrom(String text,
String charsetName)
Encodes
text into a sequence of bytes using the named charset and returns the result as a Binary. |
static Binary |
copyFromBase64(String text) |
static Binary |
copyFromHex(String text) |
static Binary |
copyFromUtf8(String text)
Encodes
text into a sequence of UTF-8 bytes and returns the result as a Binary. |
void |
copyTo(byte[] target,
int offset)
Copies bytes into a buffer at the given offset.
|
void |
copyTo(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
Copies bytes into a buffer.
|
abstract void |
copyTo(ByteBuffer target)
Copies bytes into a ByteBuffer.
|
protected abstract void |
copyToInternal(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
Internal (package private) implementation of
copyTo(byte[], int, int, int). |
abstract boolean |
equals(Object o) |
protected abstract int |
getTreeDepth()
Return the depth of the tree representing this
Binary, if any, whose root is this node. |
abstract int |
hashCode()
Return a non-zero hashCode depending only on the sequence of bytes in this Binary.
|
String |
hexString() |
protected abstract boolean |
isBalanced()
Return
true if this Binary is literal (a leaf node) or a flat-enough tree in the sense of
RopeBinary. |
boolean |
isEmpty()
Returns
true if the size is 0, false otherwise. |
abstract boolean |
isValidUtf8()
Tells whether this
Binary represents a well-formed UTF-8 byte sequence, such that the original bytes can
be converted to a String object and then round tripped back to bytes without loss. |
abstract Binary.ByteIterator |
iterator()
Return a
Binary.ByteIterator over the bytes in the Binary. |
abstract InputStream |
newInput()
Creates an
InputStream which can be used to read the bytes. |
static Binary.Output |
newOutput()
Creates a new
Binary.Output. |
static Binary.Output |
newOutput(int initialCapacity)
Creates a new
Binary.Output with the given initial capacity. |
protected abstract int |
partialHash(int h,
int offset,
int length)
Compute the hash across the value bytes starting with the given hash, and return the result.
|
protected abstract int |
partialIsValidUtf8(int state,
int offset,
int length)
Tells whether the given byte sequence is a well-formed, malformed, or incomplete UTF-8 byte sequence.
|
protected abstract int |
peekCachedHashCode()
Return the cached hash code if available.
|
static Binary |
random(int bytes) |
static Binary |
readFrom(InputStream streamToDrain)
Completely reads the given stream's bytes into a
Binary, blocking if necessary until all bytes are read
through to the end of the stream. |
static Binary |
readFrom(InputStream streamToDrain,
int chunkSize)
Completely reads the given stream's bytes into a
Binary, blocking if necessary until all bytes are read
through to the end of the stream. |
static Binary |
readFrom(InputStream streamToDrain,
int minChunkSize,
int maxChunkSize) |
Binary |
sha256()
Returns a SHA-256 hash of this binary.
|
abstract int |
size()
Gets the number of bytes.
|
boolean |
startsWith(Binary prefix)
Tests if this bytestring starts with the specified prefix.
|
Binary |
substring(int beginIndex)
Return the substring from
beginIndex, inclusive, to the end of the string. |
abstract Binary |
substring(int beginIndex,
int endIndex)
Return the substring from
beginIndex, inclusive, to endIndex, exclusive. |
byte[] |
toByteArray()
Copies bytes to a
byte[]. |
String |
toString() |
abstract String |
toString(String charsetName)
Constructs a new
String by decoding the bytes using the specified charset. |
String |
toStringUtf8()
Constructs a new
String by decoding the bytes as UTF-8. |
abstract void |
writeTo(OutputStream out)
Writes the complete contents of this byte string to the specified output stream argument.
|
clone, finalize, getClass, notify, notifyAll, wait, wait, waitforEach, spliteratorpublic static final Binary EMPTY
Binary with size = 0.public abstract ByteBuffer asReadOnlyByteBuffer()
java.nio.ByteBuffer whose content is equal to the contents of this byte string.
The result uses the same backing array as the byte string, if possible.public abstract List<ByteBuffer> asReadOnlyByteBufferList()
java.nio.ByteBuffer objects such that the concatenation of their contents
is equal to the contents of this byte string. The result uses the same backing arrays as the byte string.
By returning a list, implementations of this method may be able to avoid copying even when there are multiple backing arrays.
public String base64encode()
public String hexString()
public abstract byte byteAt(int index)
Binary.ByteIterator returned by iterator(), and call
substring(int, int) first if necessary.index - index of byteArrayIndexOutOfBoundsException - index is less than 0 or greater than or equal to sizepublic int compareTo(Binary o)
compareTo in interface Comparable<Binary>public Binary concat(Binary other)
Binary to this one. Short concatenations, of total size smaller than
CONCATENATE_BY_COPY_SIZE, are produced by copying the underlying bytes (as per Rope.java, BAP95 . In
general, the concatenate involves no copying.other - string to concatenateBinary instancepublic void copyTo(byte[] target,
int offset)
target - buffer to copy intooffset - in the target bufferIndexOutOfBoundsException - if the offset is negative or too largepublic void copyTo(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
target - buffer to copy intosourceOffset - offset within these bytestargetOffset - offset within the target buffernumberToCopy - number of bytes to copyIndexOutOfBoundsException - if an offset or size is negative or too largepublic abstract void copyTo(ByteBuffer target)
target - ByteBuffer to copy into.ReadOnlyBufferException - if the target is read-onlyBufferOverflowException - if the target's remaining() space is not large enough to hold the data.protected abstract void copyToInternal(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
copyTo(byte[], int, int, int). It assumes that all error
checking has already been performed and thattarget - sdsourceOffset - sourcetargetOffset - targetnumberToCopy - numerprotected abstract int getTreeDepth()
Binary, if any, whose root is this node. If this is a leaf
node, return 0.public abstract int hashCode()
protected abstract boolean isBalanced()
true if this Binary is literal (a leaf node) or a flat-enough tree in the sense of
RopeBinary.public boolean isEmpty()
true if the size is 0, false otherwise.public abstract boolean isValidUtf8()
Binary represents a well-formed UTF-8 byte sequence, such that the original bytes can
be converted to a String object and then round tripped back to bytes without loss.
More precisely, returns true whenever:
Arrays.equals(byteString.toByteArray(),
new String(byteString.toByteArray(), "UTF-8").getBytes("UTF-8"))
This method returns false for "overlong" byte sequences, as well as for 3-byte sequences that would map
to a surrogate character, in accordance with the restricted definition of UTF-8 introduced in Unicode 3.1. Note
that the UTF-8 decoder included in Oracle's JDK has been modified to also reject "overlong" byte sequences, but
(as of 2011) still accepts 3-byte surrogate character byte sequences.
See the Unicode Standard, Table 3-6. UTF-8 Bit Distribution, Table 3-7. Well Formed UTF-8 Byte Sequences.
Binary are a well-formed UTF-8 byte sequencepublic abstract Binary.ByteIterator iterator()
Binary.ByteIterator over the bytes in the Binary. To avoid auto-boxing, you may get the iterator
manually and call Binary.ByteIterator.nextByte().public abstract InputStream newInput()
InputStream which can be used to read the bytes.
The InputStream returned by this method is guaranteed to be completely non-blocking. The method
InputStream.available() returns the number of bytes remaining in the stream. The methods
InputStream.read(byte[]), InputStream.read(byte[],int,int) and InputStream.skip(long)
will read/skip as many bytes as are available.
The methods in the returned InputStream might not be thread safe.
protected abstract int partialHash(int h,
int offset,
int length)
h - starting hash valueoffset - offset into this value to start looking at data valueslength - number of data values to include in the hash computationprotected abstract int partialIsValidUtf8(int state,
int offset,
int length)
Binary segments.state - either 0 (if this is the initial decoding operation) or the value returned from a call to a
partial decoding method for the previous bytesoffset - offset of the first byte to checklength - number of bytes to check-1 if the partial byte sequence is definitely malformed, 0 if it is well-formed (no
additional input needed), or, if the byte sequence is "incomplete", i.e. apparently terminated in the
middle of a character, an opaque integer "state" value containing enough information to decode the
character when passed to a subsequent invocation of a partial decoding method.protected abstract int peekCachedHashCode()
public final Binary sha256()
public abstract int size()
public boolean startsWith(Binary prefix)
String.startsWith(String)prefix - the prefix.true if the byte sequence represented by the argument is a prefix of the byte sequence
represented by this string; false otherwise.public Binary substring(int beginIndex)
beginIndex, inclusive, to the end of the string.beginIndex - start at this indexIndexOutOfBoundsException - if beginIndex < 0 or beginIndex > size().public abstract Binary substring(int beginIndex, int endIndex)
beginIndex, inclusive, to endIndex, exclusive.beginIndex - start at this indexendIndex - the last character is the one before this indexIndexOutOfBoundsException - if beginIndex < 0, endIndex > size(), or beginIndex > endIndex.public byte[] toByteArray()
byte[].public abstract String toString(String charsetName) throws UnsupportedEncodingException
String by decoding the bytes using the specified charset.charsetName - encode using this charsetUnsupportedEncodingException - if charset isn't recognizedpublic String toStringUtf8()
String by decoding the bytes as UTF-8.public abstract void writeTo(OutputStream out) throws IOException
out - the output stream to which to write the data.IOException - if an I/O error occurs.public static Binary copyFrom(byte... bytes)
Binary.bytes - to copyBinarypublic static Binary copyFrom(byte[] bytes, int offset, int size)
Binary.bytes - source arrayoffset - offset in source arraysize - number of bytes to copyBinarypublic static Binary copyFrom(ByteBuffer bytes)
java.nio.ByteBuffer into a Binary.bytes - sourceBufferBinarypublic static Binary copyFrom(ByteBuffer bytes, int size)
size bytes from a java.nio.ByteBuffer into a Binary.bytes - source buffersize - number of bytes to copyBinarypublic static Binary copyFrom(Iterable<Binary> byteStrings)
The returned Binary is not necessarily a unique object. If the list is empty, the returned object is the
singleton empty Binary. If the list has only one element, that Binary will be returned without
copying.
byteStrings - strings to be concatenatedBinarypublic static Binary copyFrom(String text, String charsetName) throws UnsupportedEncodingException
text into a sequence of bytes using the named charset and returns the result as a Binary.text - source stringcharsetName - encoding to useBinaryUnsupportedEncodingException - if the encoding isn't foundpublic static Binary copyFromUtf8(String text)
text into a sequence of UTF-8 bytes and returns the result as a Binary.text - source stringBinarypublic static Binary.Output newOutput()
Binary.Output. Call Binary.Output.toBinary() to create the Binary instance.
A Binary.Output offers the same functionality as a ByteArrayOutputStream, except that it returns
a Binary rather than a byte array.
OutputStream for building a Binarypublic static Binary.Output newOutput(int initialCapacity)
Binary.Output with the given initial capacity. Call Binary.Output.toBinary() to create the
Binary instance.
A Binary.Output offers the same functionality as a ByteArrayOutputStream, except that it returns
a Binary rather than a byte array.
initialCapacity - estimate of number of bytes to be writtenOutputStream for building a Binarypublic static Binary random(int bytes)
public static Binary readFrom(InputStream streamToDrain) throws IOException
Binary, blocking if necessary until all bytes are read
through to the end of the stream.
Performance notes: The returned Binary is an immutable tree of byte arrays ("chunks") of the
stream data. The first chunk is small, with subsequent chunks each being double the size, up to 8K. If the caller
knows the precise length of the stream and wishes to avoid all unnecessary copies and allocations, consider using
the two-argument version of this method, below.streamToDrain - The source stream, which is read completely but not closed.Binary which is made up of chunks of various sizes, depending on the behavior of the
underlying stream.IOException - IOException is thrown if there is a problem reading the underlying stream.public static Binary readFrom(InputStream streamToDrain, int chunkSize) throws IOException
Binary, blocking if necessary until all bytes are read
through to the end of the stream.
Performance notes: The returned Binary is an immutable tree of byte arrays ("chunks") of the
stream data. The chunkSize parameter sets the size of these byte arrays. In particular, if the chunkSize is
precisely the same as the length of the stream, unnecessary allocations and copies will be avoided. Otherwise,
the chunks will be of the given size, except for the last chunk, which will be resized (via a reallocation and
copy) to contain the remainder of the stream.streamToDrain - The source stream, which is read completely but not closed.chunkSize - The size of the chunks in which to read the stream.Binary which is made up of chunks of the given size.IOException - IOException is thrown if there is a problem reading the underlying stream.public static Binary readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws IOException
IOExceptionCopyright © 2012–2015 Danish Maritime Authority. All rights reserved.