A partial implementation of the Message interface which implements as many methods of that interface as possible in terms of other methods.

A partial implementation of the Message.Builder interface which implements as many methods of that interface as possible in terms of other methods.

A partial implementation of the MessageLite interface which implements as many methods of that interface as possible in terms of other methods.

A partial implementation of the Message.Builder interface which implements as many methods of that interface as possible in terms of other methods.

A partial implementation of the Parser interface which implements as many methods of that interface as possible in terms of other methods.

Note: This class implements all the convenience methods in the Parser interface. See Parser for related javadocs. Subclasses need to implement Parser#parsePartialFrom(CodedInputStream, ExtensionRegistryLite)

Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Foo foo = ...; Any any; any.PackFrom(foo); ... if (any.UnpackTo(&foo)) { ... } Example 2: Pack and unpack a message in Java. Foo foo = ...; Any any = Any.pack(foo); ... if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) ... Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { ... } ... foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { ... } The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".

JSON

The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" }

Protobuf type google.protobuf.Any

Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Foo foo = ...; Any any; any.PackFrom(foo); ... if (any.UnpackTo(&foo)) { ... } Example 2: Pack and unpack a message in Java. Foo foo = ...; Any any = Any.pack(foo); ... if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) ... Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { ... } ... foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { ... } The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".

JSON

The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" }

Protobuf type google.protobuf.Any

Api is a light-weight descriptor for an API Interface. Interfaces are also described as "protocol buffer services" in some contexts, such as by the "service" keyword in a .proto file, but they are different from API Services, which represent a concrete implementation of an interface as opposed to simply a description of methods and bindings. They are also sometimes simply referred to as "APIs" in other contexts, such as the name of this message itself. See https://cloud.google.com/apis/design/glossary for detailed terminology.

Protobuf type google.protobuf.Api

Api is a light-weight descriptor for an API Interface. Interfaces are also described as "protocol buffer services" in some contexts, such as by the "service" keyword in a .proto file, but they are different from API Services, which represent a concrete implementation of an interface as opposed to simply a description of methods and bindings. They are also sometimes simply referred to as "APIs" in other contexts, such as the name of this message itself. See https://cloud.google.com/apis/design/glossary for detailed terminology.

Protobuf type google.protobuf.Api

Wrapper message for bool. The JSON representation for BoolValue is JSON true and false.

Protobuf type google.protobuf.BoolValue

Wrapper message for bool. The JSON representation for BoolValue is JSON true and false.

Protobuf type google.protobuf.BoolValue

An output target for raw bytes. This interface provides semantics that support two types of writing:

Traditional write operations: (as defined by java.io.OutputStream) where the target method is responsible for either copying the data or completing the write before returning from the method call.

Lazy write operations: where the caller guarantees that it will never modify the provided buffer and it can therefore be considered immutable. The target method is free to maintain a reference to the buffer beyond the scope of the method call (e.g. until the write operation completes).

Immutable sequence of bytes. Provides conversions to and from byte[], java.lang.String, ByteBuffer, InputStream, OutputStream. Also provides a conversion to CodedInputStream.

Like String, the contents of a ByteString can never be observed to change, not even in the presence of a data race or incorrect API usage in the client code.

Substring is supported by sharing the reference to the immutable underlying bytes. Concatenation is likewise supported without copying (long strings) by building a tree of pieces in RopeByteString.

Outputs to a ByteString instance. Call #toByteString() to create the ByteString instance.

Wrapper message for bytes. The JSON representation for BytesValue is JSON string.

Protobuf type google.protobuf.BytesValue

Wrapper message for bytes. The JSON representation for BytesValue is JSON string.

Protobuf type google.protobuf.BytesValue

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

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.

This class is totally unsynchronized.

Describes a message type.

Protobuf type google.protobuf.DescriptorProto

Describes a message type.

Protobuf type google.protobuf.DescriptorProto

Protobuf type google.protobuf.DescriptorProto.ExtensionRange

Protobuf type google.protobuf.DescriptorProto.ExtensionRange

Range of reserved tag numbers. Reserved tag numbers may not be used by fields or extension ranges in the same message. Reserved ranges may not overlap.

Protobuf type google.protobuf.DescriptorProto.ReservedRange

Range of reserved tag numbers. Reserved tag numbers may not be used by fields or extension ranges in the same message. Reserved ranges may not overlap.

Protobuf type google.protobuf.DescriptorProto.ReservedRange

Describes an enum type.

Protobuf type google.protobuf.EnumDescriptorProto

Describes an enum type.

Protobuf type google.protobuf.EnumDescriptorProto

Range of reserved numeric values. Reserved values may not be used by entries in the same enum. Reserved ranges may not overlap. Note that this is distinct from DescriptorProto.ReservedRange in that it is inclusive such that it can appropriately represent the entire int32 domain.

Protobuf type google.protobuf.EnumDescriptorProto.EnumReservedRange

Range of reserved numeric values. Reserved values may not be used by entries in the same enum. Reserved ranges may not overlap. Note that this is distinct from DescriptorProto.ReservedRange in that it is inclusive such that it can appropriately represent the entire int32 domain.

Protobuf type google.protobuf.EnumDescriptorProto.EnumReservedRange

Protobuf type google.protobuf.EnumOptions

Protobuf type google.protobuf.EnumOptions

Describes a value within an enum.

Protobuf type google.protobuf.EnumValueDescriptorProto

Describes a value within an enum.

Protobuf type google.protobuf.EnumValueDescriptorProto

Protobuf type google.protobuf.EnumValueOptions

Protobuf type google.protobuf.EnumValueOptions

Protobuf type google.protobuf.ExtensionRangeOptions

Protobuf type google.protobuf.ExtensionRangeOptions

Describes a field within a message.

Protobuf type google.protobuf.FieldDescriptorProto

Describes a field within a message.

Protobuf type google.protobuf.FieldDescriptorProto

Protobuf type google.protobuf.FieldOptions

Protobuf type google.protobuf.FieldOptions

Describes a complete .proto file.

Protobuf type google.protobuf.FileDescriptorProto

Describes a complete .proto file.

Protobuf type google.protobuf.FileDescriptorProto

The protocol compiler can output a FileDescriptorSet containing the .proto files it parses.

