khenaidoo | d948f77 | 2021-08-11 17:49:24 -0400 | [diff] [blame] | 1 | // Copyright 2018 The Go Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style |
| 3 | // license that can be found in the LICENSE file. |
| 4 | |
| 5 | package protoreflect |
| 6 | |
| 7 | import "google.golang.org/protobuf/encoding/protowire" |
| 8 | |
| 9 | // Enum is a reflection interface for a concrete enum value, |
| 10 | // which provides type information and a getter for the enum number. |
| 11 | // Enum does not provide a mutable API since enums are commonly backed by |
| 12 | // Go constants, which are not addressable. |
| 13 | type Enum interface { |
| 14 | // Descriptor returns enum descriptor, which contains only the protobuf |
| 15 | // type information for the enum. |
| 16 | Descriptor() EnumDescriptor |
| 17 | |
| 18 | // Type returns the enum type, which encapsulates both Go and protobuf |
| 19 | // type information. If the Go type information is not needed, |
| 20 | // it is recommended that the enum descriptor be used instead. |
| 21 | Type() EnumType |
| 22 | |
| 23 | // Number returns the enum value as an integer. |
| 24 | Number() EnumNumber |
| 25 | } |
| 26 | |
| 27 | // Message is a reflective interface for a concrete message value, |
| 28 | // encapsulating both type and value information for the message. |
| 29 | // |
| 30 | // Accessor/mutators for individual fields are keyed by FieldDescriptor. |
| 31 | // For non-extension fields, the descriptor must exactly match the |
| 32 | // field known by the parent message. |
| 33 | // For extension fields, the descriptor must implement ExtensionTypeDescriptor, |
| 34 | // extend the parent message (i.e., have the same message FullName), and |
| 35 | // be within the parent's extension range. |
| 36 | // |
| 37 | // Each field Value can be a scalar or a composite type (Message, List, or Map). |
| 38 | // See Value for the Go types associated with a FieldDescriptor. |
| 39 | // Providing a Value that is invalid or of an incorrect type panics. |
| 40 | type Message interface { |
| 41 | // Descriptor returns message descriptor, which contains only the protobuf |
| 42 | // type information for the message. |
| 43 | Descriptor() MessageDescriptor |
| 44 | |
| 45 | // Type returns the message type, which encapsulates both Go and protobuf |
| 46 | // type information. If the Go type information is not needed, |
| 47 | // it is recommended that the message descriptor be used instead. |
| 48 | Type() MessageType |
| 49 | |
| 50 | // New returns a newly allocated and mutable empty message. |
| 51 | New() Message |
| 52 | |
| 53 | // Interface unwraps the message reflection interface and |
| 54 | // returns the underlying ProtoMessage interface. |
| 55 | Interface() ProtoMessage |
| 56 | |
| 57 | // Range iterates over every populated field in an undefined order, |
| 58 | // calling f for each field descriptor and value encountered. |
| 59 | // Range returns immediately if f returns false. |
| 60 | // While iterating, mutating operations may only be performed |
| 61 | // on the current field descriptor. |
| 62 | Range(f func(FieldDescriptor, Value) bool) |
| 63 | |
| 64 | // Has reports whether a field is populated. |
| 65 | // |
| 66 | // Some fields have the property of nullability where it is possible to |
| 67 | // distinguish between the default value of a field and whether the field |
| 68 | // was explicitly populated with the default value. Singular message fields, |
| 69 | // member fields of a oneof, and proto2 scalar fields are nullable. Such |
| 70 | // fields are populated only if explicitly set. |
| 71 | // |
| 72 | // In other cases (aside from the nullable cases above), |
| 73 | // a proto3 scalar field is populated if it contains a non-zero value, and |
| 74 | // a repeated field is populated if it is non-empty. |
| 75 | Has(FieldDescriptor) bool |
| 76 | |
| 77 | // Clear clears the field such that a subsequent Has call reports false. |
| 78 | // |
| 79 | // Clearing an extension field clears both the extension type and value |
| 80 | // associated with the given field number. |
| 81 | // |
| 82 | // Clear is a mutating operation and unsafe for concurrent use. |
| 83 | Clear(FieldDescriptor) |
| 84 | |
| 85 | // Get retrieves the value for a field. |
| 86 | // |
| 87 | // For unpopulated scalars, it returns the default value, where |
| 88 | // the default value of a bytes scalar is guaranteed to be a copy. |
| 89 | // For unpopulated composite types, it returns an empty, read-only view |
| 90 | // of the value; to obtain a mutable reference, use Mutable. |
| 91 | Get(FieldDescriptor) Value |
| 92 | |
| 93 | // Set stores the value for a field. |
| 94 | // |
| 95 | // For a field belonging to a oneof, it implicitly clears any other field |
| 96 | // that may be currently set within the same oneof. |
| 97 | // For extension fields, it implicitly stores the provided ExtensionType. |
| 98 | // When setting a composite type, it is unspecified whether the stored value |
| 99 | // aliases the source's memory in any way. If the composite value is an |
| 100 | // empty, read-only value, then it panics. |
| 101 | // |
| 102 | // Set is a mutating operation and unsafe for concurrent use. |
| 103 | Set(FieldDescriptor, Value) |
| 104 | |
| 105 | // Mutable returns a mutable reference to a composite type. |
| 106 | // |
| 107 | // If the field is unpopulated, it may allocate a composite value. |
| 108 | // For a field belonging to a oneof, it implicitly clears any other field |
| 109 | // that may be currently set within the same oneof. |
| 110 | // For extension fields, it implicitly stores the provided ExtensionType |
| 111 | // if not already stored. |
| 112 | // It panics if the field does not contain a composite type. |
| 113 | // |
| 114 | // Mutable is a mutating operation and unsafe for concurrent use. |
| 115 | Mutable(FieldDescriptor) Value |
| 116 | |
| 117 | // NewField returns a new value that is assignable to the field |
| 118 | // for the given descriptor. For scalars, this returns the default value. |
| 119 | // For lists, maps, and messages, this returns a new, empty, mutable value. |
| 120 | NewField(FieldDescriptor) Value |
| 121 | |
| 122 | // WhichOneof reports which field within the oneof is populated, |
| 123 | // returning nil if none are populated. |
| 124 | // It panics if the oneof descriptor does not belong to this message. |
| 125 | WhichOneof(OneofDescriptor) FieldDescriptor |
| 126 | |
| 127 | // GetUnknown retrieves the entire list of unknown fields. |
| 128 | // The caller may only mutate the contents of the RawFields |
| 129 | // if the mutated bytes are stored back into the message with SetUnknown. |
| 130 | GetUnknown() RawFields |
| 131 | |
| 132 | // SetUnknown stores an entire list of unknown fields. |
| 133 | // The raw fields must be syntactically valid according to the wire format. |
| 134 | // An implementation may panic if this is not the case. |
| 135 | // Once stored, the caller must not mutate the content of the RawFields. |
| 136 | // An empty RawFields may be passed to clear the fields. |
| 137 | // |
| 138 | // SetUnknown is a mutating operation and unsafe for concurrent use. |
| 139 | SetUnknown(RawFields) |
| 140 | |
| 141 | // IsValid reports whether the message is valid. |
| 142 | // |
| 143 | // An invalid message is an empty, read-only value. |
| 144 | // |
| 145 | // An invalid message often corresponds to a nil pointer of the concrete |
| 146 | // message type, but the details are implementation dependent. |
| 147 | // Validity is not part of the protobuf data model, and may not |
| 148 | // be preserved in marshaling or other operations. |
| 149 | IsValid() bool |
| 150 | |
| 151 | // ProtoMethods returns optional fast-path implementions of various operations. |
| 152 | // This method may return nil. |
| 153 | // |
| 154 | // The returned methods type is identical to |
| 155 | // "google.golang.org/protobuf/runtime/protoiface".Methods. |
| 156 | // Consult the protoiface package documentation for details. |
| 157 | ProtoMethods() *methods |
| 158 | } |
| 159 | |
| 160 | // RawFields is the raw bytes for an ordered sequence of fields. |
| 161 | // Each field contains both the tag (representing field number and wire type), |
| 162 | // and also the wire data itself. |
| 163 | type RawFields []byte |
| 164 | |
| 165 | // IsValid reports whether b is syntactically correct wire format. |
| 166 | func (b RawFields) IsValid() bool { |
| 167 | for len(b) > 0 { |
| 168 | _, _, n := protowire.ConsumeField(b) |
| 169 | if n < 0 { |
| 170 | return false |
| 171 | } |
| 172 | b = b[n:] |
| 173 | } |
| 174 | return true |
| 175 | } |
| 176 | |
| 177 | // List is a zero-indexed, ordered list. |
| 178 | // The element Value type is determined by FieldDescriptor.Kind. |
| 179 | // Providing a Value that is invalid or of an incorrect type panics. |
| 180 | type List interface { |
| 181 | // Len reports the number of entries in the List. |
| 182 | // Get, Set, and Truncate panic with out of bound indexes. |
| 183 | Len() int |
| 184 | |
| 185 | // Get retrieves the value at the given index. |
| 186 | // It never returns an invalid value. |
| 187 | Get(int) Value |
| 188 | |
| 189 | // Set stores a value for the given index. |
| 190 | // When setting a composite type, it is unspecified whether the set |
| 191 | // value aliases the source's memory in any way. |
| 192 | // |
| 193 | // Set is a mutating operation and unsafe for concurrent use. |
| 194 | Set(int, Value) |
| 195 | |
| 196 | // Append appends the provided value to the end of the list. |
| 197 | // When appending a composite type, it is unspecified whether the appended |
| 198 | // value aliases the source's memory in any way. |
| 199 | // |
| 200 | // Append is a mutating operation and unsafe for concurrent use. |
| 201 | Append(Value) |
| 202 | |
| 203 | // AppendMutable appends a new, empty, mutable message value to the end |
| 204 | // of the list and returns it. |
| 205 | // It panics if the list does not contain a message type. |
| 206 | AppendMutable() Value |
| 207 | |
| 208 | // Truncate truncates the list to a smaller length. |
| 209 | // |
| 210 | // Truncate is a mutating operation and unsafe for concurrent use. |
| 211 | Truncate(int) |
| 212 | |
| 213 | // NewElement returns a new value for a list element. |
| 214 | // For enums, this returns the first enum value. |
| 215 | // For other scalars, this returns the zero value. |
| 216 | // For messages, this returns a new, empty, mutable value. |
| 217 | NewElement() Value |
| 218 | |
| 219 | // IsValid reports whether the list is valid. |
| 220 | // |
| 221 | // An invalid list is an empty, read-only value. |
| 222 | // |
| 223 | // Validity is not part of the protobuf data model, and may not |
| 224 | // be preserved in marshaling or other operations. |
| 225 | IsValid() bool |
| 226 | } |
| 227 | |
| 228 | // Map is an unordered, associative map. |
| 229 | // The entry MapKey type is determined by FieldDescriptor.MapKey.Kind. |
| 230 | // The entry Value type is determined by FieldDescriptor.MapValue.Kind. |
| 231 | // Providing a MapKey or Value that is invalid or of an incorrect type panics. |
| 232 | type Map interface { |
| 233 | // Len reports the number of elements in the map. |
| 234 | Len() int |
| 235 | |
| 236 | // Range iterates over every map entry in an undefined order, |
| 237 | // calling f for each key and value encountered. |
| 238 | // Range calls f Len times unless f returns false, which stops iteration. |
| 239 | // While iterating, mutating operations may only be performed |
| 240 | // on the current map key. |
| 241 | Range(f func(MapKey, Value) bool) |
| 242 | |
| 243 | // Has reports whether an entry with the given key is in the map. |
| 244 | Has(MapKey) bool |
| 245 | |
| 246 | // Clear clears the entry associated with they given key. |
| 247 | // The operation does nothing if there is no entry associated with the key. |
| 248 | // |
| 249 | // Clear is a mutating operation and unsafe for concurrent use. |
| 250 | Clear(MapKey) |
| 251 | |
| 252 | // Get retrieves the value for an entry with the given key. |
| 253 | // It returns an invalid value for non-existent entries. |
| 254 | Get(MapKey) Value |
| 255 | |
| 256 | // Set stores the value for an entry with the given key. |
| 257 | // It panics when given a key or value that is invalid or the wrong type. |
| 258 | // When setting a composite type, it is unspecified whether the set |
| 259 | // value aliases the source's memory in any way. |
| 260 | // |
| 261 | // Set is a mutating operation and unsafe for concurrent use. |
| 262 | Set(MapKey, Value) |
| 263 | |
| 264 | // Mutable retrieves a mutable reference to the entry for the given key. |
| 265 | // If no entry exists for the key, it creates a new, empty, mutable value |
| 266 | // and stores it as the entry for the key. |
| 267 | // It panics if the map value is not a message. |
| 268 | Mutable(MapKey) Value |
| 269 | |
| 270 | // NewValue returns a new value assignable as a map value. |
| 271 | // For enums, this returns the first enum value. |
| 272 | // For other scalars, this returns the zero value. |
| 273 | // For messages, this returns a new, empty, mutable value. |
| 274 | NewValue() Value |
| 275 | |
| 276 | // IsValid reports whether the map is valid. |
| 277 | // |
| 278 | // An invalid map is an empty, read-only value. |
| 279 | // |
| 280 | // An invalid message often corresponds to a nil Go map value, |
| 281 | // but the details are implementation dependent. |
| 282 | // Validity is not part of the protobuf data model, and may not |
| 283 | // be preserved in marshaling or other operations. |
| 284 | IsValid() bool |
| 285 | } |