Binary (MaritimeCloud API)

java.lang.Object
- net.maritimecloud.util.Binary

All Implemented Interfaces:

Comparable<Binary>, Iterable<Byte>
```
public abstract class Binary
extends Object
implements Iterable<Byte>, Comparable<Binary>
```
Immutable sequence of bytes. Substring is supported by sharing the reference to the immutable underlying bytes, as with 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.

Author:

crazybob@google.com Bob Lee, kenton@google.com Kenton Varda, carlanton@google.com Carl Haverl, martinrb@google.com Martin Buchholz, kasperni@gmail.com Kasper Nielsen

Nested Class Summary

Nested Classes
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.

Field Summary

Fields
Modifier and Type Field and Description

static Binary EMPTY
An empty Binary with size = 0.

Fields
Modifier and Type	Field and Description
`static Binary`	`EMPTY` An empty `Binary` with size = 0.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - EMPTY
```
public static final Binary EMPTY
```
    An empty Binary with size = 0.
- Method Detail
  - asReadOnlyByteBuffer
```
public abstract ByteBuffer asReadOnlyByteBuffer()
```
    Constructs a read-only 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.
    
    Returns:
    
    wrapped bytes
  - asReadOnlyByteBufferList
```
public 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. 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.
    
    Returns:
    
    a list of wrapped bytes
  - base64encode
```
public String base64encode()
```
  - hexString
```
public String hexString()
```
  - byteAt
```
public abstract byte byteAt(int index)
```
    Gets the byte at the given index. This method should be used only for random access to individual bytes. To access bytes sequentially, use the Binary.ByteIterator returned by iterator(), and call substring(int, int) first if necessary.
    
    Parameters:
    
    index - index of byte
    
    Returns:
    
    the value
    
    Throws:
    
    ArrayIndexOutOfBoundsException - index is less than 0 or greater than or equal to size
  - compareTo
```
public int compareTo(Binary o)
```
    Specified by:
    
    compareTo in interface Comparable<Binary>
  - concat
```
public Binary concat(Binary other)
```
    Concatenate the given 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.
    
    Parameters:
    
    other - string to concatenate
    
    Returns:
    
    a new Binary instance
  - copyTo
```
public void copyTo(byte[] target,
                   int offset)
```
    Copies bytes into a buffer at the given offset.
    
    Parameters:
    
    target - buffer to copy into
    
    offset - in the target buffer
    
    Throws:
    
    IndexOutOfBoundsException - if the offset is negative or too large
  - copyTo
```
public void copyTo(byte[] target,
                   int sourceOffset,
                   int targetOffset,
                   int numberToCopy)
```
    Copies bytes into a buffer.
    
    Parameters:
    
    target - buffer to copy into
    
    sourceOffset - offset within these bytes
    
    targetOffset - offset within the target buffer
    
    numberToCopy - number of bytes to copy
    
    Throws:
    
    IndexOutOfBoundsException - if an offset or size is negative or too large
  - copyTo
```
public abstract void copyTo(ByteBuffer target)
```
    Copies bytes into a ByteBuffer.
    
    Parameters:
    
    target - ByteBuffer to copy into.
    
    Throws:
    
    ReadOnlyBufferException - if the target is read-only
    
    BufferOverflowException - if the target's remaining() space is not large enough to hold the data.
  - copyToInternal
```
protected abstract void copyToInternal(byte[] target,
                                       int sourceOffset,
                                       int targetOffset,
                                       int numberToCopy)
```
    Internal (package private) implementation of copyTo(byte[], int, int, int). It assumes that all error checking has already been performed and that
    
    Parameters:
    
    target - sd
    
    sourceOffset - source
    
    targetOffset - target
    
    numberToCopy - numer
  - equals
```
public abstract boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - getTreeDepth
```
protected abstract int getTreeDepth()
```
    Return the depth of the tree representing this Binary, if any, whose root is this node. If this is a leaf node, return 0.
    
    Returns:
    
    tree depth or zero
  - hashCode
```
public abstract int hashCode()
```
    Return a non-zero hashCode depending only on the sequence of bytes in this Binary.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    hashCode value for this object
  - isBalanced