Protobuf type google.protobuf.FileDescriptorSet

The protocol compiler can output a FileDescriptorSet containing the .proto files it parses.

Protobuf type google.protobuf.FileDescriptorSet

Protobuf type google.protobuf.FileOptions

Protobuf type google.protobuf.FileOptions

Describes the relationship between generated code and its original source file. A GeneratedCodeInfo message is associated with only one generated source file, but may contain references to different source .proto files.

Protobuf type google.protobuf.GeneratedCodeInfo

Protobuf type google.protobuf.GeneratedCodeInfo.Annotation

Protobuf type google.protobuf.GeneratedCodeInfo.Annotation

Describes the relationship between generated code and its original source file. A GeneratedCodeInfo message is associated with only one generated source file, but may contain references to different source .proto files.

Protobuf type google.protobuf.GeneratedCodeInfo

Protobuf type google.protobuf.MessageOptions

Protobuf type google.protobuf.MessageOptions

Describes a method of a service.

Protobuf type google.protobuf.MethodDescriptorProto

Describes a method of a service.

Protobuf type google.protobuf.MethodDescriptorProto

Protobuf type google.protobuf.MethodOptions

Protobuf type google.protobuf.MethodOptions

Describes a oneof.

Protobuf type google.protobuf.OneofDescriptorProto

Describes a oneof.

Protobuf type google.protobuf.OneofDescriptorProto

Protobuf type google.protobuf.OneofOptions

Protobuf type google.protobuf.OneofOptions

Describes a service.

Protobuf type google.protobuf.ServiceDescriptorProto

Describes a service.

Protobuf type google.protobuf.ServiceDescriptorProto

Protobuf type google.protobuf.ServiceOptions

Protobuf type google.protobuf.ServiceOptions

Encapsulates information about the original source file from which a FileDescriptorProto was generated.

Protobuf type google.protobuf.SourceCodeInfo

Encapsulates information about the original source file from which a FileDescriptorProto was generated.

Protobuf type google.protobuf.SourceCodeInfo

Protobuf type google.protobuf.SourceCodeInfo.Location

Protobuf type google.protobuf.SourceCodeInfo.Location

A message representing a option the parser does not recognize. This only appears in options protos created by the compiler::Parser class. DescriptorPool resolves these when building Descriptor objects. Therefore, options protos in descriptor objects (e.g. returned by Descriptor::options(), or produced by Descriptor::CopyTo()) will never have UninterpretedOptions in them.

Protobuf type google.protobuf.UninterpretedOption

A message representing a option the parser does not recognize. This only appears in options protos created by the compiler::Parser class. DescriptorPool resolves these when building Descriptor objects. Therefore, options protos in descriptor objects (e.g. returned by Descriptor::options(), or produced by Descriptor::CopyTo()) will never have UninterpretedOptions in them.

Protobuf type google.protobuf.UninterpretedOption

The name of the uninterpreted option. Each string represents a segment in a dot-separated name. is_extension is true iff a segment represents an extension (denoted with parentheses in options specs in .proto files). E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents "foo.(bar.baz).qux".

Protobuf type google.protobuf.UninterpretedOption.NamePart

The name of the uninterpreted option. Each string represents a segment in a dot-separated name. is_extension is true iff a segment represents an extension (denoted with parentheses in options specs in .proto files). E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents "foo.(bar.baz).qux".

Protobuf type google.protobuf.UninterpretedOption.NamePart

Contains a collection of classes which describe protocol message types.

Every message type has a Descriptor, which lists all its fields and other information about a type. You can get a message type's descriptor by calling MessageType.getDescriptor(), or (given a message object of the type) message.getDescriptorForType(). Furthermore, each message is associated with a FileDescriptor for a relevant .proto file. You can obtain it by calling Descriptor.getFile(). A FileDescriptor contains descriptors for all the messages defined in that file, and file descriptors for all the imported .proto files.

Descriptors are built from DescriptorProtos, as defined in google/protobuf/descriptor.proto.

Describes a message type.

Describes an enum type.

Describes one value within an enum type. Note that multiple defined values may have the same number. In generated Java code, all values with the same number after the first become aliases of the first. However, they still have independent EnumValueDescriptors.

Describes a field of a message type.

Describes a .proto file, including everything defined within. That includes, in particular, descriptors for all the messages and file descriptors for all other imported .proto files (dependencies).

All descriptors implement this to make it easier to implement tools like DescriptorPool.

Describes one method within a service type.

Describes an oneof of a message type.

Describes a service type.

Parsers to discard unknown fields during parsing.

Wrapper message for double. The JSON representation for DoubleValue is JSON number.

Protobuf type google.protobuf.DoubleValue

Wrapper message for double. The JSON representation for DoubleValue is JSON number.

Protobuf type google.protobuf.DoubleValue

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

Examples

Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td)

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".

Protobuf type google.protobuf.Duration

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

Examples

Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td)

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".

Protobuf type google.protobuf.Duration

An implementation of Message that can represent arbitrary types, given a Descriptors.Descriptor.

Builder for DynamicMessages.

A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance: service Foo { rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); } The JSON representation for Empty is empty JSON object {}.

Protobuf type google.protobuf.Empty

A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance: service Foo { rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); } The JSON representation for Empty is empty JSON object {}.

Protobuf type google.protobuf.Empty

Enum type definition.

Protobuf type google.protobuf.Enum

Enum type definition.

Protobuf type google.protobuf.Enum

Enum value definition.

Protobuf type google.protobuf.EnumValue

Enum value definition.

Protobuf type google.protobuf.EnumValue

Interface that generated extensions implement.

Lite interface that generated extensions implement.

Methods are for use by generated code only. You can hold a reference to extensions using this type name.

A table of known extensions, searchable by name or field number. When parsing a protocol message that might have extensions, you must provide an ExtensionRegistry in which you have registered any extensions that you want to be able to parse. Otherwise, those extensions will just be treated like unknown fields.

For example, if you had the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then you might write code like:

ExtensionRegistry registry = ExtensionRegistry.newInstance(); registry.add(MyProto.bar); MyProto.Foo message = MyProto.Foo.parseFrom(input, registry);

Background:

You might wonder why this is necessary. Two alternatives might come to mind. First, you might imagine a system where generated extensions are automatically registered when their containing classes are loaded. This is a popular technique, but is bad design; among other things, it creates a situation where behavior can change depending on what classes happen to be loaded. It also introduces a security vulnerability, because an unprivileged class could cause its code to be called unexpectedly from a privileged class by registering itself as an extension of the right type.

Another option you might consider is lazy parsing: do not parse an extension until it is first requested, at which point the caller must provide a type to use. This introduces a different set of problems. First, it would require a mutex lock any time an extension was accessed, which would be slow. Second, corrupt data would not be detected until first access, at which point it would be much harder to deal with it. Third, it could violate the expectation that message objects are immutable, since the type provided could be any arbitrary message class. An unprivileged user could take advantage of this to inject a mutable object into a message belonging to privileged code and create mischief.

A (Descriptor, Message) pair, returned by lookup methods.

Equivalent to ExtensionRegistry but supports only "lite" types.

If all of your types are lite types, then you only need to use ExtensionRegistryLite. Similarly, if all your types are regular types, then you only need ExtensionRegistry. Typically it does not make sense to mix the two, since if you have any regular types in your program, you then require the full runtime and lose all the benefits of the lite runtime, so you might as well make all your types be regular types. However, in some cases (e.g. when depending on multiple third-party libraries where one uses lite types and one uses regular), you may find yourself wanting to mix the two. In this case things get more complicated.

There are three factors to consider: Whether the type being extended is lite, whether the embedded type (in the case of a message-typed extension) is lite, and whether the extension itself is lite. Since all three are declared in different files, they could all be different. Here are all the combinations and which type of registry to use:

Extended type Inner type Extension Use registry

lite lite lite ExtensionRegistryLite lite regular lite ExtensionRegistry regular regular regular ExtensionRegistry all other combinations not supported

Note that just as regular types are not allowed to contain lite-type fields, they are also not allowed to contain lite-type extensions. This is because regular types must be fully accessible via reflection, which in turn means that all the inner messages must also support reflection. On the other hand, since regular types implement the entire lite interface, there is no problem with embedding regular types inside lite types.

A single field of a message type.

Protobuf type google.protobuf.Field

A single field of a message type.

Protobuf type google.protobuf.Field

FieldMask represents a set of symbolic field paths, for example: paths: "f.a" paths: "f.b.d" Here f represents a field in some root message, a and b fields in the message found in f, and d a field found in the message in f.b. Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below).

Field Masks in Projections

When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows: f { a : 22 b { d : 1 x : 2 } y : 13 } z: 8 The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output): f { a : 22 b { d : 1 } } A repeated field is not allowed except at the last position of a paths string. If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified). Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs.

Field Masks in Update Operations

A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask. If a repeated field is specified for an update operation, new values will be appended to the existing repeated field in the target resource. Note that a repeated field is only allowed in the last position of a paths string. If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource. For example, given the target message: f { b { d: 1 x: 2 } c: [1] } And an update message: f { b { d: 10 } c: [2] } then if the field mask is: paths: ["f.b", "f.c"] then the result will be: f { b { d: 10 x: 2 } c: [1, 2] } An implementation may provide options to override this default behavior for repeated and message fields. In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below. If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not. As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API.

Considerations for HTTP REST

The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates).

JSON Encoding of Field Masks

In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions. As an example, consider the following message declarations: message Profile { User user = 1; Photo photo = 2; } message User { string display_name = 1; string address = 2; } In proto a field mask for Profile may look as such: mask { paths: "user.display_name" paths: "photo" } In JSON, the same mask is represented as below: { mask: "user.displayName,photo" }

Field Masks and Oneof Fields

Field masks treat fields in oneofs just as regular fields. Consider the following message: message SampleMessage { oneof test_oneof { string name = 4; SubMessage sub_message = 9; } } The field mask can be: mask { paths: "name" } Or: mask { paths: "sub_message" } Note that oneof type names ("test_oneof" in this case) cannot be used in paths.

Field Mask Verification

The implementation of any API method which has a FieldMask type field in the request should verify the included field paths, and return an INVALID_ARGUMENT error if any path is unmappable.

Protobuf type google.protobuf.FieldMask

FieldMask represents a set of symbolic field paths, for example: paths: "f.a" paths: "f.b.d" Here f represents a field in some root message, a and b fields in the message found in f, and d a field found in the message in f.b. Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below).

Field Masks in Projections

When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows: f { a : 22 b { d : 1 x : 2 } y : 13 } z: 8 The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output): f { a : 22 b { d : 1 } } A repeated field is not allowed except at the last position of a paths string. If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified). Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs.

Field Masks in Update Operations

A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask. If a repeated field is specified for an update operation, new values will be appended to the existing repeated field in the target resource. Note that a repeated field is only allowed in the last position of a paths string. If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource. For example, given the target message: f { b { d: 1 x: 2 } c: [1] } And an update message: f { b { d: 10 } c: [2] } then if the field mask is: paths: ["f.b", "f.c"] then the result will be: f { b { d: 10 x: 2 } c: [1, 2] } An implementation may provide options to override this default behavior for repeated and message fields. In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below. If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not. As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API.

Considerations for HTTP REST

The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates).

JSON Encoding of Field Masks

In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions. As an example, consider the following message declarations: message Profile { User user = 1; Photo photo = 2; } message User { string display_name = 1; string address = 2; } In proto a field mask for Profile may look as such: mask { paths: "user.display_name" paths: "photo" } In JSON, the same mask is represented as below: { mask: "user.displayName,photo" }

Field Masks and Oneof Fields

Field masks treat fields in oneofs just as regular fields. Consider the following message: message SampleMessage { oneof test_oneof { string name = 4; SubMessage sub_message = 9; } } The field mask can be: mask { paths: "name" } Or: mask { paths: "sub_message" } Note that oneof type names ("test_oneof" in this case) cannot be used in paths.

Field Mask Verification

The implementation of any API method which has a FieldMask type field in the request should verify the included field paths, and return an INVALID_ARGUMENT error if any path is unmappable.

Protobuf type google.protobuf.FieldMask

Wrapper message for float. The JSON representation for FloatValue is JSON number.

Protobuf type google.protobuf.FloatValue

Wrapper message for float. The JSON representation for FloatValue is JSON number.

