com.google.protobuf
Class CodedOutputStream

java.lang.Object
  com.google.protobuf.CodedOutputStream

public final class CodedOutputStream
extends java.lang.Object

Encodes and writes protocol message fields.

This class contains two kinds of methods: methods that write specific protocol message constructs and field types (e.g. writeTag(int, int) and writeInt32(int, int)) and methods that write low-level values (e.g. writeRawVarint32(int) and writeRawBytes(byte[])). If you are writing encoded protocol messages, you should use the former methods, but if you are writing some other format of your own design, use the latter.

This class is totally unsynchronized.

Author:

[email protected] Kenton Varda

Nested Class Summary

static class

CodedOutputStream.OutOfSpaceException If you create a CodedOutputStream around a simple flat array, you must not attempt to write more bytes than the array has space.

Field Summary

static int	DEFAULT_BUFFER_SIZE The buffer size used in newInstance(java.io.OutputStream).
static int	LITTLE_ENDIAN_32_SIZE
static int	LITTLE_ENDIAN_64_SIZE

Method Summary

void	checkNoSpaceLeft() Verifies that spaceLeft() returns zero.
static int	computeBoolSize(int fieldNumber, boolean value) Compute the number of bytes that would be needed to encode a bool field, including tag.
static int	computeBytesSize(int fieldNumber, ByteString value) Compute the number of bytes that would be needed to encode a bytes field, including tag.
static int	computeDoubleSize(int fieldNumber, double value) Compute the number of bytes that would be needed to encode a double field, including tag.
static int	computeEnumSize(int fieldNumber, int value) Compute the number of bytes that would be needed to encode an enum field, including tag.
static int	computeFieldSize(Descriptors.FieldDescriptor.Type type, int number, java.lang.Object value) Compute the number of bytes that would be needed to encode a field of arbitrary type, including tag, to the stream.
static int	computeFixed32Size(int fieldNumber, int value) Compute the number of bytes that would be needed to encode a fixed32 field, including tag.
static int	computeFixed64Size(int fieldNumber, long value) Compute the number of bytes that would be needed to encode a fixed64 field, including tag.
static int	computeFloatSize(int fieldNumber, float value) Compute the number of bytes that would be needed to encode a float field, including tag.
static int	computeGroupSize(int fieldNumber, Message value) Compute the number of bytes that would be needed to encode a group field, including tag.
static int	computeInt32Size(int fieldNumber, int value) Compute the number of bytes that would be needed to encode an int32 field, including tag.
static int	computeInt64Size(int fieldNumber, long value) Compute the number of bytes that would be needed to encode an int64 field, including tag.
static int	computeMessageSetExtensionSize(int fieldNumber, Message value) Compute the number of bytes that would be needed to encode a MessageSet extension to the stream.
static int	computeMessageSize(int fieldNumber, Message value) Compute the number of bytes that would be needed to encode an embedded message field, including tag.
static int	computeRawMessageSetExtensionSize(int fieldNumber, ByteString value) Compute the number of bytes that would be needed to encode an unparsed MessageSet extension field to the stream.
static int	computeRawVarint32Size(int value) Compute the number of bytes that would be needed to encode a varint.
static int	computeRawVarint64Size(long value) Compute the number of bytes that would be needed to encode a varint.
static int	computeSFixed32Size(int fieldNumber, int value) Compute the number of bytes that would be needed to encode an sfixed32 field, including tag.
static int	computeSFixed64Size(int fieldNumber, long value) Compute the number of bytes that would be needed to encode an sfixed64 field, including tag.
static int	computeSInt32Size(int fieldNumber, int value) Compute the number of bytes that would be needed to encode an sint32 field, including tag.
static int	computeSInt64Size(int fieldNumber, long value) Compute the number of bytes that would be needed to encode an sint64 field, including tag.
static int	computeStringSize(int fieldNumber, java.lang.String value) Compute the number of bytes that would be needed to encode a string field, including tag.
static int	computeTagSize(int fieldNumber) Compute the number of bytes that would be needed to encode a tag.
static int	computeUInt32Size(int fieldNumber, int value) Compute the number of bytes that would be needed to encode a uint32 field, including tag.
static int	computeUInt64Size(int fieldNumber, long value) Compute the number of bytes that would be needed to encode a uint64 field, including tag.
static int	computeUnknownGroupSize(int fieldNumber, UnknownFieldSet value) Compute the number of bytes that would be needed to encode a group field represented by an UnknownFieldSet, including tag.
static int	encodeZigZag32(int n) Encode a ZigZag-encoded 32-bit value.
static long	encodeZigZag64(long n) Encode a ZigZag-encoded 64-bit value.
void	flush() Flushes the stream and forces any buffered bytes to be written.
static CodedOutputStream	newInstance(byte[] flatArray) Create a new CodedOutputStream that writes directly to the given byte array.
static CodedOutputStream	newInstance(byte[] flatArray, int offset, int length) Create a new CodedOutputStream that writes directly to the given byte array slice.
static CodedOutputStream	newInstance(java.io.OutputStream output) Create a new CodedOutputStream wrapping the given OutputStream.
static CodedOutputStream	newInstance(java.io.OutputStream output, int bufferSize) Create a new CodedOutputStream wrapping the given OutputStream with a given buffer size.
int	spaceLeft() If writing to a flat array, return the space left in the array.
void	writeBool(int fieldNumber, boolean value) Write a bool field, including tag, to the stream.
void	writeBytes(int fieldNumber, ByteString value) Write a bytes field, including tag, to the stream.
void	writeDouble(int fieldNumber, double value) Write a double field, including tag, to the stream.
void	writeEnum(int fieldNumber, int value) Write an enum field, including tag, to the stream.
void	writeField(Descriptors.FieldDescriptor.Type type, int number, java.lang.Object value) Write a field of arbitrary type, including tag, to the stream.
void	writeFixed32(int fieldNumber, int value) Write a fixed32 field, including tag, to the stream.
void	writeFixed64(int fieldNumber, long value) Write a fixed64 field, including tag, to the stream.
void	writeFloat(int fieldNumber, float value) Write a float field, including tag, to the stream.
void	writeGroup(int fieldNumber, Message value) Write a group field, including tag, to the stream.
void	writeInt32(int fieldNumber, int value) Write an int32 field, including tag, to the stream.
void	writeInt64(int fieldNumber, long value) Write an int64 field, including tag, to the stream.
void	writeMessage(int fieldNumber, Message value) Write an embedded message field, including tag, to the stream.
void	writeMessageSetExtension(int fieldNumber, Message value) Write a MessageSet extension field to the stream.
void	writeRawByte(byte value) Write a single byte.
void	writeRawByte(int value) Write a single byte, represented by an integer value.
void	writeRawBytes(byte[] value) Write an array of bytes.
void	writeRawBytes(byte[] value, int offset, int length) Write part of an array of bytes.
void	writeRawLittleEndian32(int value) Write a little-endian 32-bit integer.
void	writeRawLittleEndian64(long value) Write a little-endian 64-bit integer.
void	writeRawMessageSetExtension(int fieldNumber, ByteString value) Write an unparsed MessageSet extension field to the stream.
void	writeRawVarint32(int value) Encode and write a varint.
void	writeRawVarint64(long value) Encode and write a varint.
void	writeSFixed32(int fieldNumber, int value) Write an sfixed32 field, including tag, to the stream.
void	writeSFixed64(int fieldNumber, long value) Write an sfixed64 field, including tag, to the stream.
void	writeSInt32(int fieldNumber, int value) Write an sint32 field, including tag, to the stream.
void	writeSInt64(int fieldNumber, long value) Write an sint64 field, including tag, to the stream.
void	writeString(int fieldNumber, java.lang.String value) Write a string field, including tag, to the stream.
void	writeTag(int fieldNumber, int wireType) Encode and write a tag.
void	writeUInt32(int fieldNumber, int value) Write a uint32 field, including tag, to the stream.
void	writeUInt64(int fieldNumber, long value) Write a uint64 field, including tag, to the stream.
void	writeUnknownGroup(int fieldNumber, UnknownFieldSet value) Write a group represented by an UnknownFieldSet.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The buffer size used in newInstance(java.io.OutputStream).

