ProtocolBufferInputStream (Revolution Systems Open Library TRUNK-SNAPSHOT API)

java.lang.Object
- com.revolsys.io.ProtocolBufferInputStream

```
public final class ProtocolBufferInputStream
extends Object
```
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

Constructor Summary

Constructors
Constructor and Description
`ProtocolBufferInputStream()`
`ProtocolBufferInputStream(byte[] buffer)`
`ProtocolBufferInputStream(byte[] buffer, int off, int len)`
`ProtocolBufferInputStream(InputStream input)`

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`void`	`endLengthDelimited(int limit)`
`int`	`getBytesUntilLimit()` Returns the number of bytes to be read before the current limit.
`int`	`getTotalBytesRead()` The total bytes read up to the current position.
`boolean`	`isAtEnd()` Returns true if the stream has reached the end of the input.
`static ProtocolBufferInputStream`	`newInstance(byte[] buf)` Create a new CodedInputStream wrapping the given byte array.
`static ProtocolBufferInputStream`	`newInstance(byte[] buf, int off, int len)` Create a new CodedInputStream wrapping the given byte array slice.
`static ProtocolBufferInputStream`	`newInstance(InputStream input)` Create a new CodedInputStream wrapping the given InputStream.
`void`	`popLimit(int limit)` Discards the current limit, returning to the previous limit.
`int`	`pushLimit(int byteLimit)` Sets `currentLimit` to (current position) + `byteLimit`.
`boolean`	`readBool()` Read a `bool` field value from the stream.
`void`	`readBool(Collection<Boolean> booleans)`
`void`	`readBools(Collection<Boolean> booleans)`
`byte[]`	`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.
`void`	`readEnum(Collection<Integer> enums)`
`void`	`readEnums(Collection<Integer> enums)`
`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.
`void`	`readInt(Collection<Integer> ints)`
`int`	`readInt32()` Read an `int32` field value from the stream.
`long`	`readInt64()` Read an `int64` field value from the stream.
`void`	`readInts(Collection<Integer> ints)`
`void`	`readLong(Collection<Long> longs)`
`void`	`readLongs(Collection<Long> longs)`
`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.
`static int`	`readRawVarint32(int firstByte, InputStream input)` Like `readRawVarint32(InputStream)`, but expects that the caller has already read one byte.
`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.
`String`	`readString()` Read a `string` field value from the stream.
`String`	`readString(String charsetName)`
`String`	`readStringUtf8()`
`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)`).
`void`	`setBuffer(byte[] buffer)`
`void`	`setBuffer(byte[] buffer, int offset, int length)`
`void`	`setInputStream(InputStream input)`
`int`	`setRecursionLimit(int limit)` Set the maximum message recursion depth.
`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.
`int`	`startLengthDelimited()`

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

- Constructor Detail
  - ProtocolBufferInputStream
```
public ProtocolBufferInputStream()
```
  - ProtocolBufferInputStream
```
public ProtocolBufferInputStream(byte[] buffer)
```
  - ProtocolBufferInputStream
```
public ProtocolBufferInputStream(byte[] buffer,
                         int off,
                         int len)
```
  - ProtocolBufferInputStream
```
public ProtocolBufferInputStream(InputStream input)
```
- Method Detail
  - 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.
  - newInstance
```
public static ProtocolBufferInputStream newInstance(byte[] buf)
```
    Create a new CodedInputStream wrapping the given byte array.
  - newInstance
```
public static ProtocolBufferInputStream newInstance(byte[] buf,
                                    int off,
                                    int len)
```
    Create a new CodedInputStream wrapping the given byte array slice.
  - newInstance
```
public static ProtocolBufferInputStream newInstance(InputStream input)
```
    Create a new CodedInputStream wrapping the given InputStream.
  - readRawVarint32
```
public static int readRawVarint32(int firstByte,
                  InputStream input)
                           throws IOException
```
    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.
    
    Throws:
    
    IOException
  - checkLastTagWas
```
public void checkLastTagWas(int value)
                     throws InvalidProtocolBufferException
```
    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:
    
    InvalidProtocolBufferException - value does not match the last tag.
  - endLengthDelimited
```
public void endLengthDelimited(int limit)
                        throws InvalidProtocolBufferException
