public abstract class CodedOutputStream extends ByteOutput
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 and #writeInt32) and methods that write low-level values (e.g. #writeRawVarint32 and #writeRawBytes). 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.
public static int computeEnumSize(int fieldNumber, int value)
Compute the number of bytes that would be needed to encode an enum field, including tag. The provided value is the numeric value used to represent the enum value on the wire (not the enum ordinal value).
Compute the number of bytes that would be needed to encode an enum field. The provided value is the numeric value used to represent the enum value on the wire (not the enum ordinal value).
public static int computeLazyFieldMessageSetExtensionSize(int fieldNumber, LazyFieldLite value)
Compute the number of bytes that would be needed to encode a lazily parsed MessageSet extension field to the stream. For historical reasons, the wire format differs from normal fields.
public static int computeMessageSetExtensionSize(int fieldNumber, MessageLite 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.
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.
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.)
An unsigned 32-bit integer, stored in a signed int because Java has no explicit unsigned support.
encodeZigZag64(long n)
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.)
An unsigned 64-bit integer, stored in a signed int because Java has no explicit unsigned support.
newInstance(byte[] flatArray)
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, OutOfSpaceException will be thrown. Writing directly to a flat array is faster than writing to an OutputStream. See also ByteString#newCodedBuilder.
newInstance(byte[] flatArray, int offset, int length)
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, OutOfSpaceException will be thrown. Writing directly to a flat array is faster than writing to an OutputStream. See alsoByteString#newCodedBuilder.
public static CodedOutputStream newInstance(OutputStream output)
Create a new CodedOutputStream wrapping the given OutputStream.
NOTE: The provided OutputStreamMUST NOT retain access or modify the provided byte arrays. Doing so may result in corrupted data, which would be difficult to debug.
public static CodedOutputStream newInstance(OutputStream output, int bufferSize)
Create a new CodedOutputStream wrapping the given OutputStream with a given buffer size.
NOTE: The provided OutputStreamMUST NOT retain access or modify the provided byte arrays. Doing so may result in corrupted data, which would be difficult to debug.
newInstance(ByteBuffer byteBuffer, int unused) (deprecated)
public static CodedOutputStream newInstance(ByteBuffer byteBuffer, int unused)
Deprecated.the size parameter is no longer used since use of an internal buffer is useless (and wasteful) when writing to a ByteBuffer. Use #newInstance(ByteBuffer) instead.
Create a new CodedOutputStream that writes to the given ByteBuffer.
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.
flush()
public abstract void flush()
Flushes the stream and forces any buffered bytes to be written. This does not flush the underlying OutputStream.
Get the total number of bytes successfully written to this stream. The returned value is not guaranteed to be accurate if exceptions have been found in the middle of writing.
The deterministic serialization guarantees that for a given binary, equal (defined by theequals() methods in protos) messages will always be serialized to the same bytes. This implies:
repeated serialization of a message will return the same bytes
different processes of the same binary (which may be executing on different machines) will serialize equal messages to the same bytes.
Note the deterministic serialization is NOT canonical across languages; it is also unstable across different builds with schema changes due to unknown fields. Users who need canonical serialization, e.g. persistent storage in a canonical form, fingerprinting, etc, should define their own canonicalization specification and implement the serializer using reflection APIs rather than relying on this API.
Once set, the serializer will: (Note this is an implementation detail and may subject to change in the future)
sort map entries by keys in lexicographical order or numerical order. Note: For string keys, the order is based on comparing the Unicode value of each character in the strings. The order may be different from the deterministic serialization in other languages where maps are sorted on the lexicographical order of the UTF8 encoded keys.
public abstract void write(byte[] value, int offset, int length)
Writes a sequence of bytes. The ByteOutput must copy value if it will not be processed prior to the return of this method call, since value may be reused/altered by the caller.
NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.
Writes a sequence of bytes. The ByteOutput must copy value if it will not be processed prior to the return of this method call, since value may be reused/altered by the caller.
NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.
public abstract void writeByteBuffer(int fieldNumber, ByteBuffer value)
Write a bytes field, including tag, to the stream. This method will write all content of the ByteBuffer regardless of the current position and limit (i.e., the number of bytes to be written is value.capacity(), not value.remaining()). Furthermore, this method doesn't alter the state of the passed-in ByteBuffer. Its position, limit, mark, etc. will remain unchanged. If you only want to write the remaining bytes of a ByteBuffer, you can call writeByteBuffer(fieldNumber, byteBuffer.slice()).
public final void writeEnum(int fieldNumber, int value)
Write an enum field, including tag, to the stream. The provided value is the numeric value used to represent the enum value on the wire (not the enum ordinal value).
public abstract void writeLazy(byte[] value, int offset, int length)
Writes a sequence of bytes. The ByteOutput is free to retain a reference to the value beyond the scope of this method call (e.g. write later) since it is considered immutable and is guaranteed not to change by the caller.
NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.
Writes a sequence of bytes. The ByteOutput is free to retain a reference to the value beyond the scope of this method call (e.g. write later) since it is considered immutable and is guaranteed not to change by the caller.
NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.
public abstract void writeRawBytes(ByteBuffer value)
Write a ByteBuffer. This method will write all content of the ByteBuffer regardless of the current position and limit (i.e., the number of bytes to be written is value.capacity(), not value.remaining()). Furthermore, this method doesn't alter the state of the passed-in ByteBuffer. Its position, limit, mark, etc. will remain unchanged. If you only want to write the remaining bytes of a ByteBuffer, you can call writeRawBytes(byteBuffer.slice()).