See Also:

Constant Field Values

LITTLE_ENDIAN_32_SIZE

public static final int LITTLE_ENDIAN_32_SIZE

See Also:

Constant Field Values

LITTLE_ENDIAN_64_SIZE

public static final int LITTLE_ENDIAN_64_SIZE

See Also:

Constant Field Values

Method Detail

newInstance

public static CodedOutputStream newInstance(java.io.OutputStream output)

Create a new CodedOutputStream wrapping the given OutputStream.

newInstance

public static CodedOutputStream newInstance(java.io.OutputStream output,
                                            int bufferSize)

Create a new CodedOutputStream wrapping the given OutputStream with a given buffer size.

newInstance

public static CodedOutputStream newInstance(byte[] flatArray)

Create a new CodedOutputStream that writes directly to the given byte array. If more bytes are written than fit in the array, CodedOutputStream.OutOfSpaceException will be thrown. Writing directly to a flat array is faster than writing to an OutputStream. See also ByteString.newCodedBuilder(int).

newInstance

public static CodedOutputStream newInstance(byte[] flatArray,
                                            int offset,
                                            int length)

Create a new CodedOutputStream that writes directly to the given byte array slice. If more bytes are written than fit in the slice, CodedOutputStream.OutOfSpaceException will be thrown. Writing directly to a flat array is faster than writing to an OutputStream. See also ByteString.newCodedBuilder(int).