```
    Throws:
    
    InvalidProtocolBufferException
  - getBytesUntilLimit
```
public int getBytesUntilLimit()
```
    Returns the number of bytes to be read before the current limit. If no limit is set, returns -1.
  - getTotalBytesRead
```
public int getTotalBytesRead()
```
    The total bytes read up to the current position. Calling resetSizeCounter() resets this value to zero.
  - isAtEnd
```
public boolean isAtEnd()
                throws 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:
    
    IOException
  - popLimit
```
public void popLimit(int limit)
```
    Discards the current limit, returning to the previous limit.
    
    Parameters:
    oldLimit - The old limit, as returned by pushLimit.
  - pushLimit
```
public int pushLimit(int byteLimit)
              throws InvalidProtocolBufferException
```
    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.
    
    Returns:
    the old limit.
    
    Throws:
    
    InvalidProtocolBufferException
  - readBool
```
public boolean readBool()
                 throws IOException
```
    Read a bool field value from the stream.
    
    Throws:
    
    IOException
  - readBool
```
public void readBool(Collection<Boolean> booleans)
              throws IOException
```
    Throws:
    
    IOException
  - readBools
```
public void readBools(Collection<Boolean> booleans)
               throws IOException
```
    Throws:
    
    IOException
  - readBytes
```
public byte[] readBytes()
                 throws IOException
```
    Read a bytes field value from the stream.
    
    Throws:
    
    IOException
  - readDouble
```
public double readDouble()
                  throws IOException
```
    Read a double field value from the stream.
    
    Throws:
    
    IOException
  - readEnum
```
public int readEnum()
             throws IOException
```
    Read an enum field value from the stream. Caller is responsible for converting the numeric value to an actual enum.
    
    Throws:
    
    IOException
  - readEnum
```
public void readEnum(Collection<Integer> enums)
              throws IOException
```
    Throws:
    
    IOException
  - readEnums
```
public void readEnums(Collection<Integer> enums)
               throws IOException
```
    Throws:
    
    IOException
  - readFixed32
```
public int readFixed32()
                throws IOException
```
    Read a fixed32 field value from the stream.
    
    Throws:
    
    IOException
  - readFixed64
```
public long readFixed64()
                 throws IOException
```
    Read a fixed64 field value from the stream.
    
    Throws:
    
    IOException
  - readFloat
```
public float readFloat()
                throws IOException
```
    Read a float field value from the stream.
    
    Throws:
    
    IOException
  - readInt
```
public void readInt(Collection<Integer> ints)
             throws IOException
```
    Throws:
    
    IOException
  - readInt32
```
public int readInt32()
              throws IOException
```
    Read an int32 field value from the stream.
    
    Throws:
    
    IOException
  - readInt64
```
public long readInt64()
               throws IOException
```
    Read an int64 field value from the stream.
    
    Throws:
    
    IOException
  - readInts
```
public void readInts(Collection<Integer> ints)
              throws IOException
```
    Throws:
    
    IOException
  - readLong
```
public void readLong(Collection<Long> longs)
              throws IOException
```
    Throws:
    
    IOException
  - readLongs
```
public void readLongs(Collection<Long> longs)
               throws IOException
```
    Throws:
    
    IOException
  - readRawByte
```
public byte readRawByte()
                 throws IOException
```
    Read one byte from the input.
    
    Throws:
    
    InvalidProtocolBufferException - The end of the stream or the current limit was reached.
    
    IOException
  - readRawBytes
```
public byte[] readRawBytes(int size)
                    throws IOException
```
    Read a fixed size of bytes from the input.
    
    Throws:
    
    InvalidProtocolBufferException - The end of the stream or the current limit was reached.
    
    IOException
  - readRawLittleEndian32
```
public int readRawLittleEndian32()
                          throws IOException
```
    Read a 32-bit little-endian integer from the stream.
    
    Throws:
    
    IOException
  - readRawLittleEndian64
```
public long readRawLittleEndian64()
                           throws IOException
```
    Read a 64-bit little-endian integer from the stream.
    
    Throws:
    
    IOException
  - readRawVarint32
