com.dyuproject.protostuff
Class CodedInput

java.lang.Object
  com.dyuproject.protostuff.CodedInput

All Implemented Interfaces:

Input

public final class CodedInput
extends java.lang.Object
implements Input

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(int)). 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.

Author:

kenton@google.com Kenton Varda, David Yu

Field Summary

boolean

decodeNestedMessageAsGroup If true, the nested messages are group-encoded

Constructor Summary

CodedInput(byte[] buffer, int off, int len, boolean decodeNestedMessageAsGroup)

CodedInput(java.io.InputStream input, boolean decodeNestedMessageAsGroup)

CodedInput(java.io.InputStream input, byte[] buffer, boolean decodeNestedMessageAsGroup)

CodedInput(java.io.InputStream input, byte[] buffer, int offset, int limit, boolean decodeNestedMessageAsGroup)

Method Summary

void	checkLastTagWas(int value) Verifies that the last call to readTag() returned the given tag value.
static int	decodeZigZag32(int n) Decode a ZigZag-encoded 32-bit value.
static long	decodeZigZag64(long n) Decode a ZigZag-encoded 64-bit value.
int	getBytesUntilLimit() Returns the number of bytes to be read before the current limit.
int	getLastTag() Returns the last tag.
int	getTotalBytesRead() The total bytes read up to the current position.
<T> void	handleUnknownField(int fieldNumber, Schema<T> schema)
boolean	isAtEnd() Returns true if the stream has reached the end of the input.
<T> T	mergeObject(T value, Schema<T> schema)
static CodedInput	newInstance(byte[] buf) Create a new CodedInput wrapping the given byte array.
static CodedInput	newInstance(byte[] buf, int off, int len) Create a new CodedInput wrapping the given byte array slice.
static CodedInput	newInstance(java.io.InputStream input) Create a new CodedInput wrapping the given InputStream.
void	popLimit(int oldLimit) Discards the current limit, returning to the previous limit.
int	pushLimit(int byteLimit) Note that pushLimit() does NOT affect how many bytes the CodedInputStream reads from an underlying InputStream when refreshing its buffer.
boolean	readBool() Read a bool field value from the stream.
byte[]	readByteArray()
ByteString	readBytes() Read a bytes field value from the stream.
double	readDouble() Read a double field value from the stream.
int	readEnum() Read an enum field value from the stream.
<T> int	readFieldNumber(Schema<T> schema)
int	readFixed32() Read a fixed32 field value from the stream.
long	readFixed64() Read a fixed64 field value from the stream.
float	readFloat() Read a float field value from the stream.
int	readInt32() Read an int32 field value from the stream.
long	readInt64() Read an int64 field value from the stream.
byte	readRawByte() Read one byte from the input.
byte[]	readRawBytes(int size) Read a fixed size of bytes from the input.
int	readRawLittleEndian32() Read a 32-bit little-endian integer from the stream.
long	readRawLittleEndian64() Read a 64-bit little-endian integer from the stream.
int	readRawVarint32() Read a raw Varint from the stream.
long	readRawVarint64() Read a raw Varint from the stream.
int	readSFixed32() Read an sfixed32 field value from the stream.
long	readSFixed64() Read an sfixed64 field value from the stream.
int	readSInt32() Read an sint32 field value from the stream.
long	readSInt64() Read an sint64 field value from the stream.
java.lang.String	readString() Read a string field value from the stream.
int	readTag() Attempt to read a field tag, returning zero if we have reached EOF.
int	readUInt32() Read a uint32 field value from the stream.
long	readUInt64() Read a uint64 field value from the stream.
void	resetSizeCounter() Resets the current size counter to zero (see setSizeLimit(int)).
int	setSizeLimit(int limit) Set the maximum message size.
boolean	skipField(int tag) Reads and discards a single field, given its tag value.
void	skipMessage() Reads and discards an entire message.
void	skipRawBytes(int size) Reads and discards size bytes.
void	transferByteRangeTo(Output output, boolean utf8String, int fieldNumber, boolean repeated)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