```
protected abstract boolean isBalanced()
```
    Return true if this Binary is literal (a leaf node) or a flat-enough tree in the sense of RopeBinary.
    
    Returns:
    
    true if the tree is flat enough
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if the size is 0, false otherwise.
    
    Returns:
    
    true if this is zero bytes long
  - isValidUtf8
```
public 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.
    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.
    Returns:
    
    whether the bytes in this Binary are a well-formed UTF-8 byte sequence
  - iterator
```
public abstract Binary.ByteIterator iterator()
```
    Return a Binary.ByteIterator over the bytes in the Binary. To avoid auto-boxing, you may get the iterator manually and call Binary.ByteIterator.nextByte().
    
    Specified by:
    
    iterator in interface Iterable<Byte>
    
    Returns:
    
    the iterator
  - newInput
```
public abstract InputStream newInput()
```
    Creates an 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.
    
    Returns:
    
    an input stream that returns the bytes of this byte string.
  - partialHash
```
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. This is used to compute the hash across strings represented as a set of pieces by allowing the hash computation to be continued from piece to piece.
    
    Parameters:
    
    h - starting hash value
    
    offset - offset into this value to start looking at data values
    
    length - number of data values to include in the hash computation
    
    Returns:
    
    ending hash value
  - partialIsValidUtf8
```
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. This method accepts and returns a partial state result, allowing the bytes for a complete UTF-8 byte sequence to be composed from multiple Binary segments.
    
    Parameters:
    
    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 bytes
    
    offset - offset of the first byte to check
    
    length - number of bytes to check
    
    Returns:
    
    -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.
  - peekCachedHashCode
```
protected abstract int peekCachedHashCode()
```
    Return the cached hash code if available.
    
    Returns:
    
    value of cached hash code or 0 if not computed yet
  - sha256
```
public final Binary sha256()
```
    Returns a SHA-256 hash of this binary.
    
    Returns:
    
    the hash
  - size
```
public abstract int size()
```
    Gets the number of bytes.
    
    Returns:
    
    size in bytes
  - startsWith
```
public boolean startsWith(Binary prefix)
```
    Tests if this bytestring starts with the specified prefix. Similar to String.startsWith(String)
    
    Parameters:
    
    prefix - the prefix.
    
    Returns:
    
    true if the byte sequence represented by the argument is a prefix of the byte sequence represented by this string; false otherwise.
  - substring
```
public Binary substring(int beginIndex)
```
    Return the substring from beginIndex, inclusive, to the end of the string.
    
    Parameters:
    
    beginIndex - start at this index
    
    Returns:
    
    substring sharing underlying data
    
    Throws:
    
    IndexOutOfBoundsException - if beginIndex < 0 or beginIndex > size().
  - substring
```
public abstract Binary substring(int beginIndex,
                                 int endIndex)
```
    Return the substring from beginIndex, inclusive, to endIndex, exclusive.
    
    Parameters:
    
    beginIndex - start at this index
    
    endIndex - the last character is the one before this index
    
    Returns:
    
    substring sharing underlying data
    
    Throws:
    
    IndexOutOfBoundsException - if beginIndex < 0, endIndex > size(), or beginIndex > endIndex.
  - toByteArray
```
public byte[] toByteArray()
```
    Copies bytes to a byte[].
    
    Returns:
    
    copied bytes
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toString
```
public abstract String toString(String charsetName)
                         throws UnsupportedEncodingException
```
    Constructs a new String by decoding the bytes using the specified charset.
    
    Parameters:
    
    charsetName - encode using this charset
    
    Returns:
    
    new string
    
    Throws:
    
    UnsupportedEncodingException - if charset isn't recognized
  - toStringUtf8
```
public String toStringUtf8()
```
    Constructs a new String by decoding the bytes as UTF-8.
    
    Returns:
    
    new string using UTF-8 encoding
  - writeTo
```
public abstract void writeTo(OutputStream out)
                      throws IOException
```
    Writes the complete contents of this byte string to the specified output stream argument.
    
    Parameters:
    
    out - the output stream to which to write the data.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - copyFrom
```
public static Binary copyFrom(byte... bytes)
```
    Copies the given bytes into a Binary.
    
    Parameters:
    
    bytes - to copy
    
    Returns:
    
    new Binary
  - copyFrom
```
public static Binary copyFrom(byte[] bytes,
                              int offset,
                              int size)