writeDouble

public void writeDouble(int fieldNumber,
                        double value)
                 throws java.io.IOException

Write a double field, including tag, to the stream.

Throws:

java.io.IOException

writeFloat

public void writeFloat(int fieldNumber,
                       float value)
                throws java.io.IOException

Write a float field, including tag, to the stream.

Throws:

java.io.IOException

writeUInt64

public void writeUInt64(int fieldNumber,
                        long value)
                 throws java.io.IOException

Write a uint64 field, including tag, to the stream.

Throws:

java.io.IOException

writeInt64

public void writeInt64(int fieldNumber,
                       long value)
                throws java.io.IOException

Write an int64 field, including tag, to the stream.

Throws:

java.io.IOException

writeInt32

public void writeInt32(int fieldNumber,
                       int value)
                throws java.io.IOException

Write an int32 field, including tag, to the stream.

Throws:

java.io.IOException

writeFixed64

public void writeFixed64(int fieldNumber,
                         long value)
                  throws java.io.IOException

Write a fixed64 field, including tag, to the stream.

Throws:

java.io.IOException

writeFixed32

public void writeFixed32(int fieldNumber,
                         int value)
                  throws java.io.IOException

Write a fixed32 field, including tag, to the stream.

Throws:

java.io.IOException

writeBool

public void writeBool(int fieldNumber,
                      boolean value)
               throws java.io.IOException

Write a bool field, including tag, to the stream.

Throws:

java.io.IOException

writeString

public void writeString(int fieldNumber,
                        java.lang.String value)
                 throws java.io.IOException

Write a string field, including tag, to the stream.

Throws:

java.io.IOException

writeGroup

public void writeGroup(int fieldNumber,
                       Message value)
                throws java.io.IOException

Write a group field, including tag, to the stream.

Throws:

java.io.IOException

writeUnknownGroup

public void writeUnknownGroup(int fieldNumber,
                              UnknownFieldSet value)
                       throws java.io.IOException

Write a group represented by an UnknownFieldSet.

Throws:

java.io.IOException

writeMessage

public void writeMessage(int fieldNumber,
                         Message value)
                  throws java.io.IOException

Write an embedded message field, including tag, to the stream.

Throws:

java.io.IOException

writeBytes

public void writeBytes(int fieldNumber,
                       ByteString value)
                throws java.io.IOException

Write a bytes field, including tag, to the stream.

Throws:

java.io.IOException

writeUInt32

public void writeUInt32(int fieldNumber,
                        int value)
                 throws java.io.IOException

Write a uint32 field, including tag, to the stream.

Throws:

java.io.IOException

writeEnum

public void writeEnum(int fieldNumber,
                      int value)
               throws java.io.IOException

Write an enum field, including tag, to the stream. Caller is responsible for converting the enum value to its numeric value.

Throws:

java.io.IOException

writeSFixed32

public void writeSFixed32(int fieldNumber,
                          int value)
                   throws java.io.IOException

Write an sfixed32 field, including tag, to the stream.

Throws:

java.io.IOException

writeSFixed64