decodeNestedMessageAsGroup

public final boolean decodeNestedMessageAsGroup

If true, the nested messages are group-encoded

Constructor Detail

CodedInput

public CodedInput(byte[] buffer,
                  int off,
                  int len,
                  boolean decodeNestedMessageAsGroup)

CodedInput

public CodedInput(java.io.InputStream input,
                  boolean decodeNestedMessageAsGroup)

CodedInput

public CodedInput(java.io.InputStream input,
                  byte[] buffer,
                  boolean decodeNestedMessageAsGroup)

CodedInput

public CodedInput(java.io.InputStream input,
                  byte[] buffer,
                  int offset,
                  int limit,
                  boolean decodeNestedMessageAsGroup)

Method Detail

newInstance

public static CodedInput newInstance(java.io.InputStream input)

Create a new CodedInput wrapping the given InputStream.

newInstance

public static CodedInput newInstance(byte[] buf)

Create a new CodedInput wrapping the given byte array.

newInstance

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

Create a new CodedInput wrapping the given byte array slice.

readTag

public int readTag()
            throws java.io.IOException

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.

Throws:

java.io.IOException

checkLastTagWas

public void checkLastTagWas(int value)
                     throws ProtobufException

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.

Throws:

ProtobufException - value does not match the last tag.

skipField

public boolean skipField(int tag)
                  throws java.io.IOException

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

Returns:

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

Throws:

java.io.IOException

skipMessage

public void skipMessage()
                 throws java.io.IOException

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

Throws:

java.io.IOException

readDouble

public double readDouble()
                  throws java.io.IOException

Read a double field value from the stream.

Specified by:

readDouble in interface Input

Throws:

java.io.IOException

readFloat

public float readFloat()
                throws java.io.IOException

Read a float field value from the stream.

Specified by:

readFloat in interface Input

Throws:

java.io.IOException

readUInt64

public long readUInt64()
                throws java.io.IOException

Read a uint64 field value from the stream.

Specified by:

readUInt64 in interface Input

Throws:

java.io.IOException

readInt64

public long readInt64()
               throws java.io.IOException

Read an int64 field value from the stream.

Specified by:

readInt64 in interface Input

Throws:

java.io.IOException

readInt32

public int readInt32()
              throws java.io.IOException

Read an int32 field value from the stream.

Specified by:

readInt32 in interface Input

Throws:

java.io.IOException

readFixed64

public long readFixed64()
                 throws java.io.IOException

Read a fixed64 field value from the stream.

Specified by:

readFixed64 in interface Input

Throws:

java.io.IOException

readFixed32

public int readFixed32()
                throws java.io.IOException

Read a fixed32 field value from the stream.

Specified by:

readFixed32 in interface Input

Throws:

java.io.IOException

readBool

public boolean readBool()
                 throws java.io.IOException

Read a bool field value from the stream.

Specified by:

readBool in interface Input

Throws:

java.io.IOException

readString

public java.lang.String readString()
                            throws java.io.IOException

Read a string field value from the stream.

Specified by:

readString in interface Input

Throws:

java.io.IOException

mergeObject

public <T> T mergeObject(T value,
                         Schema<T> schema)
              throws java.io.IOException

Specified by:

mergeObject in interface Input

Throws:

java.io.IOException

readBytes

public ByteString readBytes()
                     throws java.io.IOException

Read a bytes field value from the stream.

Specified by:

readBytes in interface Input

Throws:

java.io.IOException

readUInt32

public int readUInt32()
               throws java.io.IOException

Read a uint32 field value from the stream.

Specified by:

readUInt32 in interface Input

Throws:

java.io.IOException

readEnum

public int readEnum()
             throws java.io.IOException

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

Specified by:

readEnum in interface Input

Throws:

java.io.IOException

readSFixed32

public int readSFixed32()
                 throws java.io.IOException

Read an sfixed32 field value from the stream.

Specified by:

readSFixed32 in interface Input

Throws:

java.io.IOException

readSFixed64

public long readSFixed64()
                  throws java.io.IOException

Read an sfixed64 field value from the stream.

Specified by:

readSFixed64 in interface Input

Throws:

java.io.IOException

readSInt32

public int readSInt32()
               throws java.io.IOException

Read an sint32 field value from the stream.

Specified by:

readSInt32 in interface Input

Throws:

java.io.IOException

readSInt64

public long readSInt64()
                throws java.io.IOException

Read an sint64 field value from the stream.

Specified by:

readSInt64 in interface Input

Throws:

java.io.IOException

readRawVarint32

public int readRawVarint32()
                    throws java.io.IOException

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

Throws:

java.io.IOException

readRawVarint64

public long readRawVarint64()
                     throws java.io.IOException

Read a raw Varint from the stream.

Throws:

java.io.IOException

readRawLittleEndian32

public int readRawLittleEndian32()
                          throws java.io.IOException

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

Throws:

java.io.IOException

readRawLittleEndian64

public long readRawLittleEndian64()
                           throws java.io.IOException

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

Throws:

java.io.IOException

decodeZigZag32

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.)

Parameters:

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

Returns:

A signed 32-bit integer.

decodeZigZag64

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.)

Parameters:

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

Returns:

A signed 64-bit integer.

setSizeLimit

public int setSizeLimit(int limit)

Set the maximum message size. In order to prevent malicious messages from exhausting memory or causing integer overflows, CodedInput limits how large a message may be. The default limit is 64MB. 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 CodedInput, you could call resetSizeCounter() after each one to avoid hitting the size limit.

Returns:

the old limit.

resetSizeCounter

public void resetSizeCounter()

Resets the current size counter to zero (see setSizeLimit(int)). The field totalBytesRetired will be negative if the initial position was not zero.

pushLimit

public int pushLimit(int byteLimit)
              throws ProtobufException

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.

Returns:

the old limit.

Throws:

ProtobufException

popLimit

public void popLimit(int oldLimit)

Discards the current limit, returning to the previous limit.

Parameters:

oldLimit - The old limit, as returned by pushLimit.

getBytesUntilLimit

public int getBytesUntilLimit()

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

isAtEnd

public boolean isAtEnd()
                throws java.io.IOException

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).

Throws:

java.io.IOException

getTotalBytesRead

public int getTotalBytesRead()

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

readRawByte

public byte readRawByte()
                 throws java.io.IOException

Read one byte from the input.

Throws:

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

java.io.IOException

readRawBytes

public byte[] readRawBytes(int size)
                    throws java.io.IOException

Read a fixed size of bytes from the input.

Throws:

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

java.io.IOException

skipRawBytes

public void skipRawBytes(int size)
                  throws java.io.IOException

Reads and discards size bytes.

Throws:

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

java.io.IOException

readFieldNumber

public <T> int readFieldNumber(Schema<T> schema)
                    throws java.io.IOException

Specified by:

readFieldNumber in interface Input

Throws:

java.io.IOException

readByteArray

public byte[] readByteArray()
                     throws java.io.IOException

Specified by:

readByteArray in interface Input

Throws:

java.io.IOException

handleUnknownField

public <T> void handleUnknownField(int fieldNumber,
                                   Schema<T> schema)
                        throws java.io.IOException

Specified by:

handleUnknownField in interface Input

Throws:

java.io.IOException

transferByteRangeTo

public void transferByteRangeTo(Output output,
                                boolean utf8String,
                                int fieldNumber,
                                boolean repeated)
                         throws java.io.IOException

Specified by:

transferByteRangeTo in interface Input

Throws:

java.io.IOException

getLastTag

public int getLastTag()

Returns the last tag.