```
    Copies the given bytes into a Binary.
    
    Parameters:
    
    bytes - source array
    
    offset - offset in source array
    
    size - number of bytes to copy
    
    Returns:
    
    new Binary
  - copyFrom
```
public static Binary copyFrom(ByteBuffer bytes)
```
    Copies the remaining bytes from a java.nio.ByteBuffer into a Binary.
    
    Parameters:
    
    bytes - sourceBuffer
    
    Returns:
    
    new Binary
  - copyFrom
```
public static Binary copyFrom(ByteBuffer bytes,
                              int size)
```
    Copies the next size bytes from a java.nio.ByteBuffer into a Binary.
    
    Parameters:
    
    bytes - source buffer
    
    size - number of bytes to copy
    
    Returns:
    
    new Binary
  - copyFrom
```
public static Binary copyFrom(Iterable<Binary> byteStrings)
```
    Concatenates all byte strings in the iterable and returns the result. This is designed to run in O(list size), not O(total bytes).
    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.
    
    Parameters:
    
    byteStrings - strings to be concatenated
    
    Returns:
    
    new Binary
  - copyFrom
```
public static Binary copyFrom(String text,
                              String charsetName)
                       throws UnsupportedEncodingException
```
    Encodes text into a sequence of bytes using the named charset and returns the result as a Binary.
    
    Parameters:
    
    text - source string
    
    charsetName - encoding to use
    
    Returns:
    
    new Binary
    
    Throws:
    
    UnsupportedEncodingException - if the encoding isn't found
  - copyFromHex
```
public static Binary copyFromHex(String text)
```
  - copyFromBase64
```
public static Binary copyFromBase64(String text)
```
  - copyFromUtf8
```
public static Binary copyFromUtf8(String text)
```
    Encodes text into a sequence of UTF-8 bytes and returns the result as a Binary.
    
    Parameters:
    
    text - source string
    
    Returns:
    
    new Binary
  - newOutput
```
public static Binary.Output newOutput()
```
    Creates a new 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.
    
    Returns:
    
    OutputStream for building a Binary
  - newOutput
```
public static Binary.Output newOutput(int initialCapacity)
```
    Creates a new 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.
    
    Parameters:
    
    initialCapacity - estimate of number of bytes to be written
    
    Returns:
    
    OutputStream for building a Binary
  - random
```
public static Binary random(int bytes)
```
  - readFrom
```
public static Binary readFrom(InputStream streamToDrain)
                       throws IOException
```
    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. 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.
    
    Parameters:
    
    streamToDrain - The source stream, which is read completely but not closed.
    
    Returns:
    
    A new Binary which is made up of chunks of various sizes, depending on the behavior of the underlying stream.
    
    Throws:
    
    IOException - IOException is thrown if there is a problem reading the underlying stream.
  - readFrom
```
public static Binary readFrom(InputStream streamToDrain,
                              int chunkSize)
                       throws IOException
```
    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. 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.
    
    Parameters:
    
    streamToDrain - The source stream, which is read completely but not closed.
    
    chunkSize - The size of the chunks in which to read the stream.
    
    Returns:
    
    A new Binary which is made up of chunks of the given size.
    
    Throws:
    
    IOException - IOException is thrown if there is a problem reading the underlying stream.
  - readFrom
```
public static Binary readFrom(InputStream streamToDrain,
                              int minChunkSize,
                              int maxChunkSize)
                       throws IOException
```
    Throws:
    
    IOException

Class Binary

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

EMPTY

Method Detail

asReadOnlyByteBuffer

asReadOnlyByteBufferList

base64encode

hexString

byteAt

compareTo

concat

copyTo

copyTo

copyTo

copyToInternal

equals

getTreeDepth

hashCode

isBalanced

isEmpty

isValidUtf8

iterator

newInput

partialHash

partialIsValidUtf8

peekCachedHashCode

sha256

size

startsWith

substring

substring

toByteArray

toString

toString

toStringUtf8

writeTo

copyFrom

copyFrom

copyFrom

copyFrom

copyFrom

copyFrom

copyFromHex

copyFromBase64

copyFromUtf8

newOutput

newOutput

random

readFrom

readFrom

readFrom