Protobuf type google.protobuf.FloatValue

All generated protocol message classes extend this class. This class implements most of the Message and Builder interfaces using Java reflection. Users can ignore this class and pretend that generated messages implement the Message interface directly.

Generated message builders for message types that contain extension ranges subclass this.

This class implements type-safe accessors for extensions. They implement all the same operations that you can do with normal fields -- e.g. "get", "set", and "add" -- but for extensions. The extensions are identified using instances of the class GeneratedExtension; the protocol compiler generates a static instance of this class for every extension in its input. Through the magic of generics, all is made type-safe.

For example, imagine you have the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then you might write code like:

MyProto.Foo foo = MyProto.Foo.newBuilder() .setExtension(MyProto.bar, 123) .build();

See also ExtendableMessage.

Generated message classes for message types that contain extension ranges subclass this.

This class implements type-safe accessors for extensions. They implement all the same operations that you can do with normal fields -- e.g. "has", "get", and "getCount" -- but for extensions. The extensions are identified using instances of the class GeneratedExtension; the protocol compiler generates a static instance of this class for every extension in its input. Through the magic of generics, all is made type-safe.

For example, imagine you have the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then you might write code like:

MyProto.Foo foo = getFoo(); int i = foo.getExtension(MyProto.bar);

See also ExtendableBuilder.

Used by subclasses to serialize extensions. Extension ranges may be interleaved with field numbers, but we must write them in canonical (sorted by field number) order. ExtensionWriter helps us write individual ranges of extensions at once.

Users should ignore this class. This class provides the implementation with access to the fields of a message object using Java reflection.

Type used to represent generated extensions. The protocol compiler generates a static singleton instance of this class for each extension.

For example, imagine you have the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then, MyProto.Foo.bar has type GeneratedExtension<MyProto.Foo, Integer>.

In general, users should ignore the details of this type, and simply use these static singletons as parameters to the extension accessors defined in ExtendableMessage and ExtendableBuilder.

Lite version of GeneratedMessage.

A Parser implementation that delegates to the default instance.

For use by generated code only.

Lite equivalent of GeneratedMessage.ExtendableBuilder.

Lite equivalent of GeneratedMessage.ExtendableMessage.

Used by subclasses to serialize extensions. Extension ranges may be interleaved with field numbers, but we must write them in canonical (sorted by field number) order. ExtensionWriter helps us write individual ranges of extensions at once.

Lite equivalent to GeneratedMessage.GeneratedExtension.

Users should ignore the contents of this class and only use objects of this type as parameters to extension accessors and ExtensionRegistry.add().

A serialized (serializable) form of the generated message. Stores the message as a class name and a byte array.

All generated protocol message classes extend this class. This class implements most of the Message and Builder interfaces using Java reflection. Users can ignore this class and pretend that generated messages implement the Message interface directly.

Generated message builders for message types that contain extension ranges subclass this.

This class implements type-safe accessors for extensions. They implement all the same operations that you can do with normal fields -- e.g. "get", "set", and "add" -- but for extensions. The extensions are identified using instances of the class GeneratedExtension; the protocol compiler generates a static instance of this class for every extension in its input. Through the magic of generics, all is made type-safe.

For example, imagine you have the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then you might write code like:

MyProto.Foo foo = MyProto.Foo.newBuilder() .setExtension(MyProto.bar, 123) .build();

See also ExtendableMessage.

Generated message classes for message types that contain extension ranges subclass this.

This class implements type-safe accessors for extensions. They implement all the same operations that you can do with normal fields -- e.g. "has", "get", and "getCount" -- but for extensions. The extensions are identified using instances of the class GeneratedExtension; the protocol compiler generates a static instance of this class for every extension in its input. Through the magic of generics, all is made type-safe.

For example, imagine you have the .proto file:

option java_class = "MyProto";

message Foo { extensions 1000 to max; }

extend Foo { optional int32 bar; }

Then you might write code like:

MyProto.Foo foo = getFoo(); int i = foo.getExtension(MyProto.bar);

See also ExtendableBuilder.

Used by subclasses to serialize extensions. Extension ranges may be interleaved with field numbers, but we must write them in canonical (sorted by field number) order. ExtensionWriter helps us write individual ranges of extensions at once.

Users should ignore this class. This class provides the implementation with access to the fields of a message object using Java reflection.

This class is used to make a generated protected method inaccessible from user's code (e.g., the #newInstance method below). When this class is used as a parameter's type in a generated protected method, the method is visible to user's code in the same package, but since the constructor of this class is private to protobuf runtime, user's code can't obtain an instance of this class and as such can't actually make a method call on the protected method.

Wrapper message for int32. The JSON representation for Int32Value is JSON number.

Protobuf type google.protobuf.Int32Value

Wrapper message for int32. The JSON representation for Int32Value is JSON number.

Protobuf type google.protobuf.Int32Value

Wrapper message for int64. The JSON representation for Int64Value is JSON string.

Protobuf type google.protobuf.Int64Value

Wrapper message for int64. The JSON representation for Int64Value is JSON string.

Protobuf type google.protobuf.Int64Value

The classes contained within are used internally by the Protocol Buffer library and generated message implementations. They are public only because those generated messages do not reside in the protobuf package. Others should not use this class directly.

Provides an immutable view of List around a List.

Protobuf internal. Used in protobuf generated code only.

Wrap around a Map<K, RealValue> and provide a Map<K, V> interface.

LazyField encapsulates the logic of lazily parsing message fields. It stores the message in a ByteString initially and then parses it on-demand.

Most methods are implemented in LazyFieldLite but this class can contain a default instance of the message to provide hashCode(), equals(), and toString().

LazyFieldLite encapsulates the logic of lazily parsing message fields. It stores the message in a ByteString initially and then parses it on-demand.

LazyFieldLite is thread-compatible: concurrent reads are safe once the proto that this LazyFieldLite is a part of is no longer being mutated by its Builder. However, explicit synchronization is needed under read/write situations.

When a LazyFieldLite is used in the context of a MessageLite object, its behavior is considered to be immutable and none of the setter methods in its API are expected to be invoked. All of the getters are expected to be thread-safe. When used in the context of a MessageLite.Builder, setters can be invoked, but there is no guarantee of thread safety.