```
public int readRawVarint32()
                    throws IOException
```
    Read a raw Varint from the stream. If larger than 32 bits, discard the upper bits.
    
    Throws:
    
    IOException
  - readRawVarint64
```
public long readRawVarint64()
                     throws IOException
```
    Read a raw Varint from the stream.
    
    Throws:
    
    IOException
  - readSFixed32
```
public int readSFixed32()
                 throws IOException
```
    Read an sfixed32 field value from the stream.
    
    Throws:
    
    IOException
  - readSFixed64
```
public long readSFixed64()
                  throws IOException
```
    Read an sfixed64 field value from the stream.
    
    Throws:
    
    IOException
  - readSInt32
```
public int readSInt32()
               throws IOException
```
    Read an sint32 field value from the stream.
    
    Throws:
    
    IOException
  - readSInt64
```
public long readSInt64()
                throws IOException
```
    Read an sint64 field value from the stream.
    
    Throws:
    
    IOException
  - readString
```
public String readString()
                  throws IOException
```
    Read a string field value from the stream.
    
    Throws:
    
    IOException
  - readString
```
public String readString(String charsetName)
                  throws IOException
```
    Throws:
    
    IOException
  - readStringUtf8
```
public String readStringUtf8()
                      throws IOException
```
    Throws:
    
    IOException
  - readTag
```
public int readTag()
            throws 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:
    
    IOException
  - readUInt32
```
public int readUInt32()
               throws IOException
```
    Read a uint32 field value from the stream.
    
    Throws:
    
    IOException
  - readUInt64
```
public long readUInt64()
                throws IOException
```
    Read a uint64 field value from the stream.
    
    Throws:
    
    IOException
  - resetSizeCounter
```
public void resetSizeCounter()
```
    Resets the current size counter to zero (see setSizeLimit(int)).
  - setBuffer
```
public void setBuffer(byte[] buffer)
```
  - setBuffer
```
public void setBuffer(byte[] buffer,
             int offset,
             int length)
```
  - setInputStream
```
public void setInputStream(InputStream input)
```
  - setRecursionLimit
```
public 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 64.
    
    Returns:
    the old limit.
  - setSizeLimit
```
public int setSizeLimit(int limit)
```
    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 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 (nor with ByteString.newCodedInput()).
    If you want to read several messages from a single CodedInputStream, you could call resetSizeCounter() after each one to avoid hitting the size limit.
    
    Returns:
    the old limit.
  - skipField
```
public boolean skipField(int tag)
                  throws 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:
    
    IOException
  - skipMessage
```
public void skipMessage()
                 throws IOException
```
    Reads and discards an entire message. This will read either until EOF or until an endgroup tag, whichever comes first.
    
    Throws:
    
    IOException
  - skipRawBytes
```
public void skipRawBytes(int size)
                  throws IOException
```
    Reads and discards size bytes.
    
    Throws:
    
    InvalidProtocolBufferException - The end of the stream or the current limit was reached.
    
    IOException
  - startLengthDelimited
```
public int startLengthDelimited()
                         throws IOException
```
    Throws:
    
    IOException

Class ProtocolBufferInputStream

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ProtocolBufferInputStream

ProtocolBufferInputStream

ProtocolBufferInputStream

ProtocolBufferInputStream

Method Detail

decodeZigZag32

decodeZigZag64

newInstance

newInstance

newInstance

readRawVarint32

checkLastTagWas

endLengthDelimited

getBytesUntilLimit

getTotalBytesRead

isAtEnd

popLimit

pushLimit

readBool

readBool

readBools

readBytes

readDouble

readEnum

readEnum

readEnums

readFixed32

readFixed64

readFloat

readInt

readInt32

readInt64

readInts

readLong

readLongs

readRawByte

readRawBytes

readRawLittleEndian32

readRawLittleEndian64

readRawVarint32

readRawVarint64

readSFixed32

readSFixed64

readSInt32

readSInt64

readString

readString

readStringUtf8

readTag

readUInt32

readUInt64

resetSizeCounter

setBuffer

setBuffer

setInputStream

setRecursionLimit

setSizeLimit

skipField

skipMessage

skipRawBytes

startLengthDelimited