ProtoOutputStream
public
final
class
ProtoOutputStream
extends Object
java.lang.Object | |
↳ | android.util.proto.ProtoOutputStream |
Class to write to a protobuf stream.
This API is not as convenient or type safe as the standard protobuf classes. If possible, the best recommended library is to use protobuf lite. However, in environments (such as the Android platform itself), a more memory efficient version is necessary.
Each write method takes an ID code from the protoc generated classes
and the value to write. To make a nested object, call start(long)
and then end(long)
when you are done.
The ID codes have type information embedded into them, so if you call
the incorrect function you will get an IllegalArgumentException
.
To retrieve the encoded protobuf stream, call getBytes()
.
stream as the top-level objects are finished.
Summary
Constants | |
---|---|
long |
FIELD_COUNT_MASK
Bit mask for selecting the field count when reading a field id that
is used with a |
long |
FIELD_COUNT_PACKED
Repeated packed field count, encoded into a field id used with a
|
long |
FIELD_COUNT_REPEATED
Repeated field count, encoded into a field id used with a
|
int |
FIELD_COUNT_SHIFT
Bit offset for building a field id to be used with a
|
long |
FIELD_COUNT_SINGLE
Single field count, encoded into a field id used with a
|
long |
FIELD_COUNT_UNKNOWN
Unknown field count, encoded into a field id used with a
|
int |
FIELD_ID_SHIFT
Number of bits to shift the field number to form a tag. |
long |
FIELD_TYPE_BOOL
Field type code for bool fields. |
long |
FIELD_TYPE_BYTES
Field type code for bytes fields. |
long |
FIELD_TYPE_DOUBLE
Field type code for double fields. |
long |
FIELD_TYPE_ENUM
Field type code for enum fields. |
long |
FIELD_TYPE_FIXED32
Field type code for fixed32 fields. |
long |
FIELD_TYPE_FIXED64
Field type code for fixed64 fields. |
long |
FIELD_TYPE_FLOAT
Field type code for float fields. |
long |
FIELD_TYPE_INT32
Field type code for int32 fields. |
long |
FIELD_TYPE_INT64
Field type code for int64 fields. |
long |
FIELD_TYPE_MASK
Mask for the field types stored in a fieldId. |
long |
FIELD_TYPE_MESSAGE
Field type code for message fields. |
long |
FIELD_TYPE_SFIXED32
Field type code for sfixed32 fields. |
long |
FIELD_TYPE_SFIXED64
Field type code for sfixed64 fields. |
int |
FIELD_TYPE_SHIFT
Position of the field type in a (long) fieldId. |
long |
FIELD_TYPE_SINT32
Field type code for sint32 fields. |
long |
FIELD_TYPE_SINT64
Field type code for sint64 fields. |
long |
FIELD_TYPE_STRING
Field type code for string fields. |
long |
FIELD_TYPE_UINT32
Field type code for uint32 fields. |
long |
FIELD_TYPE_UINT64
Field type code for uint64 fields. |
int |
WIRE_TYPE_END_GROUP
End group wire type code. |
int |
WIRE_TYPE_FIXED32
Fixed32 wire type code. |
int |
WIRE_TYPE_FIXED64
Fixed64 wire type code. |
int |
WIRE_TYPE_LENGTH_DELIMITED
Length delimited wire type code. |
int |
WIRE_TYPE_MASK
Mask to select the wire type from a tag. |
int |
WIRE_TYPE_START_GROUP
Start group wire type code. |
int |
WIRE_TYPE_VARINT
Varint wire type code. |
Public constructors | |
---|---|
ProtoOutputStream()
Construct a |
|
ProtoOutputStream(int chunkSize)
Construct a {@link ProtoOutputStream with the given chunk size. |
|
ProtoOutputStream(OutputStream stream)
Construct a |
Public methods | |
---|---|
static
int
|
checkFieldId(long fieldId, long expectedFlags)
Validates that the fieldId provided is of the type and count from expectedType. |
void
|
dump(String tag)
Dump debugging data about the buffers with the given log tag. |
void
|
end(long token)
End the object started by start() that returned token. |
void
|
flush()
Write remaining data to the output stream. |
byte[]
|
getBytes()
Finish the encoding of the data, and return a byte[] with the protobuf formatted data. |
static
String
|
getFieldCountString(long fieldCount)
Get the developer-usable name of a field count. |
static
String
|
getFieldIdString(long fieldId)
Get a debug string for a fieldId. |
static
String
|
getFieldTypeString(long fieldType)
Get the developer-usable name of a field type. |
int
|
getRawSize()
Returns the total size of the data that has been written, after full protobuf encoding has occurred. |
static
String
|
getWireTypeString(int wireType)
Get the developer-usable name of a wire type. |
static
long
|
makeFieldId(int id, long fieldFlags)
Combine a fieldId (the field keys in the proto file) and the field flags. |
static
long
|
makeToken(int tagSize, boolean repeated, int depth, int objectId, int offset)
Make a token. |
long
|
start(long fieldId)
Start a sub object. |
static
String
|
token2String(long token)
Return a debugging string of a token. |
void
|
write(long fieldId, String val)
Write a string value for the given fieldId. |
void
|
write(long fieldId, boolean val)
Write a boolean value for the given fieldId. |
void
|
write(long fieldId, int val)
Write a value for the given fieldId. |
void
|
write(long fieldId, float val)
Write a value for the given fieldId. |
void
|
write(long fieldId, long val)
Write a value for the given fieldId. |
void
|
write(long fieldId, double val)
Write a value for the given fieldId. |
void
|
write(long fieldId, byte[] val)
Write a byte[] value for the given fieldId. |
void
|
writeTag(int id, int wireType)
Write an individual field tag by hand. |
Inherited methods | |
---|---|
Constants
FIELD_COUNT_MASK
public static final long FIELD_COUNT_MASK
Bit mask for selecting the field count when reading a field id that
is used with a
method.ProtoOutputStream
.write(...)
See also:
Constant Value: 16492674416640 (0x00000f0000000000)
FIELD_COUNT_PACKED
public static final long FIELD_COUNT_PACKED
Repeated packed field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
See also:
Constant Value: 5497558138880 (0x0000050000000000)
FIELD_COUNT_REPEATED
public static final long FIELD_COUNT_REPEATED
Repeated field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
See also:
Constant Value: 2199023255552 (0x0000020000000000)
FIELD_COUNT_SHIFT
public static final int FIELD_COUNT_SHIFT
Bit offset for building a field id to be used with a
.ProtoOutputStream
.write(...)
See also:
Constant Value: 40 (0x00000028)
FIELD_COUNT_SINGLE
public static final long FIELD_COUNT_SINGLE
Single field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
See also:
Constant Value: 1099511627776 (0x0000010000000000)
FIELD_COUNT_UNKNOWN
public static final long FIELD_COUNT_UNKNOWN
Unknown field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
See also:
Constant Value: 0 (0x0000000000000000)
FIELD_ID_SHIFT
public static final int FIELD_ID_SHIFT
Number of bits to shift the field number to form a tag.
// Reading a field number from a tag. int fieldNumber = tag >>> FIELD_ID_SHIFT; // Building a tag from a field number and a wire type. int tag = (fieldNumber << FIELD_ID_SHIFT) | wireType;
See also:
Constant Value: 3 (0x00000003)
FIELD_TYPE_BOOL
public static final long FIELD_TYPE_BOOL
Field type code for bool fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, boolean)
method.
Constant Value: 34359738368 (0x0000000800000000)
FIELD_TYPE_BYTES
public static final long FIELD_TYPE_BYTES
Field type code for bytes fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, byte[])
method.
Constant Value: 51539607552 (0x0000000c00000000)
FIELD_TYPE_DOUBLE
public static final long FIELD_TYPE_DOUBLE
Field type code for double fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, double)
method.
Constant Value: 4294967296 (0x0000000100000000)
FIELD_TYPE_ENUM
public static final long FIELD_TYPE_ENUM
Field type code for enum fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 60129542144 (0x0000000e00000000)
FIELD_TYPE_FIXED32
public static final long FIELD_TYPE_FIXED32
Field type code for fixed32 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 30064771072 (0x0000000700000000)
FIELD_TYPE_FIXED64
public static final long FIELD_TYPE_FIXED64
Field type code for fixed64 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, long)
method.
Constant Value: 25769803776 (0x0000000600000000)
FIELD_TYPE_FLOAT
public static final long FIELD_TYPE_FLOAT
Field type code for float fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, float)
method.
Constant Value: 8589934592 (0x0000000200000000)
FIELD_TYPE_INT32
public static final long FIELD_TYPE_INT32
Field type code for int32 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 21474836480 (0x0000000500000000)
FIELD_TYPE_INT64
public static final long FIELD_TYPE_INT64
Field type code for int64 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, long)
method.
Constant Value: 12884901888 (0x0000000300000000)
FIELD_TYPE_MASK
public static final long FIELD_TYPE_MASK
Mask for the field types stored in a fieldId. Leaves a whole byte for future expansion, even though there are currently only 17 types.
Constant Value: 1095216660480 (0x000000ff00000000)
FIELD_TYPE_MESSAGE
public static final long FIELD_TYPE_MESSAGE
Field type code for message fields. Used to build constants in generated
code for use with the ProtoOutputStream.start(long)
method.
Constant Value: 47244640256 (0x0000000b00000000)
FIELD_TYPE_SFIXED32
public static final long FIELD_TYPE_SFIXED32
Field type code for sfixed32 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 64424509440 (0x0000000f00000000)
FIELD_TYPE_SFIXED64
public static final long FIELD_TYPE_SFIXED64
Field type code for sfixed64 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, long)
method.
Constant Value: 68719476736 (0x0000001000000000)
FIELD_TYPE_SHIFT
public static final int FIELD_TYPE_SHIFT
Position of the field type in a (long) fieldId.
Constant Value: 32 (0x00000020)
FIELD_TYPE_SINT32
public static final long FIELD_TYPE_SINT32
Field type code for sint32 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 73014444032 (0x0000001100000000)
FIELD_TYPE_SINT64
public static final long FIELD_TYPE_SINT64
Field type code for sint64 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, long)
method.
Constant Value: 77309411328 (0x0000001200000000)
FIELD_TYPE_STRING
public static final long FIELD_TYPE_STRING
Field type code for string fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, String)
method.
Constant Value: 38654705664 (0x0000000900000000)
FIELD_TYPE_UINT32
public static final long FIELD_TYPE_UINT32
Field type code for uint32 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, int)
method.
Constant Value: 55834574848 (0x0000000d00000000)
FIELD_TYPE_UINT64
public static final long FIELD_TYPE_UINT64
Field type code for uint64 fields. Used to build constants in generated
code for use with the ProtoOutputStream.write(long, long)
method.
Constant Value: 17179869184 (0x0000000400000000)
WIRE_TYPE_END_GROUP
public static final int WIRE_TYPE_END_GROUP
End group wire type code.
See also:
Constant Value: 4 (0x00000004)
WIRE_TYPE_FIXED32
public static final int WIRE_TYPE_FIXED32
Fixed32 wire type code.
See also:
Constant Value: 5 (0x00000005)
WIRE_TYPE_FIXED64
public static final int WIRE_TYPE_FIXED64
Fixed64 wire type code.
See also:
Constant Value: 1 (0x00000001)
WIRE_TYPE_LENGTH_DELIMITED
public static final int WIRE_TYPE_LENGTH_DELIMITED
Length delimited wire type code.
See also:
Constant Value: 2 (0x00000002)
WIRE_TYPE_MASK
public static final int WIRE_TYPE_MASK
Mask to select the wire type from a tag.
// Reading a wire type from a tag. int wireType = tag & WIRE_TYPE_MASK; // Building a tag from a field number and a wire type. int tag = (fieldNumber << FIELD_ID_SHIFT) | wireType;
See also:
Constant Value: 7 (0x00000007)
WIRE_TYPE_START_GROUP
public static final int WIRE_TYPE_START_GROUP
Start group wire type code.
See also:
Constant Value: 3 (0x00000003)
WIRE_TYPE_VARINT
public static final int WIRE_TYPE_VARINT
Varint wire type code.
See also:
Constant Value: 0 (0x00000000)
Public constructors
ProtoOutputStream
public ProtoOutputStream ()
Construct a ProtoOutputStream
with the default chunk size.
This is for an in-memory proto. The caller should use getBytes()
for the result.
ProtoOutputStream
public ProtoOutputStream (int chunkSize)
Construct a {@link ProtoOutputStream with the given chunk size.
This is for an in-memory proto. The caller should use {@link #getBytes()} for the result.
Parameters | |
---|---|
chunkSize |
int |
ProtoOutputStream
public ProtoOutputStream (OutputStream stream)
Construct a ProtoOutputStream
that sits on top of an OutputStream
.
The flush()
method must be called when done writing
to flush any remaining data, although data *may* be written at intermediate
points within the writing as well.
Parameters | |
---|---|
stream |
OutputStream : This value cannot be null . |
Public methods
checkFieldId
public static int checkFieldId (long fieldId, long expectedFlags)
Validates that the fieldId provided is of the type and count from expectedType.
The type must match exactly to pass this check.
The count must match according to this truth table to pass the check: expectedFlags UNKNOWN SINGLE REPEATED PACKED fieldId UNKNOWN true false false false SINGLE x true false false REPEATED x false true false PACKED x false true true
Parameters | |
---|---|
fieldId |
long |
expectedFlags |
long |
Returns | |
---|---|
int |
The raw ID of that field. |
Throws | |
---|---|
|
java.lang.IllegalArgumentException IllegalArgumentException} if it is not. |
dump
public void dump (String tag)
Dump debugging data about the buffers with the given log tag.
Parameters | |
---|---|
tag |
String : This value cannot be null . |
end
public void end (long token)
End the object started by start() that returned token.
Parameters | |
---|---|
token |
long : The token returned from start(long) |
flush
public void flush ()
Write remaining data to the output stream. If there is no output stream,
this function does nothing. Any currently open objects (i.e. ones that
have not had end(long)
called for them will not be written). Whether this
writes objects that are closed if there are remaining open objects is
undefined (current implementation does not write it, future ones will).
For now, can either call getBytes()
or flush()
, but not both.
getBytes
public byte[] getBytes ()
Finish the encoding of the data, and return a byte[] with the protobuf formatted data.
After this call, do not call any of the write* functions. The behavior is undefined.
Returns | |
---|---|
byte[] |
This value cannot be null . |
getFieldCountString
public static String getFieldCountString (long fieldCount)
Get the developer-usable name of a field count.
Parameters | |
---|---|
fieldCount |
long |
Returns | |
---|---|
String |
This value may be null . |
getFieldIdString
public static String getFieldIdString (long fieldId)
Get a debug string for a fieldId.
Parameters | |
---|---|
fieldId |
long |
Returns | |
---|---|
String |
This value cannot be null . |
getFieldTypeString
public static String getFieldTypeString (long fieldType)
Get the developer-usable name of a field type.
Parameters | |
---|---|
fieldType |
long : Value is android.util.proto.ProtoStream.FIELD_TYPE_UNKNOWN, android.util.proto.ProtoStream.FIELD_TYPE_DOUBLE, android.util.proto.ProtoStream.FIELD_TYPE_FLOAT, android.util.proto.ProtoStream.FIELD_TYPE_INT64, android.util.proto.ProtoStream.FIELD_TYPE_UINT64, android.util.proto.ProtoStream.FIELD_TYPE_INT32, android.util.proto.ProtoStream.FIELD_TYPE_FIXED64, android.util.proto.ProtoStream.FIELD_TYPE_FIXED32, android.util.proto.ProtoStream.FIELD_TYPE_BOOL, android.util.proto.ProtoStream.FIELD_TYPE_STRING, android.util.proto.ProtoStream.FIELD_TYPE_MESSAGE, android.util.proto.ProtoStream.FIELD_TYPE_BYTES, android.util.proto.ProtoStream.FIELD_TYPE_UINT32, android.util.proto.ProtoStream.FIELD_TYPE_ENUM, android.util.proto.ProtoStream.FIELD_TYPE_SFIXED32, android.util.proto.ProtoStream.FIELD_TYPE_SFIXED64, android.util.proto.ProtoStream.FIELD_TYPE_SINT32, or android.util.proto.ProtoStream.FIELD_TYPE_SINT64 |
Returns | |
---|---|
String |
This value may be null . |
getRawSize
public int getRawSize ()
Returns the total size of the data that has been written, after full protobuf encoding has occurred.
Returns | |
---|---|
int |
the uncompressed buffer size |
getWireTypeString
public static String getWireTypeString (int wireType)
Get the developer-usable name of a wire type.
Parameters | |
---|---|
wireType |
int : Value is android.util.proto.ProtoStream.WIRE_TYPE_VARINT, android.util.proto.ProtoStream.WIRE_TYPE_FIXED64, android.util.proto.ProtoStream.WIRE_TYPE_LENGTH_DELIMITED, android.util.proto.ProtoStream.WIRE_TYPE_START_GROUP, android.util.proto.ProtoStream.WIRE_TYPE_END_GROUP, or android.util.proto.ProtoStream.WIRE_TYPE_FIXED32 |
Returns | |
---|---|
String |
This value may be null . |
makeFieldId
public static long makeFieldId (int id, long fieldFlags)
Combine a fieldId (the field keys in the proto file) and the field flags. Mostly useful for testing because the generated code contains the fieldId constants.
Parameters | |
---|---|
id |
int |
fieldFlags |
long |
Returns | |
---|---|
long |
makeToken
public static long makeToken (int tagSize, boolean repeated, int depth, int objectId, int offset)
Make a token. Bits 61-63 - tag size (So we can go backwards later if the object had not data) - 3 bits, max value 7, max value needed 5 Bit 60 - true if the object is repeated (lets us require endObject or endRepeatedObject) Bits 59-51 - depth (For error checking) - 9 bits, max value 512, when checking, value is masked (if we really are more than 512 levels deep) Bits 32-50 - objectId (For error checking) - 19 bits, max value 524,288. that's a lot of objects. IDs will wrap because of the overflow, and only the tokens are compared. Bits 0-31 - offset of interest for the object.
Parameters | |
---|---|
tagSize |
int |
repeated |
boolean |
depth |
int |
objectId |
int |
offset |
int |
Returns | |
---|---|
long |
start
public long start (long fieldId)
Start a sub object.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
Returns | |
---|---|
long |
The token to call end(long) with. |
token2String
public static String token2String (long token)
Return a debugging string of a token.
Parameters | |
---|---|
token |
long |
Returns | |
---|---|
String |
This value cannot be null . |
write
public void write (long fieldId, String val)
Write a string value for the given fieldId.
If the field is not a string field, an exception will be thrown.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
String : The value.
This value may be null . |
write
public void write (long fieldId, boolean val)
Write a boolean value for the given fieldId.
If the field is not a bool field, an IllegalStateException
will be thrown.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
boolean : The value. |
write
public void write (long fieldId, int val)
Write a value for the given fieldId.
Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
int : The value. |
write
public void write (long fieldId, float val)
Write a value for the given fieldId.
Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
float : The value. |
write
public void write (long fieldId, long val)
Write a value for the given fieldId.
Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
long : The value. |
write
public void write (long fieldId, double val)
Write a value for the given fieldId.
Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
double : The value. |
write
public void write (long fieldId, byte[] val)
Write a byte[] value for the given fieldId.
If the field is not a bytes or object field, an exception will be thrown.
Parameters | |
---|---|
fieldId |
long : The field identifier constant from the generated class. |
val |
byte : The value.
This value may be null . |
writeTag
public void writeTag (int id, int wireType)
Write an individual field tag by hand. See Protobuf Encoding for details on the structure of how tags and data are written.
Parameters | |
---|---|
id |
int |
wireType |
int : Value is android.util.proto.ProtoStream.WIRE_TYPE_VARINT, android.util.proto.ProtoStream.WIRE_TYPE_FIXED64, android.util.proto.ProtoStream.WIRE_TYPE_LENGTH_DELIMITED, android.util.proto.ProtoStream.WIRE_TYPE_START_GROUP, android.util.proto.ProtoStream.WIRE_TYPE_END_GROUP, or android.util.proto.ProtoStream.WIRE_TYPE_FIXED32 |