TODO(yatin,dweis): Consider splitting this class's functionality and put the mutable methods into a separate builder class to allow us to give stronger compile-time guarantees.

This class is internal implementation detail of the protobuf library, so you don't need to use it directly.

An implementation of LazyStringList that wraps an ArrayList. Each element is one of String, ByteString, or byte[]. It caches the last one requested which is most likely the one needed next. This minimizes memory usage while satisfying the most common use cases.

Note that this implementation is not synchronized. If multiple threads access an ArrayList instance concurrently, and at least one of the threads modifies the list structurally, it must be synchronized externally. (A structural modification is any operation that adds or deletes one or more elements, or explicitly resizes the backing array; merely setting the value of an element is not a structural modification.) This is typically accomplished by synchronizing on some object that naturally encapsulates the list.

If the implementation is accessed via concurrent reads, this is thread safe. Conversions are done in a thread safe manner. It's possible that the conversion may happen more than once if two threads attempt to access the same element and the modifications were not visible to each other, but this will not result in any corruption of the list or change in behavior other than performance.

ListValue is a wrapper around a repeated field of values. The JSON representation for ListValue is JSON array.

Protobuf type google.protobuf.ListValue

ListValue is a wrapper around a repeated field of values. The JSON representation for ListValue is JSON array.

Protobuf type google.protobuf.ListValue

Implements MapEntry messages.

In reflection API, map fields will be treated as repeated message fields and each map entry is accessed as a message. This MapEntry class is used to represent these map entry messages in reflection API.

Protobuf internal. Users shouldn't use this class.

Builder to create MapEntry messages.

Implements the lite version of map entry messages.

This class serves as an utility class to help do serialization/parsing of map entries. It's used in generated code and also in the full version MapEntry message.

Protobuf internal. Users shouldn't use.

Internal representation of map fields in generated messages.

This class supports accessing the map field as a Map to be used in generated API and also supports accessing the field as a List to be used in reflection API. It keeps track of where the data is currently stored and do necessary conversions between map and list.

This class is a protobuf implementation detail. Users shouldn't use this class directly.

THREAD-SAFETY NOTE: Read-only access is thread-safe. Users can call getMap() and getList() concurrently in multiple threads. If write-access is needed, all access must be synchronized.

Internal representation of map fields in generated lite-runtime messages.

This class is a protobuf implementation detail. Users shouldn't use this class directly.

Method represents a method of an API interface.

Protobuf type google.protobuf.Method

Method represents a method of an API interface.

Protobuf type google.protobuf.Method

Declares an API Interface to be included in this interface. The including interface must redeclare all the methods from the included interface, but documentation and options are inherited as follows:

