diff options
Diffstat (limited to 'java/core/src/main/java/com/google/protobuf/ByteString.java')
| -rw-r--r-- | java/core/src/main/java/com/google/protobuf/ByteString.java | 702 |
1 files changed, 354 insertions, 348 deletions
diff --git a/java/core/src/main/java/com/google/protobuf/ByteString.java b/java/core/src/main/java/com/google/protobuf/ByteString.java index d67bb54a..844d8a53 100644 --- a/java/core/src/main/java/com/google/protobuf/ByteString.java +++ b/java/core/src/main/java/com/google/protobuf/ByteString.java @@ -46,6 +46,7 @@ import java.util.ArrayList; import java.util.Arrays; import java.util.Collection; import java.util.Collections; +import java.util.Comparator; import java.util.Iterator; import java.util.List; import java.util.NoSuchElementException; @@ -66,41 +67,36 @@ import java.util.NoSuchElementException; public abstract class ByteString implements Iterable<Byte>, Serializable { /** - * When two strings to be concatenated have a combined length shorter than - * this, we just copy their bytes on {@link #concat(ByteString)}. - * The trade-off is copy size versus the overhead of creating tree nodes - * in {@link RopeByteString}. + * When two strings to be concatenated have a combined length shorter than this, we just copy + * their bytes on {@link #concat(ByteString)}. The trade-off is copy size versus the overhead of + * creating tree nodes in {@link RopeByteString}. */ static final int CONCATENATE_BY_COPY_SIZE = 128; /** - * When copying an InputStream into a ByteString with .readFrom(), - * the chunks in the underlying rope start at 256 bytes, but double - * each iteration up to 8192 bytes. + * When copying an InputStream into a ByteString with .readFrom(), the chunks in the underlying + * rope start at 256 bytes, but double each iteration up to 8192 bytes. */ - static final int MIN_READ_FROM_CHUNK_SIZE = 0x100; // 256b - static final int MAX_READ_FROM_CHUNK_SIZE = 0x2000; // 8k + static final int MIN_READ_FROM_CHUNK_SIZE = 0x100; // 256b - /** - * Empty {@code ByteString}. - */ + static final int MAX_READ_FROM_CHUNK_SIZE = 0x2000; // 8k + + /** Empty {@code ByteString}. */ public static final ByteString EMPTY = new LiteralByteString(Internal.EMPTY_BYTE_ARRAY); /** * An interface to efficiently copy {@code byte[]}. * - * <p>One of the noticeable costs of copying a byte[] into a new array using - * {@code System.arraycopy} is nullification of a new buffer before the copy. It has been shown - * the Hotspot VM is capable to intrisicfy {@code Arrays.copyOfRange} operation to avoid this + * <p>One of the noticeable costs of copying a byte[] into a new array using {@code + * System.arraycopy} is nullification of a new buffer before the copy. It has been shown the + * Hotspot VM is capable to intrisicfy {@code Arrays.copyOfRange} operation to avoid this * expensive nullification and provide substantial performance gain. Unfortunately this does not - * hold on Android runtimes and could make the copy slightly slower due to additional code in - * the {@code Arrays.copyOfRange}. Thus we provide two different implementation for array copier - * for Hotspot and Android runtimes. + * hold on Android runtimes and could make the copy slightly slower due to additional code in the + * {@code Arrays.copyOfRange}. Thus we provide two different implementation for array copier for + * Hotspot and Android runtimes. */ private interface ByteArrayCopier { - /** - * Copies the specified range of the specified array into a new array - */ + /** Copies the specified range of the specified array into a new array */ byte[] copyFrom(byte[] bytes, int offset, int size); } @@ -123,15 +119,16 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } private static final ByteArrayCopier byteArrayCopier; + static { byteArrayCopier = Android.isOnAndroidDevice() ? new SystemByteArrayCopier() : new ArraysByteArrayCopier(); } /** - * Cached hash value. Intentionally accessed via a data race, which - * is safe because of the Java Memory Model's "no out-of-thin-air values" - * guarantees for ints. A value of 0 implies that the hash has not been set. + * Cached hash value. Intentionally accessed via a data race, which is safe because of the Java + * Memory Model's "no out-of-thin-air values" guarantees for ints. A value of 0 implies that the + * hash has not been set. */ private int hash = 0; @@ -139,10 +136,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { ByteString() {} /** - * 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 - * {@link ByteIterator} returned by {@link #iterator()}, and call {@link - * #substring(int, int)} first if necessary. + * 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 {@link ByteIterator} returned by {@link + * #iterator()}, and call {@link #substring(int, int)} first if necessary. * * @param index index of byte * @return the value @@ -151,9 +147,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { public abstract byte byteAt(int index); /** - * Return a {@link ByteString.ByteIterator} over the bytes in the ByteString. - * To avoid auto-boxing, you may get the iterator manually and call - * {@link ByteIterator#nextByte()}. + * Return a {@link ByteString.ByteIterator} over the bytes in the ByteString. To avoid + * auto-boxing, you may get the iterator manually and call {@link ByteIterator#nextByte()}. * * @return the iterator */ @@ -191,13 +186,11 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * This interface extends {@code Iterator<Byte>}, so that we can return an - * unboxed {@code byte}. + * This interface extends {@code Iterator<Byte>}, so that we can return an unboxed {@code byte}. */ public interface ByteIterator extends Iterator<Byte> { /** - * An alternative to {@link Iterator#next()} that returns an - * unboxed primitive {@code byte}. + * An alternative to {@link Iterator#next()} that returns an unboxed primitive {@code byte}. * * @return the next {@code byte} in the iteration * @throws NoSuchElementException if the iteration has no more elements @@ -222,59 +215,113 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } // ================================================================= + // Comparison + + private static final int UNSIGNED_BYTE_MASK = 0xFF; + + /** + * Returns the value of the given byte as an integer, interpreting the byte as an unsigned value. + * That is, returns {@code value + 256} if {@code value} is negative; {@code value} itself + * otherwise. + * + * <p>Note: This code was copied from {@link com.google.common.primitives.UnsignedBytes#toInt}, as + * Guava libraries cannot be used in the {@code com.google.protobuf} package. + */ + private static int toInt(byte value) { + return value & UNSIGNED_BYTE_MASK; + } + + /** + * Compares two {@link ByteString}s lexicographically, treating their contents as unsigned byte + * values between 0 and 255 (inclusive). + * + * <p>For example, {@code (byte) -1} is considered to be greater than {@code (byte) 1} because it + * is interpreted as an unsigned value, {@code 255}. + */ + private static final Comparator<ByteString> UNSIGNED_LEXICOGRAPHICAL_COMPARATOR = + new Comparator<ByteString>() { + @Override + public int compare(ByteString former, ByteString latter) { + ByteIterator formerBytes = former.iterator(); + ByteIterator latterBytes = latter.iterator(); + + while (formerBytes.hasNext() && latterBytes.hasNext()) { + // Note: This code was copied from com.google.common.primitives.UnsignedBytes#compare, + // as Guava libraries cannot be used in the {@code com.google.protobuf} package. + int result = + Integer.compare(toInt(formerBytes.nextByte()), toInt(latterBytes.nextByte())); + if (result != 0) { + return result; + } + } + + return Integer.compare(former.size(), latter.size()); + } + }; + + /** + * Returns a {@link Comparator<ByteString>} which compares {@link ByteString}-s lexicographically + * as sequences of unsigned bytes (i.e. values between 0 and 255, inclusive). + * + * <p>For example, {@code (byte) -1} is considered to be greater than {@code (byte) 1} because it + * is interpreted as an unsigned value, {@code 255}: + * + * <ul> + * <li>{@code `-1` -> 0b11111111 (two's complement) -> 255} + * <li>{@code `1` -> 0b00000001 -> 1} + * </ul> + */ + public static Comparator<ByteString> unsignedLexicographicalComparator() { + return UNSIGNED_LEXICOGRAPHICAL_COMPARATOR; + } + + // ================================================================= // ByteString -> substring /** - * Return the substring from {@code beginIndex}, inclusive, to the end of the - * string. + * Return the substring from {@code beginIndex}, inclusive, to the end of the string. * * @param beginIndex start at this index * @return substring sharing underlying data - * @throws IndexOutOfBoundsException if {@code beginIndex < 0} or - * {@code beginIndex > size()}. + * @throws IndexOutOfBoundsException if {@code beginIndex < 0} or {@code beginIndex > size()}. */ public final ByteString substring(int beginIndex) { return substring(beginIndex, size()); } /** - * Return the substring from {@code beginIndex}, inclusive, to {@code - * endIndex}, exclusive. + * Return the substring from {@code beginIndex}, inclusive, to {@code endIndex}, exclusive. * * @param beginIndex start at this index - * @param endIndex the last character is the one before this index + * @param endIndex the last character is the one before this index * @return substring sharing underlying data - * @throws IndexOutOfBoundsException if {@code beginIndex < 0}, - * {@code endIndex > size()}, or {@code beginIndex > endIndex}. + * @throws IndexOutOfBoundsException if {@code beginIndex < 0}, {@code endIndex > size()}, or + * {@code beginIndex > endIndex}. */ public abstract ByteString substring(int beginIndex, int endIndex); /** - * Tests if this bytestring starts with the specified prefix. - * Similar to {@link String#startsWith(String)} + * Tests if this bytestring starts with the specified prefix. Similar to {@link + * String#startsWith(String)} * * @param prefix the prefix. - * @return <code>true</code> if the byte sequence represented by the - * argument is a prefix of the byte sequence represented by - * this string; <code>false</code> otherwise. + * @return <code>true</code> if the byte sequence represented by the argument is a prefix of the + * byte sequence represented by this string; <code>false</code> otherwise. */ public final boolean startsWith(ByteString prefix) { - return size() >= prefix.size() && - substring(0, prefix.size()).equals(prefix); + return size() >= prefix.size() && substring(0, prefix.size()).equals(prefix); } /** - * Tests if this bytestring ends with the specified suffix. - * Similar to {@link String#endsWith(String)} + * Tests if this bytestring ends with the specified suffix. Similar to {@link + * String#endsWith(String)} * * @param suffix the suffix. - * @return <code>true</code> if the byte sequence represented by the - * argument is a suffix of the byte sequence represented by - * this string; <code>false</code> otherwise. + * @return <code>true</code> if the byte sequence represented by the argument is a suffix of the + * byte sequence represented by this string; <code>false</code> otherwise. */ public final boolean endsWith(ByteString suffix) { - return size() >= suffix.size() && - substring(size() - suffix.size()).equals(suffix); + return size() >= suffix.size() && substring(size() - suffix.size()).equals(suffix); } // ================================================================= @@ -287,8 +334,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { * @param offset offset in source array * @param size number of bytes to copy * @return new {@code ByteString} + * @throws IndexOutOfBoundsException if {@code offset} or {@code size} are out of bounds */ public static ByteString copyFrom(byte[] bytes, int offset, int size) { + checkRange(offset, offset + size, bytes.length); return new LiteralByteString(byteArrayCopier.copyFrom(bytes, offset, size)); } @@ -302,9 +351,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { return copyFrom(bytes, 0, bytes.length); } - /** - * Wraps the given bytes into a {@code ByteString}. Intended for internal only usage. - */ + /** Wraps the given bytes into a {@code ByteString}. Intended for internal only usage. */ static ByteString wrap(ByteBuffer buffer) { if (buffer.hasArray()) { final int offset = buffer.arrayOffset(); @@ -315,8 +362,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Wraps the given bytes into a {@code ByteString}. Intended for internal only - * usage to force a classload of ByteString before LiteralByteString. + * Wraps the given bytes into a {@code ByteString}. Intended for internal only usage to force a + * classload of ByteString before LiteralByteString. */ static ByteString wrap(byte[] bytes) { // TODO(dweis): Return EMPTY when bytes are empty to reduce allocations? @@ -324,31 +371,31 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Wraps the given bytes into a {@code ByteString}. Intended for internal only - * usage to force a classload of ByteString before BoundedByteString and - * LiteralByteString. + * Wraps the given bytes into a {@code ByteString}. Intended for internal only usage to force a + * classload of ByteString before BoundedByteString and LiteralByteString. */ static ByteString wrap(byte[] bytes, int offset, int length) { return new BoundedByteString(bytes, offset, length); } /** - * Copies the next {@code size} bytes from a {@code java.nio.ByteBuffer} into - * a {@code ByteString}. + * Copies the next {@code size} bytes from a {@code java.nio.ByteBuffer} into a {@code + * ByteString}. * * @param bytes source buffer * @param size number of bytes to copy * @return new {@code ByteString} + * @throws IndexOutOfBoundsException if {@code size > bytes.remaining()} */ public static ByteString copyFrom(ByteBuffer bytes, int size) { + checkRange(0, size, bytes.remaining()); byte[] copy = new byte[size]; bytes.get(copy); return new LiteralByteString(copy); } /** - * Copies the remaining bytes from a {@code java.nio.ByteBuffer} into - * a {@code ByteString}. + * Copies the remaining bytes from a {@code java.nio.ByteBuffer} into a {@code ByteString}. * * @param bytes sourceBuffer * @return new {@code ByteString} @@ -358,8 +405,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Encodes {@code text} into a sequence of bytes using the named charset - * and returns the result as a {@code ByteString}. + * Encodes {@code text} into a sequence of bytes using the named charset and returns the result as + * a {@code ByteString}. * * @param text source string * @param charsetName encoding to use @@ -372,8 +419,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Encodes {@code text} into a sequence of bytes using the named charset - * and returns the result as a {@code ByteString}. + * Encodes {@code text} into a sequence of bytes using the named charset and returns the result as + * a {@code ByteString}. * * @param text source string * @param charset encode using this charset @@ -384,8 +431,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Encodes {@code text} into a sequence of UTF-8 bytes and returns the - * result as a {@code ByteString}. + * Encodes {@code text} into a sequence of UTF-8 bytes and returns the result as a {@code + * ByteString}. * * @param text source string * @return new {@code ByteString} @@ -398,60 +445,48 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { // InputStream -> ByteString /** - * Completely reads the given stream's bytes into a - * {@code ByteString}, blocking if necessary until all bytes are - * read through to the end of the stream. - * - * <b>Performance notes:</b> The returned {@code ByteString} 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. - * - * <p>Each byte read from the input stream will be copied twice to ensure - * that the resulting ByteString is truly immutable. - * - * @param streamToDrain The source stream, which is read completely - * but not closed. - * @return A new {@code ByteString} 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. + * Completely reads the given stream's bytes into a {@code ByteString}, blocking if necessary + * until all bytes are read through to the end of the stream. + * + * <p><b>Performance notes:</b> The returned {@code ByteString} 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. + * + * <p>Each byte read from the input stream will be copied twice to ensure that the resulting + * ByteString is truly immutable. + * + * @param streamToDrain The source stream, which is read completely but not closed. + * @return A new {@code ByteString} 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. */ - public static ByteString readFrom(InputStream streamToDrain) - throws IOException { + public static ByteString readFrom(InputStream streamToDrain) throws IOException { return readFrom(streamToDrain, MIN_READ_FROM_CHUNK_SIZE, MAX_READ_FROM_CHUNK_SIZE); } /** - * Completely reads the given stream's bytes into a - * {@code ByteString}, blocking if necessary until all bytes are - * read through to the end of the stream. - * - * <b>Performance notes:</b> The returned {@code ByteString} is an - * immutable tree of byte arrays ("chunks") of the stream data. The - * chunkSize parameter sets the size of these byte arrays. - * - * <p>Each byte read from the input stream will be copied twice to ensure - * that the resulting ByteString is truly immutable. - * - * @param streamToDrain The source stream, which is read completely - * but not closed. - * @param chunkSize The size of the chunks in which to read the - * stream. - * @return A new {@code ByteString} which is made up of chunks of - * the given size. - * @throws IOException IOException is thrown if there is a problem - * reading the underlying stream. + * Completely reads the given stream's bytes into a {@code ByteString}, blocking if necessary + * until all bytes are read through to the end of the stream. + * + * <p><b>Performance notes:</b> The returned {@code ByteString} is an immutable tree of byte + * arrays ("chunks") of the stream data. The chunkSize parameter sets the size of these byte + * arrays. + * + * <p>Each byte read from the input stream will be copied twice to ensure that the resulting + * ByteString is truly immutable. + * + * @param streamToDrain The source stream, which is read completely but not closed. + * @param chunkSize The size of the chunks in which to read the stream. + * @return A new {@code ByteString} which is made up of chunks of the given size. + * @throws IOException IOException is thrown if there is a problem reading the underlying stream. */ - public static ByteString readFrom(InputStream streamToDrain, int chunkSize) - throws IOException { + public static ByteString readFrom(InputStream streamToDrain, int chunkSize) throws IOException { return readFrom(streamToDrain, chunkSize, chunkSize); } // Helper method that takes the chunk size range as a parameter. - public static ByteString readFrom(InputStream streamToDrain, int minChunkSize, - int maxChunkSize) throws IOException { + public static ByteString readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize) + throws IOException { Collection<ByteString> results = new ArrayList<ByteString>(); // copy the inbound bytes into a list of chunks; the chunk size @@ -470,42 +505,39 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Blocks until a chunk of the given size can be made from the - * stream, or EOF is reached. Calls read() repeatedly in case the - * given stream implementation doesn't completely fill the given + * Blocks until a chunk of the given size can be made from the stream, or EOF is reached. Calls + * read() repeatedly in case the given stream implementation doesn't completely fill the given * buffer in one read() call. * - * @return A chunk of the desired size, or else a chunk as large as - * was available when end of stream was reached. Returns null if the - * given stream had no more data in it. + * @return A chunk of the desired size, or else a chunk as large as was available when end of + * stream was reached. Returns null if the given stream had no more data in it. */ - private static ByteString readChunk(InputStream in, final int chunkSize) - throws IOException { - final byte[] buf = new byte[chunkSize]; - int bytesRead = 0; - while (bytesRead < chunkSize) { - final int count = in.read(buf, bytesRead, chunkSize - bytesRead); - if (count == -1) { - break; - } - bytesRead += count; + private static ByteString readChunk(InputStream in, final int chunkSize) throws IOException { + final byte[] buf = new byte[chunkSize]; + int bytesRead = 0; + while (bytesRead < chunkSize) { + final int count = in.read(buf, bytesRead, chunkSize - bytesRead); + if (count == -1) { + break; } + bytesRead += count; + } - if (bytesRead == 0) { - return null; - } + if (bytesRead == 0) { + return null; + } - // Always make a copy since InputStream could steal a reference to buf. - return ByteString.copyFrom(buf, 0, bytesRead); + // Always make a copy since InputStream could steal a reference to buf. + return ByteString.copyFrom(buf, 0, bytesRead); } // ================================================================= // Multiple ByteStrings -> One ByteString /** - * Concatenate the given {@code ByteString} to this one. Short concatenations, - * of total size smaller than {@link ByteString#CONCATENATE_BY_COPY_SIZE}, are - * produced by copying the underlying bytes (as per Rope.java, <a + * Concatenate the given {@code ByteString} to this one. Short concatenations, of total size + * smaller than {@link ByteString#CONCATENATE_BY_COPY_SIZE}, are produced by copying the + * underlying bytes (as per Rope.java, <a * href="http://www.cs.ubc.ca/local/reading/proceedings/spe91-95/spe/vol25/issue12/spe986.pdf"> * BAP95 </a>. In general, the concatenate involves no copying. * @@ -514,21 +546,20 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { */ public final ByteString concat(ByteString other) { if (Integer.MAX_VALUE - size() < other.size()) { - throw new IllegalArgumentException("ByteString would be too long: " + - size() + "+" + other.size()); + throw new IllegalArgumentException( + "ByteString would be too long: " + size() + "+" + other.size()); } return RopeByteString.concatenate(this, other); } /** - * Concatenates all byte strings in the iterable and returns the result. - * This is designed to run in O(list size), not O(total bytes). + * Concatenates all byte strings in the iterable and returns the result. This is designed to run + * in O(list size), not O(total bytes). * - * <p>The returned {@code ByteString} is not necessarily a unique object. - * If the list is empty, the returned object is the singleton empty - * {@code ByteString}. If the list has only one element, that - * {@code ByteString} will be returned without copying. + * <p>The returned {@code ByteString} is not necessarily a unique object. If the list is empty, + * the returned object is the singleton empty {@code ByteString}. If the list has only one + * element, that {@code ByteString} will be returned without copying. * * @param byteStrings strings to be concatenated * @return new {@code ByteString} @@ -538,9 +569,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { final int size; if (!(byteStrings instanceof Collection)) { int tempSize = 0; - for (Iterator<ByteString> iter = byteStrings.iterator(); iter.hasNext(); - iter.next(), ++tempSize) { - } + for (Iterator<ByteString> iter = byteStrings.iterator(); + iter.hasNext(); + iter.next(), ++tempSize) {} size = tempSize; } else { size = ((Collection<ByteString>) byteStrings).size(); @@ -578,6 +609,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Copies bytes into a buffer at the given offset. * + * <p>To copy a subset of bytes, you call this method on the return value of {@link + * #substring(int, int)}. Example: {@code byteString.substring(start, end).copyTo(target, offset)} + * * @param target buffer to copy into * @param offset in the target buffer * @throws IndexOutOfBoundsException if the offset is negative or too large @@ -589,15 +623,16 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Copies bytes into a buffer. * - * @param target buffer to copy into + * @param target buffer to copy into * @param sourceOffset offset within these bytes * @param targetOffset offset within the target buffer * @param numberToCopy number of bytes to copy - * @throws IndexOutOfBoundsException if an offset or size is negative or too - * large + * @throws IndexOutOfBoundsException if an offset or size is negative or too large + * @deprecation Instead, call {@code byteString.substring(sourceOffset, sourceOffset + + * numberToCopy).copyTo(target, targetOffset)} */ - public final void copyTo(byte[] target, int sourceOffset, int targetOffset, - int numberToCopy) { + @Deprecated + public final void copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy) { checkRange(sourceOffset, sourceOffset + numberToCopy, size()); checkRange(targetOffset, targetOffset + numberToCopy, target.length); if (numberToCopy > 0) { @@ -606,21 +641,22 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Internal (package private) implementation of - * {@link #copyTo(byte[],int,int,int)}. - * It assumes that all error checking has already been performed and that - * {@code numberToCopy > 0}. + * Internal (package private) implementation of {@link #copyTo(byte[],int,int,int)}. It assumes + * that all error checking has already been performed and that {@code numberToCopy > 0}. */ - protected abstract void copyToInternal(byte[] target, int sourceOffset, - int targetOffset, int numberToCopy); + protected abstract void copyToInternal( + byte[] target, int sourceOffset, int targetOffset, int numberToCopy); /** * Copies bytes into a ByteBuffer. * + * <p>To copy a subset of bytes, you call this method on the return value of {@link + * #substring(int, int)}. Example: {@code byteString.substring(start, end).copyTo(target)} + * * @param target ByteBuffer to copy into. * @throws java.nio.ReadOnlyBufferException if the {@code target} is read-only - * @throws java.nio.BufferOverflowException if the {@code target}'s - * remaining() space is not large enough to hold the data. + * @throws java.nio.BufferOverflowException if the {@code target}'s remaining() space is not large + * enough to hold the data. */ public abstract void copyTo(ByteBuffer target); @@ -642,22 +678,21 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Writes a copy of the contents of this byte string to the specified output stream argument. * - * @param out the output stream to which to write the data. - * @throws IOException if an I/O error occurs. + * @param out the output stream to which to write the data. + * @throws IOException if an I/O error occurs. */ public abstract void writeTo(OutputStream out) throws IOException; /** * Writes a specified part of this byte string to an output stream. * - * @param out the output stream to which to write the data. - * @param sourceOffset offset within these bytes - * @param numberToWrite number of bytes to write - * @throws IOException if an I/O error occurs. + * @param out the output stream to which to write the data. + * @param sourceOffset offset within these bytes + * @param numberToWrite number of bytes to write + * @throws IOException if an I/O error occurs. * @throws IndexOutOfBoundsException if an offset or size is negative or too large */ - final void writeTo(OutputStream out, int sourceOffset, int numberToWrite) - throws IOException { + final void writeTo(OutputStream out, int sourceOffset, int numberToWrite) throws IOException { checkRange(sourceOffset, sourceOffset + numberToWrite, size()); if (numberToWrite > 0) { writeToInternal(out, sourceOffset, numberToWrite); @@ -665,59 +700,55 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Internal version of {@link #writeTo(OutputStream,int,int)} that assumes - * all error checking has already been done. + * Internal version of {@link #writeTo(OutputStream,int,int)} that assumes all error checking has + * already been done. */ abstract void writeToInternal(OutputStream out, int sourceOffset, int numberToWrite) throws IOException; /** - * Writes this {@link ByteString} to the provided {@link ByteOutput}. Calling - * this method may result in multiple operations on the target {@link ByteOutput}. + * Writes this {@link ByteString} to the provided {@link ByteOutput}. Calling this method may + * result in multiple operations on the target {@link ByteOutput}. * * <p>This method may expose internal backing buffers of the {@link ByteString} to the {@link * ByteOutput} in order to avoid additional copying overhead. It would be possible for a malicious * {@link ByteOutput} to corrupt the {@link ByteString}. Use with caution! * - * @param byteOutput the output target to receive the bytes - * @throws IOException if an I/O error occurs + * @param byteOutput the output target to receive the bytes + * @throws IOException if an I/O error occurs * @see UnsafeByteOperations#unsafeWriteTo(ByteString, ByteOutput) */ abstract void writeTo(ByteOutput byteOutput) throws IOException; /** - * Constructs a read-only {@code 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. + * Constructs a read-only {@code 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. * * @return wrapped bytes */ public abstract ByteBuffer asReadOnlyByteBuffer(); /** - * Constructs a list of read-only {@code 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. - * <p> - * By returning a list, implementations of this method may be able to avoid - * copying even when there are multiple backing arrays. + * Constructs a list of read-only {@code 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. + * + * <p>By returning a list, implementations of this method may be able to avoid copying even when + * there are multiple backing arrays. * * @return a list of wrapped bytes */ public abstract List<ByteBuffer> asReadOnlyByteBufferList(); /** - * Constructs a new {@code String} by decoding the bytes using the - * specified charset. + * Constructs a new {@code String} by decoding the bytes using the specified charset. * * @param charsetName encode using this charset * @return new string * @throws UnsupportedEncodingException if charset isn't recognized */ - public final String toString(String charsetName) - throws UnsupportedEncodingException { + public final String toString(String charsetName) throws UnsupportedEncodingException { try { return toString(Charset.forName(charsetName)); } catch (UnsupportedCharsetException e) { @@ -728,8 +759,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Constructs a new {@code String} by decoding the bytes using the - * specified charset. Returns the same empty String if empty. + * Constructs a new {@code String} by decoding the bytes using the specified charset. Returns the + * same empty String if empty. * * @param charset encode using this charset * @return new string @@ -739,8 +770,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Constructs a new {@code String} by decoding the bytes using the - * specified charset. + * Constructs a new {@code String} by decoding the bytes using the specified charset. * * @param charset encode using this charset * @return new string @@ -760,50 +790,45 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Tells whether this {@code ByteString} 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. + * Tells whether this {@code ByteString} 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. + * + * <p>More precisely, returns {@code true} whenever: * - * <p>More precisely, returns {@code true} whenever: <pre> {@code + * <pre>{@code * Arrays.equals(byteString.toByteArray(), * new String(byteString.toByteArray(), "UTF-8").getBytes("UTF-8")) * }</pre> * - * <p>This method returns {@code 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. + * <p>This method returns {@code 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. * * <p>See the Unicode Standard,<br> * Table 3-6. <em>UTF-8 Bit Distribution</em>,<br> * Table 3-7. <em>Well Formed UTF-8 Byte Sequences</em>. * - * @return whether the bytes in this {@code ByteString} are a - * well-formed UTF-8 byte sequence + * @return whether the bytes in this {@code ByteString} are a well-formed UTF-8 byte sequence */ public abstract boolean isValidUtf8(); /** - * 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 {@code ByteString} segments. - * - * @param state either {@code 0} (if this is the initial decoding operation) - * or the value returned from a call to a partial decoding method for the - * previous bytes + * 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 {@code ByteString} segments. + * + * @param state either {@code 0} (if this is the initial decoding operation) or the value returned + * from a call to a partial decoding method for the previous bytes * @param offset offset of the first byte to check * @param length number of bytes to check - * - * @return {@code -1} if the partial byte sequence is definitely malformed, - * {@code 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. + * @return {@code -1} if the partial byte sequence is definitely malformed, {@code 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 partialIsValidUtf8(int state, int offset, int length); @@ -813,9 +838,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { @Override public abstract boolean equals(Object o); - /** - * Base class for leaf {@link ByteString}s (i.e. non-ropes). - */ + /** Base class for leaf {@link ByteString}s (i.e. non-ropes). */ abstract static class LeafByteString extends ByteString { @Override protected final int getTreeDepth() { @@ -829,10 +852,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** - * Check equality of the substring of given length of this object starting at - * zero with another {@code ByteString} substring starting at offset. + * Check equality of the substring of given length of this object starting at zero with another + * {@code ByteString} substring starting at offset. * - * @param other what to compare a substring in + * @param other what to compare a substring in * @param offset offset into other * @param length number of bytes to compare * @return true for equality of substrings, else false. @@ -841,8 +864,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Compute the hashCode using the traditional algorithm from {@link - * ByteString}. + * Compute the hashCode using the traditional algorithm from {@link ByteString}. * * @return hashCode value */ @@ -866,26 +888,23 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Creates an {@code InputStream} which can be used to read the bytes. - * <p> - * The {@link InputStream} returned by this method is guaranteed to be - * completely non-blocking. The method {@link InputStream#available()} - * returns the number of bytes remaining in the stream. The methods - * {@link InputStream#read(byte[])}, {@link InputStream#read(byte[],int,int)} - * and {@link InputStream#skip(long)} will read/skip as many bytes as are - * available. The method {@link InputStream#markSupported()} returns - * {@code true}. - * <p> - * The methods in the returned {@link InputStream} might <b>not</b> be - * thread safe. + * + * <p>The {@link InputStream} returned by this method is guaranteed to be completely non-blocking. + * The method {@link InputStream#available()} returns the number of bytes remaining in the stream. + * The methods {@link InputStream#read(byte[])}, {@link InputStream#read(byte[],int,int)} and + * {@link InputStream#skip(long)} will read/skip as many bytes as are available. The method {@link + * InputStream#markSupported()} returns {@code true}. + * + * <p>The methods in the returned {@link InputStream} might <b>not</b> be thread safe. * * @return an input stream that returns the bytes of this byte string. */ public abstract InputStream newInput(); /** - * Creates a {@link CodedInputStream} which can be used to read the bytes. - * Using this is often more efficient than creating a {@link CodedInputStream} - * that wraps the result of {@link #newInput()}. + * Creates a {@link CodedInputStream} which can be used to read the bytes. Using this is often + * more efficient than creating a {@link CodedInputStream} that wraps the result of {@link + * #newInput()}. * * @return stream based on wrapped data */ @@ -897,10 +916,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Creates a new {@link Output} with the given initial capacity. Call {@link * Output#toByteString()} to create the {@code ByteString} instance. - * <p> - * A {@link ByteString.Output} offers the same functionality as a - * {@link ByteArrayOutputStream}, except that it returns a {@link ByteString} - * rather than a {@code byte} array. + * + * <p>A {@link ByteString.Output} offers the same functionality as a {@link + * ByteArrayOutputStream}, except that it returns a {@link ByteString} rather than a {@code byte} + * array. * * @param initialCapacity estimate of number of bytes to be written * @return {@code OutputStream} for building a {@code ByteString} @@ -910,12 +929,12 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Creates a new {@link Output}. Call {@link Output#toByteString()} to create - * the {@code ByteString} instance. - * <p> - * A {@link ByteString.Output} offers the same functionality as a - * {@link ByteArrayOutputStream}, except that it returns a {@link ByteString} - * rather than a {@code byte array}. + * Creates a new {@link Output}. Call {@link Output#toByteString()} to create the {@code + * ByteString} instance. + * + * <p>A {@link ByteString.Output} offers the same functionality as a {@link + * ByteArrayOutputStream}, except that it returns a {@link ByteString} rather than a {@code byte + * array}. * * @return {@code OutputStream} for building a {@code ByteString} */ @@ -924,8 +943,8 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Outputs to a {@code ByteString} instance. Call {@link #toByteString()} to - * create the {@code ByteString} instance. + * Outputs to a {@code ByteString} instance. Call {@link #toByteString()} to create the {@code + * ByteString} instance. */ public static final class Output extends OutputStream { // Implementation note. @@ -947,10 +966,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { private int bufferPos; /** - * Creates a new ByteString output stream with the specified - * initial capacity. + * Creates a new ByteString output stream with the specified initial capacity. * - * @param initialCapacity the initial capacity of the output stream. + * @param initialCapacity the initial capacity of the output stream. */ Output(int initialCapacity) { if (initialCapacity < 0) { @@ -966,43 +984,41 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { if (bufferPos == buffer.length) { flushFullBuffer(1); } - buffer[bufferPos++] = (byte)b; + buffer[bufferPos++] = (byte) b; } @Override - public synchronized void write(byte[] b, int offset, int length) { + public synchronized void write(byte[] b, int offset, int length) { if (length <= buffer.length - bufferPos) { // The bytes can fit into the current buffer. System.arraycopy(b, offset, buffer, bufferPos, length); bufferPos += length; } else { // Use up the current buffer - int copySize = buffer.length - bufferPos; + int copySize = buffer.length - bufferPos; System.arraycopy(b, offset, buffer, bufferPos, copySize); offset += copySize; length -= copySize; // Flush the buffer, and get a new buffer at least big enough to cover // what we still need to output flushFullBuffer(length); - System.arraycopy(b, offset, buffer, 0 /* count */, length); + System.arraycopy(b, offset, buffer, /* count= */ 0, length); bufferPos = length; } } /** - * Creates a byte string. Its size is the current size of this output - * stream and its output has been copied to it. + * Creates a byte string. Its size is the current size of this output stream and its output has + * been copied to it. * - * @return the current contents of this output stream, as a byte string. + * @return the current contents of this output stream, as a byte string. */ public synchronized ByteString toByteString() { flushLastBuffer(); return ByteString.copyFrom(flushedBuffers); } - /** - * Implement java.util.Arrays.copyOf() for jdk 1.5. - */ + /** Implement java.util.Arrays.copyOf() for jdk 1.5. */ private byte[] copyArray(byte[] buffer, int length) { byte[] result = new byte[length]; System.arraycopy(buffer, 0, result, 0, Math.min(buffer.length, length)); @@ -1010,11 +1026,11 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Writes the complete contents of this byte array output stream to - * the specified output stream argument. + * Writes the complete contents of this byte array output stream to the specified output stream + * argument. * * @param out the output stream to which to write the data. - * @throws IOException if an I/O error occurs. + * @throws IOException if an I/O error occurs. */ public void writeTo(OutputStream out) throws IOException { ByteString[] cachedFlushBuffers; @@ -1023,8 +1039,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { synchronized (this) { // Copy the information we need into local variables so as to hold // the lock for as short a time as possible. - cachedFlushBuffers = - flushedBuffers.toArray(new ByteString[flushedBuffers.size()]); + cachedFlushBuffers = flushedBuffers.toArray(new ByteString[flushedBuffers.size()]); cachedBuffer = buffer; cachedBufferPos = bufferPos; } @@ -1038,16 +1053,15 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { /** * Returns the current size of the output stream. * - * @return the current size of the output stream + * @return the current size of the output stream */ public synchronized int size() { return flushedBuffersTotalBytes + bufferPos; } /** - * Resets this stream, so that all currently accumulated output in the - * output stream is discarded. The output stream can be used again, - * reusing the already allocated buffer space. + * Resets this stream, so that all currently accumulated output in the output stream is + * discarded. The output stream can be used again, reusing the already allocated buffer space. */ public synchronized void reset() { flushedBuffers.clear(); @@ -1057,32 +1071,31 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { @Override public String toString() { - return String.format("<ByteString.Output@%s size=%d>", + return String.format( + "<ByteString.Output@%s size=%d>", Integer.toHexString(System.identityHashCode(this)), size()); } /** - * Internal function used by writers. The current buffer is full, and the - * writer needs a new buffer whose size is at least the specified minimum - * size. + * Internal function used by writers. The current buffer is full, and the writer needs a new + * buffer whose size is at least the specified minimum size. */ - private void flushFullBuffer(int minSize) { + private void flushFullBuffer(int minSize) { flushedBuffers.add(new LiteralByteString(buffer)); flushedBuffersTotalBytes += buffer.length; // We want to increase our total capacity by 50%, but as a minimum, // the new buffer should also at least be >= minSize and // >= initial Capacity. - int newSize = Math.max(initialCapacity, - Math.max(minSize, flushedBuffersTotalBytes >>> 1)); + int newSize = Math.max(initialCapacity, Math.max(minSize, flushedBuffersTotalBytes >>> 1)); buffer = new byte[newSize]; bufferPos = 0; } /** - * Internal function used by {@link #toByteString()}. The current buffer may - * or may not be full, but it needs to be flushed. + * Internal function used by {@link #toByteString()}. The current buffer may or may not be full, + * but it needs to be flushed. */ - private void flushLastBuffer() { + private void flushLastBuffer() { if (bufferPos < buffer.length) { if (bufferPos > 0) { byte[] bufferCopy = copyArray(buffer, bufferPos); @@ -1105,17 +1118,15 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Constructs a new {@code ByteString} builder, which allows you to - * efficiently construct a {@code ByteString} by writing to a {@link - * CodedOutputStream}. Using this is much more efficient than calling {@code - * newOutput()} and wrapping that in a {@code CodedOutputStream}. + * Constructs a new {@code ByteString} builder, which allows you to efficiently construct a {@code + * ByteString} by writing to a {@link CodedOutputStream}. Using this is much more efficient than + * calling {@code newOutput()} and wrapping that in a {@code CodedOutputStream}. * - * <p>This is package-private because it's a somewhat confusing interface. - * Users can call {@link Message#toByteString()} instead of calling this - * directly. + * <p>This is package-private because it's a somewhat confusing interface. Users can call {@link + * Message#toByteString()} instead of calling this directly. * - * @param size The target byte size of the {@code ByteString}. You must write - * exactly this many bytes before building the result. + * @param size The target byte size of the {@code ByteString}. You must write exactly this many + * bytes before building the result. * @return the builder */ static CodedBuilder newCodedBuilder(int size) { @@ -1151,16 +1162,16 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { // public API. /** - * Return the depth of the tree representing this {@code ByteString}, if any, - * whose root is this node. If this is a leaf node, return 0. + * Return the depth of the tree representing this {@code ByteString}, if any, whose root is this + * node. If this is a leaf node, return 0. * * @return tree depth or zero */ protected abstract int getTreeDepth(); /** - * Return {@code true} if this ByteString is literal (a leaf node) or a - * flat-enough tree in the sense of {@link RopeByteString}. + * Return {@code true} if this ByteString is literal (a leaf node) or a flat-enough tree in the + * sense of {@link RopeByteString}. * * @return true if the tree is flat enough */ @@ -1176,10 +1187,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * 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. + * 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. * * @param h starting hash value * @param offset offset into this value to start looking at data values @@ -1231,16 +1241,15 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { @Override public final String toString() { - return String.format("<ByteString@%s size=%d>", - Integer.toHexString(System.identityHashCode(this)), size()); + return String.format( + "<ByteString@%s size=%d>", Integer.toHexString(System.identityHashCode(this)), size()); } /** - * This class implements a {@link com.google.protobuf.ByteString} backed by a - * single array of bytes, contiguous in memory. It supports substring by - * pointing to only a sub-range of the underlying byte array, meaning that a - * substring will reference the full byte-array of the string it's made from, - * exactly as with {@link String}. + * This class implements a {@link com.google.protobuf.ByteString} backed by a single array of + * bytes, contiguous in memory. It supports substring by pointing to only a sub-range of the + * underlying byte array, meaning that a substring will reference the full byte-array of the + * string it's made from, exactly as with {@link String}. * * @author carlanton@google.com (Carl Haverl) */ @@ -1252,12 +1261,14 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { protected final byte[] bytes; /** - * Creates a {@code LiteralByteString} backed by the given array, without - * copying. + * Creates a {@code LiteralByteString} backed by the given array, without copying. * * @param bytes array to wrap */ LiteralByteString(byte[] bytes) { + if (bytes == null) { + throw new NullPointerException(); + } this.bytes = bytes; } @@ -1388,10 +1399,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Check equality of the substring of given length of this object starting at - * zero with another {@code LiteralByteString} substring starting at offset. + * Check equality of the substring of given length of this object starting at zero with another + * {@code LiteralByteString} substring starting at offset. * - * @param other what to compare a substring in + * @param other what to compare a substring in * @param offset offset into other * @param length number of bytes to compare * @return true for equality of substrings, else false. @@ -1411,10 +1422,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { byte[] thisBytes = bytes; byte[] otherBytes = lbsOther.bytes; int thisLimit = getOffsetIntoBytes() + length; - for ( - int thisIndex = getOffsetIntoBytes(), + for (int thisIndex = getOffsetIntoBytes(), otherIndex = lbsOther.getOffsetIntoBytes() + offset; - (thisIndex < thisLimit); ++thisIndex, ++otherIndex) { + (thisIndex < thisLimit); + ++thisIndex, ++otherIndex) { if (thisBytes[thisIndex] != otherBytes[otherIndex]) { return false; } @@ -1443,7 +1454,7 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { // We trust CodedInputStream not to modify the bytes, or to give anyone // else access to them. return CodedInputStream.newInstance( - bytes, getOffsetIntoBytes(), size(), true /* bufferIsImmutable */); + bytes, getOffsetIntoBytes(), size(), /* bufferIsImmutable= */ true); } // ================================================================= @@ -1460,14 +1471,12 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * This class is used to represent the substring of a {@link ByteString} over a - * single byte array. In terms of the public API of {@link ByteString}, you end - * up here by calling {@link ByteString#copyFrom(byte[])} followed by {@link - * ByteString#substring(int, int)}. + * This class is used to represent the substring of a {@link ByteString} over a single byte array. + * In terms of the public API of {@link ByteString}, you end up here by calling {@link + * ByteString#copyFrom(byte[])} followed by {@link ByteString#substring(int, int)}. * - * <p>This class contains most of the overhead involved in creating a substring - * from a {@link LiteralByteString}. The overhead involves some range-checking - * and two extra fields. + * <p>This class contains most of the overhead involved in creating a substring from a {@link + * LiteralByteString}. The overhead involves some range-checking and two extra fields. * * @author carlanton@google.com (Carl Haverl) */ @@ -1479,15 +1488,13 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { private final int bytesLength; /** - * Creates a {@code BoundedByteString} backed by the sub-range of given array, - * without copying. + * Creates a {@code BoundedByteString} backed by the sub-range of given array, without copying. * - * @param bytes array to wrap + * @param bytes array to wrap * @param offset index to first byte to use in bytes * @param length number of bytes to use from bytes - * @throws IllegalArgumentException if {@code offset < 0}, {@code length < 0}, - * or if {@code offset + length > - * bytes.length}. + * @throws IllegalArgumentException if {@code offset < 0}, {@code length < 0}, or if {@code + * offset + length > bytes.length}. */ BoundedByteString(byte[] bytes, int offset, int length) { super(bytes); @@ -1498,10 +1505,9 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { } /** - * Gets the byte at the given index. - * Throws {@link ArrayIndexOutOfBoundsException} - * for backwards-compatibility reasons although it would more properly be - * {@link IndexOutOfBoundsException}. + * Gets the byte at the given index. Throws {@link ArrayIndexOutOfBoundsException} for + * backwards-compatibility reasons although it would more properly be {@link + * IndexOutOfBoundsException}. * * @param index index of byte * @return the value @@ -1529,10 +1535,10 @@ public abstract class ByteString implements Iterable<Byte>, Serializable { // ByteString -> byte[] @Override - protected void copyToInternal(byte[] target, int sourceOffset, int targetOffset, - int numberToCopy) { - System.arraycopy(bytes, getOffsetIntoBytes() + sourceOffset, target, - targetOffset, numberToCopy); + protected void copyToInternal( + byte[] target, int sourceOffset, int targetOffset, int numberToCopy) { + System.arraycopy( + bytes, getOffsetIntoBytes() + sourceOffset, target, targetOffset, numberToCopy); } // ================================================================= |