Class ByteString
- java.lang.Object
-
- akka.protobuf.ByteString
-
- All Implemented Interfaces:
java.lang.Iterable<java.lang.Byte>
public abstract class ByteString extends java.lang.Object implements java.lang.Iterable<java.lang.Byte>
Immutable sequence of bytes. Substring is supported by sharing the reference to the immutable underlying bytes, as withString
. Concatenation is likewise supported without copying (long strings) by building a tree of pieces inRopeByteString
.Like
String
, the contents of aByteString
can never be observed to change, not even in the presence of a data race or incorrect API usage in the client code.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
ByteString.ByteIterator
This interface extendsIterator<Byte>
, so that we can return an unboxedbyte
.static class
ByteString.Output
Outputs to aByteString
instance.
-
Field Summary
Fields Modifier and Type Field Description static ByteString
EMPTY
EmptyByteString
.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract java.nio.ByteBuffer
asReadOnlyByteBuffer()
Constructs a read-onlyjava.nio.ByteBuffer
whose content is equal to the contents of this byte string.abstract java.util.List<java.nio.ByteBuffer>
asReadOnlyByteBufferList()
Constructs a list of read-onlyjava.nio.ByteBuffer
objects such that the concatenation of their contents is equal to the contents of this byte string.abstract byte
byteAt(int index)
Gets the byte at the given index.ByteString
concat(ByteString other)
Concatenate the givenByteString
to this one.static ByteString
copyFrom(byte[] bytes)
Copies the given bytes into aByteString
.static ByteString
copyFrom(byte[] bytes, int offset, int size)
Copies the given bytes into aByteString
.static ByteString
copyFrom(java.lang.Iterable<ByteString> byteStrings)
Concatenates all byte strings in the iterable and returns the result.static ByteString
copyFrom(java.lang.String text, java.lang.String charsetName)
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.static ByteString
copyFrom(java.nio.ByteBuffer bytes)
Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFrom(java.nio.ByteBuffer bytes, int size)
Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFromUtf8(java.lang.String text)
Encodestext
into a sequence of UTF-8 bytes and returns the result as aByteString
.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(java.nio.ByteBuffer target)
Copies bytes into a ByteBuffer.protected abstract void
copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)
Internal (package private) implementation ofcopyTo
.abstract boolean
equals(java.lang.Object o)
protected abstract int
getTreeDepth()
Return the depth of the tree representing thisByteString
, if any, whose root is this node.abstract int
hashCode()
Return a non-zero hashCode depending only on the sequence of bytes in this ByteString.protected abstract boolean
isBalanced()
Returntrue
if this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString
.boolean
isEmpty()
Returnstrue
if the size is0
,false
otherwise.abstract boolean
isValidUtf8()
Tells whether thisByteString
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 ByteString.ByteIterator
iterator()
Return aByteString.ByteIterator
over the bytes in the ByteString.abstract CodedInputStream
newCodedInput()
Creates aCodedInputStream
which can be used to read the bytes.abstract java.io.InputStream
newInput()
Creates anInputStream
which can be used to read the bytes.static ByteString.Output
newOutput()
Creates a newByteString.Output
.static ByteString.Output
newOutput(int initialCapacity)
Creates a newByteString.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 ByteString
readFrom(java.io.InputStream streamToDrain)
Completely reads the given stream's bytes into aByteString
, blocking if necessary until all bytes are read through to the end of the stream.static ByteString
readFrom(java.io.InputStream streamToDrain, int chunkSize)
Completely reads the given stream's bytes into aByteString
, blocking if necessary until all bytes are read through to the end of the stream.static ByteString
readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize)
abstract int
size()
Gets the number of bytes.boolean
startsWith(ByteString prefix)
Tests if this bytestring starts with the specified prefix.ByteString
substring(int beginIndex)
Return the substring frombeginIndex
, inclusive, to the end of the string.abstract ByteString
substring(int beginIndex, int endIndex)
Return the substring frombeginIndex
, inclusive, toendIndex
, exclusive.byte[]
toByteArray()
Copies bytes to abyte[]
.java.lang.String
toString()
abstract java.lang.String
toString(java.lang.String charsetName)
Constructs a newString
by decoding the bytes using the specified charset.java.lang.String
toStringUtf8()
Constructs a newString
by decoding the bytes as UTF-8.abstract void
writeTo(java.io.OutputStream out)
Writes the complete contents of this byte string to the specified output stream argument.
-
-
-
Field Detail
-
EMPTY
public static final ByteString EMPTY
EmptyByteString
.
-
-
Method Detail
-
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 theByteString.ByteIterator
returned byiterator()
, and callsubstring(int, int)
first if necessary.- Parameters:
index
- index of byte- Returns:
- the value
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-index
is < 0 or ≥ size
-
iterator
public abstract ByteString.ByteIterator iterator()
Return aByteString.ByteIterator
over the bytes in the ByteString. To avoid auto-boxing, you may get the iterator manually and callByteString.ByteIterator.nextByte()
.- Specified by:
iterator
in interfacejava.lang.Iterable<java.lang.Byte>
- Returns:
- the iterator
-
size
public abstract int size()
Gets the number of bytes.- Returns:
- size in bytes
-
isEmpty
public boolean isEmpty()
Returnstrue
if the size is0
,false
otherwise.- Returns:
- true if this is zero bytes long
-
substring
public ByteString substring(int beginIndex)
Return the substring frombeginIndex
, inclusive, to the end of the string.- Parameters:
beginIndex
- start at this index- Returns:
- substring sharing underlying data
- Throws:
java.lang.IndexOutOfBoundsException
- ifbeginIndex < 0
orbeginIndex > size()
.
-
substring
public abstract ByteString substring(int beginIndex, int endIndex)
Return the substring frombeginIndex
, inclusive, toendIndex
, exclusive.- Parameters:
beginIndex
- start at this indexendIndex
- the last character is the one before this index- Returns:
- substring sharing underlying data
- Throws:
java.lang.IndexOutOfBoundsException
- ifbeginIndex < 0
,endIndex > size()
, orbeginIndex > endIndex
.
-
startsWith
public boolean startsWith(ByteString prefix)
Tests if this bytestring starts with the specified prefix. Similar toString.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.
-
copyFrom
public static ByteString copyFrom(byte[] bytes, int offset, int size)
Copies the given bytes into aByteString
.- Parameters:
bytes
- source arrayoffset
- offset in source arraysize
- number of bytes to copy- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(byte[] bytes)
Copies the given bytes into aByteString
.- Parameters:
bytes
- to copy- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(java.nio.ByteBuffer bytes, int size)
Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- source buffersize
- number of bytes to copy- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(java.nio.ByteBuffer bytes)
Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- sourceBuffer- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(java.lang.String text, java.lang.String charsetName) throws java.io.UnsupportedEncodingException
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.- Parameters:
text
- source stringcharsetName
- encoding to use- Returns:
- new
ByteString
- Throws:
java.io.UnsupportedEncodingException
- if the encoding isn't found
-
copyFromUtf8
public static ByteString copyFromUtf8(java.lang.String text)
Encodestext
into a sequence of UTF-8 bytes and returns the result as aByteString
.- Parameters:
text
- source string- Returns:
- new
ByteString
-
readFrom
public static ByteString readFrom(java.io.InputStream streamToDrain) throws java.io.IOException
Completely reads the given stream's bytes into aByteString
, blocking if necessary until all bytes are read through to the end of the stream. Performance notes: The returnedByteString
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
ByteString
which is made up of chunks of various sizes, depending on the behavior of the underlying stream. - Throws:
java.io.IOException
- IOException is thrown if there is a problem reading the underlying stream.
-
readFrom
public static ByteString readFrom(java.io.InputStream streamToDrain, int chunkSize) throws java.io.IOException
Completely reads the given stream's bytes into aByteString
, blocking if necessary until all bytes are read through to the end of the stream. Performance notes: The returnedByteString
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
ByteString
which is made up of chunks of the given size. - Throws:
java.io.IOException
- IOException is thrown if there is a problem reading the underlying stream.
-
readFrom
public static ByteString readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws java.io.IOException
- Throws:
java.io.IOException
-
concat
public ByteString concat(ByteString other)
Concatenate the givenByteString
to this one. Short concatenations, of total size smaller thanCONCATENATE_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
ByteString
instance
-
copyFrom
public static ByteString copyFrom(java.lang.Iterable<ByteString> 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
ByteString
is not necessarily a unique object. If the list is empty, the returned object is the singleton emptyByteString
. If the list has only one element, thatByteString
will be returned without copying.- Parameters:
byteStrings
- strings to be concatenated- Returns:
- new
ByteString
-
copyTo
public void copyTo(byte[] target, int offset)
Copies bytes into a buffer at the given offset.- Parameters:
target
- buffer to copy intooffset
- in the target buffer- Throws:
java.lang.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 intosourceOffset
- offset within these bytestargetOffset
- offset within the target buffernumberToCopy
- number of bytes to copy- Throws:
java.lang.IndexOutOfBoundsException
- if an offset or size is negative or too large
-
copyToInternal
protected abstract void copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)
Internal (package private) implementation ofcopyTo
. It assumes that all error checking has already been performed and thatnumberToCopy > 0
.
-
copyTo
public abstract void copyTo(java.nio.ByteBuffer target)
Copies bytes into a ByteBuffer.- Parameters:
target
- ByteBuffer to copy into.- Throws:
java.nio.ReadOnlyBufferException
- if thetarget
is read-onlyjava.nio.BufferOverflowException
- if thetarget
's remaining() space is not large enough to hold the data.
-
toByteArray
public byte[] toByteArray()
Copies bytes to abyte[]
.- Returns:
- copied bytes
-
writeTo
public abstract void writeTo(java.io.OutputStream out) throws java.io.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:
java.io.IOException
- if an I/O error occurs.
-
asReadOnlyByteBuffer
public abstract java.nio.ByteBuffer asReadOnlyByteBuffer()
Constructs a read-onlyjava.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 java.util.List<java.nio.ByteBuffer> asReadOnlyByteBufferList()
Constructs a list of read-onlyjava.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
-
toString
public abstract java.lang.String toString(java.lang.String charsetName) throws java.io.UnsupportedEncodingException
Constructs a newString
by decoding the bytes using the specified charset.- Parameters:
charsetName
- encode using this charset- Returns:
- new string
- Throws:
java.io.UnsupportedEncodingException
- if charset isn't recognized
-
toStringUtf8
public java.lang.String toStringUtf8()
Constructs a newString
by decoding the bytes as UTF-8.- Returns:
- new string using UTF-8 encoding
-
isValidUtf8
public abstract boolean isValidUtf8()
Tells whether thisByteString
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
ByteString
are a well-formed UTF-8 byte sequence
-
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 multipleByteString
segments.- Parameters:
state
- either0
(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- 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.
-
equals
public abstract boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public abstract int hashCode()
Return a non-zero hashCode depending only on the sequence of bytes in this ByteString.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- hashCode value for this object
-
newInput
public abstract java.io.InputStream newInput()
Creates anInputStream
which can be used to read the bytes.The
InputStream
returned by this method is guaranteed to be completely non-blocking. The methodInputStream.available()
returns the number of bytes remaining in the stream. The methodsInputStream.read(byte[])
,InputStream.read(byte[],int,int)
andInputStream.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.
-
newCodedInput
public abstract CodedInputStream newCodedInput()
Creates aCodedInputStream
which can be used to read the bytes. Using this is often more efficient than creating aCodedInputStream
that wraps the result ofnewInput()
.- Returns:
- stream based on wrapped data
-
newOutput
public static ByteString.Output newOutput(int initialCapacity)
Creates a newByteString.Output
with the given initial capacity. CallByteString.Output.toByteString()
to create theByteString
instance.A
ByteString.Output
offers the same functionality as aByteArrayOutputStream
, except that it returns aByteString
rather than abyte
array.- Parameters:
initialCapacity
- estimate of number of bytes to be written- Returns:
OutputStream
for building aByteString
-
newOutput
public static ByteString.Output newOutput()
Creates a newByteString.Output
. CallByteString.Output.toByteString()
to create theByteString
instance.A
ByteString.Output
offers the same functionality as aByteArrayOutputStream
, except that it returns aByteString
rather than abyte array
.- Returns:
OutputStream
for building aByteString
-
getTreeDepth
protected abstract int getTreeDepth()
Return the depth of the tree representing thisByteString
, if any, whose root is this node. If this is a leaf node, return 0.- Returns:
- tree depth or zero
-
isBalanced
protected abstract boolean isBalanced()
Returntrue
if this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString
.- Returns:
- true if the tree is flat enough
-
peekCachedHashCode
protected abstract int peekCachedHashCode()
Return the cached hash code if available.- Returns:
- value of cached hash code or 0 if not computed yet
-
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 valueoffset
- offset into this value to start looking at data valueslength
- number of data values to include in the hash computation- Returns:
- ending hash value
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-