• If after comment and whitespace stripping, the documentation string of the redeclared method is empty, it will be inherited from the original method.
• Each annotation belonging to the service config (http, visibility) which is not set in the redeclared method will be inherited.
• If an http annotation is inherited, the path pattern will be modified as follows. Any version prefix will be replaced by the version of the including interface plus the [root][] path if specified. Example of a simple mixin: package google.acl.v1; service AccessControl { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v1/{resource=}:getAcl"; } } package google.storage.v2; service Storage { rpc GetAcl(GetAclRequest) returns (Acl); // Get a data record. rpc GetData(GetDataRequest) returns (Data) { option (google.api.http).get = "/v2/{resource=}"; } } Example of a mixin configuration: apis:
  • name: google.storage.v2.Storage mixins:
    • name: google.acl.v1.AccessControl The mixin construct implies that all methods in AccessControl are also declared with same name and request/response types in Storage. A documentation generator or annotation processor will see the effective Storage.GetAcl method after inheriting documentation and annotations as follows: service Storage { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v2/{resource=**}:getAcl"; } ... } Note how the version in the path pattern changed from v1 to v2. If the root field in the mixin is specified, it should be a relative path under which inherited HTTP paths are placed. Example: apis:
  • name: google.storage.v2.Storage mixins:
    • name: google.acl.v1.AccessControl root: acls This implies the following inherited HTTP annotation: service Storage { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; } ... }

Protobuf type google.protobuf.Mixin

Declares an API Interface to be included in this interface. The including interface must redeclare all the methods from the included interface, but documentation and options are inherited as follows:

• If after comment and whitespace stripping, the documentation string of the redeclared method is empty, it will be inherited from the original method.
• Each annotation belonging to the service config (http, visibility) which is not set in the redeclared method will be inherited.
• If an http annotation is inherited, the path pattern will be modified as follows. Any version prefix will be replaced by the version of the including interface plus the [root][] path if specified. Example of a simple mixin: package google.acl.v1; service AccessControl { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v1/{resource=}:getAcl"; } } package google.storage.v2; service Storage { rpc GetAcl(GetAclRequest) returns (Acl); // Get a data record. rpc GetData(GetDataRequest) returns (Data) { option (google.api.http).get = "/v2/{resource=}"; } } Example of a mixin configuration: apis:
  • name: google.storage.v2.Storage mixins:
    • name: google.acl.v1.AccessControl The mixin construct implies that all methods in AccessControl are also declared with same name and request/response types in Storage. A documentation generator or annotation processor will see the effective Storage.GetAcl method after inheriting documentation and annotations as follows: service Storage { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v2/{resource=**}:getAcl"; } ... } Note how the version in the path pattern changed from v1 to v2. If the root field in the mixin is specified, it should be a relative path under which inherited HTTP paths are placed. Example: apis:
  • name: google.storage.v2.Storage mixins:
    • name: google.acl.v1.AccessControl root: acls This implies the following inherited HTTP annotation: service Storage { // Get the underlying ACL object. rpc GetAcl(GetAclRequest) returns (Acl) { option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; } ... }

Protobuf type google.protobuf.Mixin

A protocol buffer option, which can be attached to a message, field, enumeration, etc.

Protobuf type google.protobuf.Option

A protocol buffer option, which can be attached to a message, field, enumeration, etc.

Protobuf type google.protobuf.Option

RepeatedFieldBuilder implements a structure that a protocol message uses to hold a repeated field of other protocol messages. It supports the classical use case of adding immutable Message's to the repeated field and is highly optimized around this (no extra memory allocations and sharing of immutable arrays).
It also supports the additional use case of adding a Message.Builder to the repeated field and deferring conversion of that Builder to an immutable Message. In this way, it's possible to maintain a tree of Builder's that acts as a fully read/write data structure.
Logically, one can think of a tree of builders as converting the entire tree to messages when build is called on the root or when any method is called that desires a Message instead of a Builder. In terms of the implementation, the SingleFieldBuilder and RepeatedFieldBuilder classes cache messages that were created so that messages only need to be created when some change occurred in its builder or a builder for one of its descendants.

RepeatedFieldBuilderV3 implements a structure that a protocol message uses to hold a repeated field of other protocol messages. It supports the classical use case of adding immutable Message's to the repeated field and is highly optimized around this (no extra memory allocations and sharing of immutable arrays).
It also supports the additional use case of adding a Message.Builder to the repeated field and deferring conversion of that Builder to an immutable Message. In this way, it's possible to maintain a tree of Builder's that acts as a fully read/write data structure.
Logically, one can think of a tree of builders as converting the entire tree to messages when build is called on the root or when any method is called that desires a Message instead of a Builder. In terms of the implementation, the SingleFieldBuilderV3 and RepeatedFieldBuilderV3 classes cache messages that were created so that messages only need to be created when some change occurred in its builder or a builder for one of its descendants.

Grab-bag of utility functions useful when dealing with RPCs.

SingleFieldBuilder implements a structure that a protocol message uses to hold a single field of another protocol message. It supports the classical use case of setting an immutable Message as the value of the field and is highly optimized around this.

It also supports the additional use case of setting a Message.Builder as the field and deferring conversion of that Builder to an immutable Message. In this way, it's possible to maintain a tree of Builder's that acts as a fully read/write data structure.
Logically, one can think of a tree of builders as converting the entire tree to messages when build is called on the root or when any method is called that desires a Message instead of a Builder. In terms of the implementation, the SingleFieldBuilder and RepeatedFieldBuilder classes cache messages that were created so that messages only need to be created when some change occurred in its builder or a builder for one of its descendants.

SingleFieldBuilderV3 implements a structure that a protocol message uses to hold a single field of another protocol message. It supports the classical use case of setting an immutable Message as the value of the field and is highly optimized around this.

It also supports the additional use case of setting a Message.Builder as the field and deferring conversion of that Builder to an immutable Message. In this way, it's possible to maintain a tree of Builder's that acts as a fully read/write data structure.
Logically, one can think of a tree of builders as converting the entire tree to messages when build is called on the root or when any method is called that desires a Message instead of a Builder. In terms of the implementation, the SingleFieldBuilderV3 and RepeatedFieldBuilderV3 classes cache messages that were created so that messages only need to be created when some change occurred in its builder or a builder for one of its descendants.

SourceContext represents information about the source of a protobuf element, like the file in which it is defined.

Protobuf type google.protobuf.SourceContext

SourceContext represents information about the source of a protobuf element, like the file in which it is defined.

Protobuf type google.protobuf.SourceContext

Wrapper message for string. The JSON representation for StringValue is JSON string.

Protobuf type google.protobuf.StringValue

Wrapper message for string. The JSON representation for StringValue is JSON string.

Protobuf type google.protobuf.StringValue

Struct represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language. The JSON representation for Struct is JSON object.

Protobuf type google.protobuf.Struct

Struct represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language. The JSON representation for Struct is JSON object.

Protobuf type google.protobuf.Struct

Provide text parsing and formatting support for proto2 instances. The implementation largely follows google/protobuf/text_format.cc.

Parser for text-format proto2 instances. This class is thread-safe. The implementation largely follows google/protobuf/text_format.cc.

Use TextFormat#getParser() to obtain the default parser, or Builder to control the parser behavior.

Builder that can be used to obtain new instances of Parser.

Helper class for converting protobufs to text.

Data structure which is populated with the locations of each field value parsed from the text.

The locations of primary fields values are retrieved by getLocation or getLocations. The locations of sub message values are within nested TextFormatParseInfoTrees and are retrieve by getNestedTree or getNestedTrees.

The TextFormatParseInfoTree is created by a Builder.

Builder for a TextFormatParseInfoTree.

A location in the source code.

A location is the starting line number and starting column number.

A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a 24-hour linear smear. The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings.

Examples

Example 1: Compute Timestamp from POSIX time(). Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX gettimeofday(). struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime(). FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java System.currentTimeMillis(). long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java Instant.now(). Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime()

JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard toISOString() method. In Python, a standard datetime.datetime object can be converted to this format using strftime with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's ISODateTimeFormat.dateTime() to obtain a formatter capable of generating timestamps in this format.

Protobuf type google.protobuf.Timestamp

A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a 24-hour linear smear. The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings.

Examples

Example 1: Compute Timestamp from POSIX time(). Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX gettimeofday(). struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime(). FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java System.currentTimeMillis(). long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java Instant.now(). Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime()

JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard toISOString() method. In Python, a standard datetime.datetime object can be converted to this format using strftime with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's ISODateTimeFormat.dateTime() to obtain a formatter capable of generating timestamps in this format.

Protobuf type google.protobuf.Timestamp

A protocol buffer message type.

Protobuf type google.protobuf.Type

A protocol buffer message type.

Protobuf type google.protobuf.Type

A TypeRegistry is used to resolve Any messages. You must provide a TypeRegistry containing all message types used in Any message fields.

A Builder is used to build TypeRegistry.

Wrapper message for uint32. The JSON representation for UInt32Value is JSON number.

Protobuf type google.protobuf.UInt32Value

Wrapper message for uint32. The JSON representation for UInt32Value is JSON number.

Protobuf type google.protobuf.UInt32Value

Wrapper message for uint64. The JSON representation for UInt64Value is JSON string.

Protobuf type google.protobuf.UInt64Value

Wrapper message for uint64. The JSON representation for UInt64Value is JSON string.

Protobuf type google.protobuf.UInt64Value

UnknownFieldSet keeps track of fields which were seen when parsing a protocol message but whose field numbers or types are unrecognized. This most frequently occurs when new fields are added to a message type and then messages containing those fields are read by old software that was compiled before the new types were added.

Every Message contains an UnknownFieldSet (and every Message.Builder contains a Builder).

Most users will never need to use this class.

Builder for UnknownFieldSets.

Note that this class maintains Field.Builders for all fields in the set. Thus, adding one element to an existing Field does not require making a copy. This is important for efficient parsing of unknown repeated fields. However, it implies that Fields cannot be constructed independently, nor can two UnknownFieldSets share the same Field object.

Use UnknownFieldSet#newBuilder() to construct a Builder.

Represents a single field in an UnknownFieldSet.

A Field consists of five lists of values. The lists correspond to the five "wire types" used in the protocol buffer binary format. The wire type of each field can be determined from the encoded form alone, without knowing the field's declared type. So, we are able to parse unknown values at least this far and separate them. Normally, only one of the five lists will contain any values, since it is impossible to define a valid message type that declares two different types for the same field number. However, the code is designed to allow for the case where the same unknown field number is encountered using multiple different wire types.

Field is an immutable class. To construct one, you must use a Builder. See Also: UnknownFieldSet

Used to build a Field within an UnknownFieldSet.

Use Field#newBuilder() to construct a Builder.

Parser to implement MessageLite interface.

UnknownFieldSetLite is used to keep track of fields which were seen when parsing a protocol message but whose field numbers or types are unrecognized. This most frequently occurs when new fields are added to a message type and then messages containing those fields are read by old software that was compiled before the new types were added.

For use by generated code only.

An implementation of LazyStringList that wraps another LazyStringList such that it cannot be modified via the wrapper.

Provides a number of unsafe byte operations to be used by advanced applications with high performance requirements. These methods are referred to as "unsafe" due to the fact that they potentially expose the backing buffer of a ByteString to the application.

DISCLAIMER: The methods in this class should only be called if it is guaranteed that the buffer backing the ByteString will never change! Mutation of a ByteString can lead to unexpected and undesirable consequences in your application, and will likely be difficult to debug. Proceed with caution!

This can have a number of significant side affects that have spooky-action-at-a-distance-like behavior. In particular, if the bytes value changes out from under a Protocol Buffer:

• serialization may throw
• serialization may succeed but the wrong bytes may be written out
• messages are no longer threadsafe
• hashCode may be incorrect
  • can result in a permanent memory leak when used as a key in a long-lived HashMap
  • the semantics of many programs may be violated if this is the case

Each of these issues will occur in parts of the code base that are entirely distinct from the parts of the code base modifying the buffer. In fact, both parts of the code base may be correct

• it is the bridging with the unsafe operations that was in error!

Value represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. A producer of value is expected to set one of these variants. Absence of any variant indicates an error. The JSON representation for Value is JSON value.

Protobuf type google.protobuf.Value

Value represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. A producer of value is expected to set one of these variants. Absence of any variant indicates an error. The JSON representation for Value is JSON value.

Protobuf type google.protobuf.Value

This class is used internally by the Protocol Buffer library and generated message implementations. It is public only because those generated messages do not reside in the protobuf package. Others should not use this class directly.

This class contains constants and helper functions useful for dealing with the Protocol Buffer wire format.

Interface for the parent of a Builder that allows the builder to communicate invalidations back to the parent for use when using nested builders.

Interface for an enum which signifies which field in a oneof was specified.

Abstract interface for a blocking RPC channel. BlockingRpcChannel is the blocking equivalent to RpcChannel.

Blocking equivalent to Service.

This interface extends Iterator<Byte>, so that we can return an unboxed byte.

This class should be used by generated code only. When calling FileDescriptor#internalBuildGeneratedFileFrom, the caller provides a callback implementing this interface. The callback is called after the FileDescriptor has been constructed, in order to assign all the global variables defined in the generated code which point at parts of the FileDescriptor. The callback returns an ExtensionRegistry which contains any extensions which might be used in the descriptor -- that is, extensions of the various "Options" messages defined in descriptor.proto. The callback may also return null to indicate that no extensions are used in the descriptor.

This interface is deprecated. Use the return value of internalBuildGeneratedFrom() instead.

TODO(xiaofeng): remove this after b/29368482 is fixed. We need to move this interface to AbstractMessage in order to versioning GeneratedMessage but this move breaks binary compatibility for AppEngine. After AppEngine is fixed we can exclude this from google3.

Lite equivalent of com.google.protobuf.GeneratedMessage.ExtendableMessageOrBuilder.

TODO(xiaofeng): remove this after b/29368482 is fixed. We need to move this interface to AbstractMessage in order to versioning GeneratedMessageV3 but this move breaks binary compatibility for AppEngine. After AppEngine is fixed we can exclude this from google3.

A java.util.List implementation that avoids boxing the elements into Booleans if possible. Does not support null elements.

A java.util.List implementation that avoids boxing the elements into Doubles if possible. Does not support null elements.

Interface for an enum value or value descriptor, to be used in FieldSet. The lite library stores enum values directly in FieldSets but the full library stores EnumValueDescriptors in order to better support reflection.

Interface for an object which maps integers to EnumLites. Descriptors.EnumDescriptor implements this interface by mapping numbers to Descriptors.EnumValueDescriptors. Additionally, every generated enum type has a static method internalGetValueMap() which returns an implementation of this type that maps numbers to enum values.

Interface for an object which verifies integers are in range.

A java.util.List implementation that avoids boxing the elements into Floats if possible. Does not support null elements.

A java.util.List implementation that avoids boxing the elements into Integers if possible. Does not support null elements.

Convert individual elements of the List from F to T.

A java.util.List implementation that avoids boxing the elements into Longs if possible. Does not support null elements.

An interface used to convert between two types.

Extends List to add the capability to make the list immutable and inspect if it is modifiable.

All implementations must support efficient random access.

An interface extending List<String> that also provides access to the items of the list as UTF8-encoded ByteString or byte[] objects. This is used by the protocol buffer implementation to support lazily converting bytes parsed over the wire to String objects until needed and also increases the efficiency of serialization if the String was never requested as the ByteString or byte[] is already cached. The ByteString methods are used in immutable API only and byte[] methods used in mutable API only for they use different representations for string/bytes fields.

Abstract interface implemented by Protocol Message objects.

See also MessageLite, which defines most of the methods that typical users care about. Message adds to it methods that are not available in the "lite" runtime. The biggest added features are introspection and reflection -- i.e., getting descriptors for the message type and accessing the field values dynamically.

Abstract interface implemented by Protocol Message builders.

Abstract interface implemented by Protocol Message objects.

This interface is implemented by all protocol message objects. Non-lite messages additionally implement the Message interface, which is a subclass of MessageLite. Use MessageLite instead when you only need the subset of features which it supports -- namely, nothing that uses descriptors or reflection. You can instruct the protocol compiler to generate classes which implement only MessageLite, not the full Message interface, by adding the follow line to the .proto file:

option optimize_for = LITE_RUNTIME;

This is particularly useful on resource-constrained systems where the full protocol buffers runtime library is too big.

Note that on non-constrained systems (e.g. servers) when you need to link in lots of protocol definitions, a better way to reduce total code footprint is to use optimize_for = CODE_SIZE. This will make the generated code smaller while still supporting all the same features (at the expense of speed). optimize_for = LITE_RUNTIME is best when you only have a small number of message types linked into your binary, in which case the size of the protocol buffers runtime itself is the biggest problem.

Abstract interface implemented by Protocol Message builders.

Base interface for methods common to MessageLite and MessageLite.Builder to provide type equivalency.

Base interface for methods common to Message and Message.Builder to provide type equivalency.

Abstract interface for parsing Protocol Messages.

The implementation should be stateless and thread-safe.

All methods may throw InvalidProtocolBufferException. In the event of invalid data, like an encoding error, the cause of the thrown exception will be null. However, if an I/O problem occurs, an exception is thrown with an java.io.IOException cause.

Interface of useful methods added to all enums generated by the protocol compiler.

An interface extending List<String> used for repeated string fields to provide optional access to the data as a list of ByteStrings. The underlying implementation stores values as either ByteStrings or Strings (see LazyStringArrayList) depending on how the value was initialized or last read, and it is often more efficient to deal with lists of ByteStrings when handling protos that have been deserialized from bytes.

Interface for an RPC callback, normally called when an RPC completes. ParameterType is normally the method's response message type.

Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

Abstract interface for an RPC channel. An RpcChannel represents a communication line to a Service which can be used to call that Service's methods. The Service may be running on another machine. Normally, you should not call an RpcChannel directly, but instead construct a stub Service wrapping it. Example:

RpcChannel channel = rpcImpl.newChannel("remotehost.example.com:1234"); RpcController controller = rpcImpl.newController(); MyService service = MyService.newStub(channel); service.myMethod(controller, request, callback);

Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

An RpcController mediates a single method call. The primary purpose of the controller is to provide a way to manipulate settings specific to the RPC implementation and to find out about RPC-level errors.

Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

The methods provided by the RpcController interface are intended to be a "least common denominator" set of features which we expect all implementations to support. Specific implementations may provide more advanced features (e.g. deadline propagation).

Abstract base interface for protocol-buffer-based RPC services. Services themselves are abstract classes (implemented either by servers or as stubs), but they subclass this base interface. The methods of this interface can be used to call the methods of the service without knowing its exact type at compile time (analogous to the Message interface).

Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

Protobuf enum google.protobuf.FieldDescriptorProto.Label

Protobuf enum google.protobuf.FieldDescriptorProto.Type

Protobuf enum google.protobuf.FieldOptions.CType

Protobuf enum google.protobuf.FieldOptions.JSType

Generated classes can be optimized for speed or code size.

Protobuf enum google.protobuf.FileOptions.OptimizeMode

Is this method side-effect-free (or safe in HTTP parlance), or idempotent, or neither? HTTP based RPC implementation may choose GET verb for safe methods, and PUT verb for idempotent methods instead of the default POST.

Protobuf enum google.protobuf.MethodOptions.IdempotencyLevel

The syntax of the .proto file.

The API type that the extension is used for.

Type of a message extension.

Whether a field is optional, required, or repeated.

Protobuf enum google.protobuf.Field.Cardinality

Basic field types.

Protobuf enum google.protobuf.Field.Kind

Enumeration identifying all relevant type information for a protobuf field.

Defines which method path to invoke in #dynamicMethod(MethodToInvoke, Object...).

For use by generated code only.

Enum that identifies the Java types required to store protobuf fields.

NullValue is a singleton enumeration to represent the null value for the Value type union. The JSON representation for NullValue is JSON null.

Protobuf enum google.protobuf.NullValue

Represents the syntax version of the message.

The syntax in which a protocol buffer element is defined.

Protobuf enum google.protobuf.Syntax

Determines if repeated values for non-repeated fields and oneofs are permitted. For example, given required/optional field "foo" and a oneof containing "baz" and "qux":

• "foo: 1 foo: 2"
• "baz: 1 qux: 2"
• merging "foo: 2" into a proto in which foo is already set, or
• merging "qux: 2" into a proto in which baz is already set.

Lite equivalent to Descriptors.FieldDescriptor.Type. This is only here to support the lite runtime and should not be used by users.

Lite equivalent to Descriptors.FieldDescriptor.JavaType. This is only here to support the lite runtime and should not be used by users.

If you create a CodedOutputStream around a simple flat array, you must not attempt to write more bytes than the array has space. Otherwise, this exception will be thrown.

Thrown when building descriptors fails because the source DescriptorProtos are not valid.

Thrown when a protocol message being parsed is invalid in some way, e.g. it contains a malformed varint or a negative byte length.

Exception indicating that an unexpected wire type was encountered for a field.

Exception thrown when a one-time callback is called more than once.

Thrown by blocking RPC methods when a failure occurs.

Thrown by TextFormat#unescapeBytes and TextFormat#unescapeText when an invalid escape sequence is seen.

Thrown when parsing an invalid text format message.

Thrown when encountering an unknown field while parsing a text format message.

Thrown when attempting to build a protocol message that is missing required fields. This is a RuntimeException because it normally represents a programming error: it happens when some code which constructs a message fails to set all the fields. parseFrom() methods do not throw this; they throw an InvalidProtocolBufferException if required fields are missing, because it is not a programming error to receive an incomplete message. In other words, UninitializedMessageException should never be thrown by correct code, but InvalidProtocolBufferException might be.

Indicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility.

Usage guidelines:

1. This annotation is used only on public API. Internal interfaces should not use it.
2. This annotation should only be added to new APIs. Adding it to an existing API is considered API-breaking.
3. Removing this annotation from an API gives it stable status.