public void writeSFixed64(int fieldNumber,
                          long value)
                   throws java.io.IOException

Write an sfixed64 field, including tag, to the stream.

Throws:

java.io.IOException

writeSInt32

public void writeSInt32(int fieldNumber,
                        int value)
                 throws java.io.IOException

Write an sint32 field, including tag, to the stream.

Throws:

java.io.IOException

writeSInt64

public void writeSInt64(int fieldNumber,
                        long value)
                 throws java.io.IOException

Write an sint64 field, including tag, to the stream.

Throws:

java.io.IOException

writeMessageSetExtension

public void writeMessageSetExtension(int fieldNumber,
                                     Message value)
                              throws java.io.IOException

Write a MessageSet extension field to the stream. For historical reasons, the wire format differs from normal fields.

Throws:

java.io.IOException

writeRawMessageSetExtension

public void writeRawMessageSetExtension(int fieldNumber,
                                        ByteString value)
                                 throws java.io.IOException

Write an unparsed MessageSet extension field to the stream. For historical reasons, the wire format differs from normal fields.

Throws:

java.io.IOException

writeField

public void writeField(Descriptors.FieldDescriptor.Type type,
                       int number,
                       java.lang.Object value)
                throws java.io.IOException

Write a field of arbitrary type, including tag, to the stream.

Parameters:

type - The field's type.

number - The field's number.

value - Object representing the field's value. Must be of the exact type which would be returned by Message.getField(Descriptors.FieldDescriptor) for this field.

Throws:

java.io.IOException

computeDoubleSize

public static int computeDoubleSize(int fieldNumber,
                                    double value)

Compute the number of bytes that would be needed to encode a double field, including tag.

computeFloatSize

public static int computeFloatSize(int fieldNumber,
                                   float value)

Compute the number of bytes that would be needed to encode a float field, including tag.

computeUInt64Size

public static int computeUInt64Size(int fieldNumber,
                                    long value)

Compute the number of bytes that would be needed to encode a uint64 field, including tag.

computeInt64Size

public static int computeInt64Size(int fieldNumber,
                                   long value)

Compute the number of bytes that would be needed to encode an int64 field, including tag.

computeInt32Size

public static int computeInt32Size(int fieldNumber,
                                   int value)

Compute the number of bytes that would be needed to encode an int32 field, including tag.

computeFixed64Size

public static int computeFixed64Size(int fieldNumber,
                                     long value)

Compute the number of bytes that would be needed to encode a fixed64 field, including tag.

computeFixed32Size

public static int computeFixed32Size(int fieldNumber,
                                     int value)

Compute the number of bytes that would be needed to encode a fixed32 field, including tag.

computeBoolSize

public static int computeBoolSize(int fieldNumber,
                                  boolean value)

Compute the number of bytes that would be needed to encode a bool field, including tag.

computeStringSize

public static int computeStringSize(int fieldNumber,
                                    java.lang.String value)

Compute the number of bytes that would be needed to encode a string field, including tag.

computeGroupSize

public static int computeGroupSize(int fieldNumber,
                                   Message value)

Compute the number of bytes that would be needed to encode a group field, including tag.

computeUnknownGroupSize

public static int computeUnknownGroupSize(int fieldNumber,
                                          UnknownFieldSet value)

Compute the number of bytes that would be needed to encode a group field represented by an UnknownFieldSet, including tag.

computeMessageSize

public static int computeMessageSize(int fieldNumber,
                                     Message value)

Compute the number of bytes that would be needed to encode an embedded message field, including tag.

computeBytesSize

public static int computeBytesSize(int fieldNumber,
                                   ByteString value)

Compute the number of bytes that would be needed to encode a bytes field, including tag.

computeUInt32Size

public static int computeUInt32Size(int fieldNumber,
                                    int value)

Compute the number of bytes that would be needed to encode a uint32 field, including tag.

computeEnumSize

public static int computeEnumSize(int fieldNumber,
                                  int value)

Compute the number of bytes that would be needed to encode an enum field, including tag. Caller is responsible for converting the enum value to its numeric value.

computeSFixed32Size

public static int computeSFixed32Size(int fieldNumber,
                                      int value)

Compute the number of bytes that would be needed to encode an sfixed32 field, including tag.

computeSFixed64Size

