Class CodedInputStream

public abstract class CodedInputStream

Reads and decodes protocol message fields.

This class contains two kinds of methods: methods that read specific protocol message constructs and field types (e.g. #readTag() and #readInt32()) and methods that read low-level values (e.g. #readRawVarint32() and #readRawBytes). If you are reading encoded protocol messages, you should use the former methods, but if you are reading some other format of your own design, use the latter.

Inheritance

java.lang.Object > CodedInputStream

Methods

<T>readGroup(int fieldNumber, Parser<T> parser, ExtensionRegistryLite extensionRegistry)

public abstract T <T>readGroup(int fieldNumber, Parser<T> parser, ExtensionRegistryLite extensionRegistry)

Read a group field value from the stream.

Parameters
NameDescription
fieldNumberint
parserParser<T>
extensionRegistryExtensionRegistryLite
Returns
TypeDescription
T
Exceptions
TypeDescription
IOException

<T>readMessage(Parser<T> parser, ExtensionRegistryLite extensionRegistry)

public abstract T <T>readMessage(Parser<T> parser, ExtensionRegistryLite extensionRegistry)

Read an embedded message field value from the stream.

Parameters
NameDescription
parserParser<T>
extensionRegistryExtensionRegistryLite
Returns
TypeDescription
T
Exceptions
TypeDescription
IOException

checkLastTagWas(int value)

public abstract void checkLastTagWas(int value)

Verifies that the last call to readTag() returned the given tag value. This is used to verify that a nested group ended with the correct end tag.

Parameter
NameDescription
valueint
Exceptions
TypeDescription
InvalidProtocolBufferException

value does not match the last tag.

checkRecursionLimit()

public void checkRecursionLimit()
Exceptions
TypeDescription
InvalidProtocolBufferException

decodeZigZag32(int n)

public static int decodeZigZag32(int n)

Decode a ZigZag-encoded 32-bit value. ZigZag encodes signed integers into values that can be efficiently encoded with varint. (Otherwise, negative values must be sign-extended to 64 bits to be varint encoded, thus always taking 10 bytes on the wire.)

Parameter
NameDescription
nint

An unsigned 32-bit integer, stored in a signed int because Java has no explicit unsigned support.

Returns
TypeDescription
int

A signed 32-bit integer.

decodeZigZag64(long n)

public static long decodeZigZag64(long n)

Decode a ZigZag-encoded 64-bit value. ZigZag encodes signed integers into values that can be efficiently encoded with varint. (Otherwise, negative values must be sign-extended to 64 bits to be varint encoded, thus always taking 10 bytes on the wire.)

Parameter
NameDescription
nlong

An unsigned 64-bit integer, stored in a signed int because Java has no explicit unsigned support.

Returns
TypeDescription
long

A signed 64-bit integer.

enableAliasing(boolean enabled)

public abstract void enableAliasing(boolean enabled)

Enables ByteString aliasing of the underlying buffer, trading off on buffer pinning for data copies. Only valid for buffer-backed streams.

Parameter
NameDescription
enabledboolean

getBytesUntilLimit()

public abstract int getBytesUntilLimit()

Returns the number of bytes to be read before the current limit. If no limit is set, returns -1.

Returns
TypeDescription
int

getLastTag()

public abstract int getLastTag()
Returns
TypeDescription
int

getTotalBytesRead()

public abstract int getTotalBytesRead()

The total bytes read up to the current position. Calling #resetSizeCounter() resets this value to zero.

Returns
TypeDescription
int

isAtEnd()

public abstract boolean isAtEnd()

Returns true if the stream has reached the end of the input. This is the case if either the end of the underlying input source has been reached or if the stream has reached a limit created using #pushLimit(int). This function may get blocked when using StreamDecoder as it invokes StreamDecoder#tryRefillBuffer(int) in this function which will try to read bytes from input.

Returns
TypeDescription
boolean
Exceptions
TypeDescription
IOException

newInstance(byte[] buf)

public static CodedInputStream newInstance(byte[] buf)

Create a new CodedInputStream wrapping the given byte array.

Parameter
NameDescription
bufbyte[]
Returns
TypeDescription
CodedInputStream

newInstance(byte[] buf, int off, int len)

public static CodedInputStream newInstance(byte[] buf, int off, int len)

Create a new CodedInputStream wrapping the given byte array slice.

Parameters
NameDescription
bufbyte[]
offint
lenint
Returns
TypeDescription
CodedInputStream

newInstance(InputStream input)

public static CodedInputStream newInstance(InputStream input)

Create a new CodedInputStream wrapping the given InputStream.

Parameter
NameDescription
inputInputStream
Returns
TypeDescription
CodedInputStream

newInstance(InputStream input, int bufferSize)

public static CodedInputStream newInstance(InputStream input, int bufferSize)

Create a new CodedInputStream wrapping the given InputStream, with a specified buffer size.

Parameters
NameDescription
inputInputStream
bufferSizeint
Returns
TypeDescription
CodedInputStream

newInstance(Iterable<ByteBuffer> input)

public static CodedInputStream newInstance(Iterable<ByteBuffer> input)

Create a new CodedInputStream wrapping the given Iterable .

Parameter
NameDescription
inputIterable<ByteBuffer>
Returns
TypeDescription
CodedInputStream

newInstance(ByteBuffer buf)

public static CodedInputStream newInstance(ByteBuffer buf)

Create a new CodedInputStream wrapping the given ByteBuffer. The data starting from the ByteBuffer's current position to its limit will be read. The returned CodedInputStream may or may not share the underlying data in the ByteBuffer, therefore the ByteBuffer cannot be changed while the CodedInputStream is in use. Note that the ByteBuffer's position won't be changed by this function. Concurrent calls with the same ByteBuffer object are safe if no other thread is trying to alter the ByteBuffer's status.

Parameter
NameDescription
bufByteBuffer
Returns
TypeDescription
CodedInputStream

popLimit(int oldLimit)

public abstract void popLimit(int oldLimit)

Discards the current limit, returning to the previous limit.

Parameter
NameDescription
oldLimitint

The old limit, as returned by pushLimit.

pushLimit(int byteLimit)

public abstract int pushLimit(int byteLimit)

Sets currentLimit to (current position) + byteLimit. This is called when descending into a length-delimited embedded message.

Note that pushLimit() does NOT affect how many bytes the CodedInputStream reads from an underlying InputStream when refreshing its buffer. If you need to prevent reading past a certain point in the underlying InputStream (e.g. because you expect it to contain more data after the end of the message which you need to handle differently) then you must place a wrapper around your InputStream which limits the amount of data that can be read from it.

Parameter
NameDescription
byteLimitint
Returns
TypeDescription
int

the old limit.

Exceptions
TypeDescription
InvalidProtocolBufferException

readBool()

public abstract boolean readBool()

Read a bool field value from the stream.

Returns
TypeDescription
boolean
Exceptions
TypeDescription
IOException

readByteArray()

public abstract byte[] readByteArray()

Read a bytes field value from the stream.

Returns
TypeDescription
byte[]
Exceptions
TypeDescription
IOException

readByteBuffer()

public abstract ByteBuffer readByteBuffer()

Read a bytes field value from the stream.

Returns
TypeDescription
ByteBuffer
Exceptions
TypeDescription
IOException

readBytes()

public abstract ByteString readBytes()

Read a bytes field value from the stream.

Returns
TypeDescription
ByteString
Exceptions
TypeDescription
IOException

readDouble()

public abstract double readDouble()

Read a double field value from the stream.

Returns
TypeDescription
double
Exceptions
TypeDescription
IOException

readEnum()

public abstract int readEnum()

Read an enum field value from the stream. Caller is responsible for converting the numeric value to an actual enum.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readFixed32()

public abstract int readFixed32()

Read a fixed32 field value from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readFixed64()

public abstract long readFixed64()

Read a fixed64 field value from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readFloat()

public abstract float readFloat()

Read a float field value from the stream.

Returns
TypeDescription
float
Exceptions
TypeDescription
IOException

readGroup(int fieldNumber, MessageLite.Builder builder, ExtensionRegistryLite extensionRegistry)

public abstract void readGroup(int fieldNumber, MessageLite.Builder builder, ExtensionRegistryLite extensionRegistry)

Read a group field value from the stream.

Parameters
NameDescription
fieldNumberint
builderMessageLite.Builder
extensionRegistryExtensionRegistryLite
Exceptions
TypeDescription
IOException

readInt32()

public abstract int readInt32()

Read an int32 field value from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readInt64()

public abstract long readInt64()

Read an int64 field value from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readMessage(MessageLite.Builder builder, ExtensionRegistryLite extensionRegistry)

public abstract void readMessage(MessageLite.Builder builder, ExtensionRegistryLite extensionRegistry)

Read an embedded message field value from the stream.

Parameters
NameDescription
builderMessageLite.Builder
extensionRegistryExtensionRegistryLite
Exceptions
TypeDescription
IOException

readRawByte()

public abstract byte readRawByte()

Read one byte from the input.

Returns
TypeDescription
byte
Exceptions
TypeDescription
IOException

The end of the stream or the current limit was reached.

readRawBytes(int size)

public abstract byte[] readRawBytes(int size)

Read a fixed size of bytes from the input.

Parameter
NameDescription
sizeint
Returns
TypeDescription
byte[]
Exceptions
TypeDescription
IOException

The end of the stream or the current limit was reached.

readRawLittleEndian32()

public abstract int readRawLittleEndian32()

Read a 32-bit little-endian integer from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readRawLittleEndian64()

public abstract long readRawLittleEndian64()

Read a 64-bit little-endian integer from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readRawVarint32()

public abstract int readRawVarint32()

Read a raw Varint from the stream. If larger than 32 bits, discard the upper bits.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readRawVarint32(int firstByte, InputStream input)

public static int readRawVarint32(int firstByte, InputStream input)

Like #readRawVarint32(InputStream), but expects that the caller has already read one byte. This allows the caller to determine if EOF has been reached before attempting to read.

Parameters
NameDescription
firstByteint
inputInputStream
Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readRawVarint64()

public abstract long readRawVarint64()

Read a raw Varint from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readSFixed32()

public abstract int readSFixed32()

Read an sfixed32 field value from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readSFixed64()

public abstract long readSFixed64()

Read an sfixed64 field value from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readSInt32()

public abstract int readSInt32()

Read an sint32 field value from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readSInt64()

public abstract long readSInt64()

Read an sint64 field value from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readString()

public abstract String readString()

Read a string field value from the stream. If the stream contains malformed UTF-8, replace the offending bytes with the standard UTF-8 replacement character.

Returns
TypeDescription
String
Exceptions
TypeDescription
IOException

readStringRequireUtf8()

public abstract String readStringRequireUtf8()

Read a string field value from the stream. If the stream contains malformed UTF-8, throw exception InvalidProtocolBufferException.

Returns
TypeDescription
String
Exceptions
TypeDescription
IOException

readTag()

public abstract int readTag()

Attempt to read a field tag, returning zero if we have reached EOF. Protocol message parsers use this to read tags, since a protocol message may legally end wherever a tag occurs, and zero is not a valid tag number.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readUInt32()

public abstract int readUInt32()

Read a uint32 field value from the stream.

Returns
TypeDescription
int
Exceptions
TypeDescription
IOException

readUInt64()

public abstract long readUInt64()

Read a uint64 field value from the stream.

Returns
TypeDescription
long
Exceptions
TypeDescription
IOException

readUnknownGroup(int fieldNumber, MessageLite.Builder builder) (deprecated)

public abstract void readUnknownGroup(int fieldNumber, MessageLite.Builder builder)

(deprecated) UnknownFieldSet.Builder now implements MessageLite.Builder, so you can just call #readGroup.

Reads a group field value from the stream and merges it into the given UnknownFieldSet.

Parameters
NameDescription
fieldNumberint
builderMessageLite.Builder
Exceptions
TypeDescription
IOException

resetSizeCounter()

public abstract void resetSizeCounter()

Resets the current size counter to zero (see #setSizeLimit(int)). Only valid for InputStream-backed streams.

setRecursionLimit(int limit)

public final int setRecursionLimit(int limit)

Set the maximum message recursion depth. In order to prevent malicious messages from causing stack overflows, CodedInputStream limits how deeply messages may be nested. The default limit is 100.

Parameter
NameDescription
limitint
Returns
TypeDescription
int

the old limit.

setSizeLimit(int limit)

public final int setSizeLimit(int limit)

Only valid for InputStream-backed streams.

Set the maximum message size. In order to prevent malicious messages from exhausting memory or causing integer overflows, CodedInputStream limits how large a message may be. The default limit is Integer.MAX_INT. You should set this limit as small as you can without harming your app's functionality. Note that size limits only apply when reading from an InputStream, not when constructed around a raw byte array.

If you want to read several messages from a single CodedInputStream, you could call #resetSizeCounter() after each one to avoid hitting the size limit.

Parameter
NameDescription
limitint
Returns
TypeDescription
int

the old limit.

skipField(int tag)

public abstract boolean skipField(int tag)

Reads and discards a single field, given its tag value.

Parameter
NameDescription
tagint
Returns
TypeDescription
boolean

false if the tag is an endgroup tag, in which case nothing is skipped. Otherwise, returns true.

Exceptions
TypeDescription
IOException

skipField(int tag, CodedOutputStream output) (deprecated)

public abstract boolean skipField(int tag, CodedOutputStream output)

(deprecated) use UnknownFieldSet or UnknownFieldSetLite to skip to an output stream.

Reads a single field and writes it to output in wire format, given its tag value.

Parameters
NameDescription
tagint
outputCodedOutputStream
Returns
TypeDescription
boolean

false if the tag is an endgroup tag, in which case nothing is skipped. Otherwise, returns true.

Exceptions
TypeDescription
IOException

skipMessage()

public abstract void skipMessage()

Reads and discards an entire message. This will read either until EOF or until an endgroup tag, whichever comes first.

Exceptions
TypeDescription
IOException

skipMessage(CodedOutputStream output)

public abstract void skipMessage(CodedOutputStream output)

Reads an entire message and writes it to output in wire format. This will read either until EOF or until an endgroup tag, whichever comes first.

Parameter
NameDescription
outputCodedOutputStream
Exceptions
TypeDescription
IOException

skipRawBytes(int size)

public abstract void skipRawBytes(int size)

Reads and discards size bytes.

Parameter
NameDescription
sizeint
Exceptions
TypeDescription
IOException

The end of the stream or the current limit was reached.