public static int computeSFixed64Size(int fieldNumber,
                                      long value)

Compute the number of bytes that would be needed to encode an sfixed64 field, including tag.

computeSInt32Size

public static int computeSInt32Size(int fieldNumber,
                                    int value)

Compute the number of bytes that would be needed to encode an sint32 field, including tag.

computeSInt64Size

public static int computeSInt64Size(int fieldNumber,
                                    long value)

Compute the number of bytes that would be needed to encode an sint64 field, including tag.

computeMessageSetExtensionSize

public static int computeMessageSetExtensionSize(int fieldNumber,
                                                 Message value)

Compute the number of bytes that would be needed to encode a MessageSet extension to the stream. For historical reasons, the wire format differs from normal fields.

computeRawMessageSetExtensionSize

public static int computeRawMessageSetExtensionSize(int fieldNumber,
                                                    ByteString value)

Compute the number of bytes that would be needed to encode an unparsed MessageSet extension field to the stream. For historical reasons, the wire format differs from normal fields.

computeFieldSize

public static int computeFieldSize(Descriptors.FieldDescriptor.Type type,
                                   int number,
                                   java.lang.Object value)

Compute the number of bytes that would be needed to encode a field of arbitrary type, including tag, to the stream.

Parameters:

type - The field's type.

number - The field's number.

value - Object representing the field's value. Must be of the exact type which would be returned by Message.getField(Descriptors.FieldDescriptor) for this field.

flush

public void flush()
           throws java.io.IOException

Flushes the stream and forces any buffered bytes to be written. This does not flush the underlying OutputStream.

Throws:

java.io.IOException

spaceLeft

public int spaceLeft()

If writing to a flat array, return the space left in the array. Otherwise, throws UnsupportedOperationException.

checkNoSpaceLeft

public void checkNoSpaceLeft()

Verifies that spaceLeft() returns zero. It's common to create a byte array that is exactly big enough to hold a message, then write to it with a CodedOutputStream. Calling checkNoSpaceLeft() after writing verifies that the message was actually as big as expected, which can help catch bugs.

writeRawByte

public void writeRawByte(byte value)
                  throws java.io.IOException

Write a single byte.

Throws:

java.io.IOException

writeRawByte

public void writeRawByte(int value)
                  throws java.io.IOException

Write a single byte, represented by an integer value.

Throws:

java.io.IOException

writeRawBytes

public void writeRawBytes(byte[] value)
                   throws java.io.IOException

Write an array of bytes.

Throws:

java.io.IOException

writeRawBytes

public void writeRawBytes(byte[] value,
                          int offset,
                          int length)
                   throws java.io.IOException

Write part of an array of bytes.

Throws:

java.io.IOException

writeTag

public void writeTag(int fieldNumber,
                     int wireType)
              throws java.io.IOException

Encode and write a tag.

Throws:

java.io.IOException

computeTagSize

public static int computeTagSize(int fieldNumber)

Compute the number of bytes that would be needed to encode a tag.

writeRawVarint32

public void writeRawVarint32(int value)
                      throws java.io.IOException

Encode and write a varint. value is treated as unsigned, so it won't be sign-extended if negative.

Throws:

java.io.IOException

computeRawVarint32Size

public static int computeRawVarint32Size(int value)

Compute the number of bytes that would be needed to encode a varint. value is treated as unsigned, so it won't be sign-extended if negative.

writeRawVarint64

public void writeRawVarint64(long value)
                      throws java.io.IOException

Encode and write a varint.

Throws:

java.io.IOException

computeRawVarint64Size

public static int computeRawVarint64Size(long value)

Compute the number of bytes that would be needed to encode a varint.

writeRawLittleEndian32

public void writeRawLittleEndian32(int value)
                            throws java.io.IOException

Write a little-endian 32-bit integer.

Throws:

java.io.IOException

writeRawLittleEndian64

public void writeRawLittleEndian64(long value)
                            throws java.io.IOException

Write a little-endian 64-bit integer.

Throws:

java.io.IOException

encodeZigZag32

public static int encodeZigZag32(int n)

Encode 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 - A signed 32-bit integer.

Returns:

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

encodeZigZag64

public static long encodeZigZag64(long n)

Encode 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 - A signed 64-bit integer.

Returns:

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