OLD | NEW |
1 // Protocol Buffers - Google's data interchange format | 1 // Protocol Buffers - Google's data interchange format |
2 // Copyright 2008 Google Inc. All rights reserved. | 2 // Copyright 2008 Google Inc. All rights reserved. |
3 // https://developers.google.com/protocol-buffers/ | 3 // https://developers.google.com/protocol-buffers/ |
4 // | 4 // |
5 // Redistribution and use in source and binary forms, with or without | 5 // Redistribution and use in source and binary forms, with or without |
6 // modification, are permitted provided that the following conditions are | 6 // modification, are permitted provided that the following conditions are |
7 // met: | 7 // met: |
8 // | 8 // |
9 // * Redistributions of source code must retain the above copyright | 9 // * Redistributions of source code must retain the above copyright |
10 // notice, this list of conditions and the following disclaimer. | 10 // notice, this list of conditions and the following disclaimer. |
(...skipping 19 matching lines...) Expand all Loading... |
30 | 30 |
31 syntax = "proto3"; | 31 syntax = "proto3"; |
32 | 32 |
33 package google.protobuf; | 33 package google.protobuf; |
34 | 34 |
35 option csharp_namespace = "Google.Protobuf.WellKnownTypes"; | 35 option csharp_namespace = "Google.Protobuf.WellKnownTypes"; |
36 option java_package = "com.google.protobuf"; | 36 option java_package = "com.google.protobuf"; |
37 option java_outer_classname = "FieldMaskProto"; | 37 option java_outer_classname = "FieldMaskProto"; |
38 option java_multiple_files = true; | 38 option java_multiple_files = true; |
39 option objc_class_prefix = "GPB"; | 39 option objc_class_prefix = "GPB"; |
40 option go_package = "google.golang.org/genproto/protobuf/field_mask;field_mask"; | 40 option java_generate_equals_and_hash = true; |
41 | 41 |
42 // `FieldMask` represents a set of symbolic field paths, for example: | 42 // `FieldMask` represents a set of symbolic field paths, for example: |
43 // | 43 // |
44 // paths: "f.a" | 44 // paths: "f.a" |
45 // paths: "f.b.d" | 45 // paths: "f.b.d" |
46 // | 46 // |
47 // Here `f` represents a field in some root message, `a` and `b` | 47 // Here `f` represents a field in some root message, `a` and `b` |
48 // fields in the message found in `f`, and `d` a field found in the | 48 // fields in the message found in `f`, and `d` a field found in the |
49 // message in `f.b`. | 49 // message in `f.b`. |
50 // | 50 // |
(...skipping 24 matching lines...) Expand all Loading... |
75 // | 75 // |
76 // | 76 // |
77 // f { | 77 // f { |
78 // a : 22 | 78 // a : 22 |
79 // b { | 79 // b { |
80 // d : 1 | 80 // d : 1 |
81 // } | 81 // } |
82 // } | 82 // } |
83 // | 83 // |
84 // A repeated field is not allowed except at the last position of a | 84 // A repeated field is not allowed except at the last position of a |
85 // paths string. | 85 // field mask. |
86 // | 86 // |
87 // If a FieldMask object is not present in a get operation, the | 87 // If a FieldMask object is not present in a get operation, the |
88 // operation applies to all fields (as if a FieldMask of all fields | 88 // operation applies to all fields (as if a FieldMask of all fields |
89 // had been specified). | 89 // had been specified). |
90 // | 90 // |
91 // Note that a field mask does not necessarily apply to the | 91 // Note that a field mask does not necessarily apply to the |
92 // top-level response message. In case of a REST get operation, the | 92 // top-level response message. In case of a REST get operation, the |
93 // field mask applies directly to the response, but in case of a REST | 93 // field mask applies directly to the response, but in case of a REST |
94 // list operation, the mask instead applies to each individual message | 94 // list operation, the mask instead applies to each individual message |
95 // in the returned resource list. In case of a REST custom method, | 95 // in the returned resource list. In case of a REST custom method, |
96 // other definitions may be used. Where the mask applies will be | 96 // other definitions may be used. Where the mask applies will be |
97 // clearly documented together with its declaration in the API. In | 97 // clearly documented together with its declaration in the API. In |
98 // any case, the effect on the returned resource/resources is required | 98 // any case, the effect on the returned resource/resources is required |
99 // behavior for APIs. | 99 // behavior for APIs. |
100 // | 100 // |
101 // # Field Masks in Update Operations | 101 // # Field Masks in Update Operations |
102 // | 102 // |
103 // A field mask in update operations specifies which fields of the | 103 // A field mask in update operations specifies which fields of the |
104 // targeted resource are going to be updated. The API is required | 104 // targeted resource are going to be updated. The API is required |
105 // to only change the values of the fields as specified in the mask | 105 // to only change the values of the fields as specified in the mask |
106 // and leave the others untouched. If a resource is passed in to | 106 // and leave the others untouched. If a resource is passed in to |
107 // describe the updated values, the API ignores the values of all | 107 // describe the updated values, the API ignores the values of all |
108 // fields not covered by the mask. | 108 // fields not covered by the mask. |
109 // | 109 // |
110 // If a repeated field is specified for an update operation, the existing | |
111 // repeated values in the target resource will be overwritten by the new values. | |
112 // Note that a repeated field is only allowed in the last position of a `paths` | |
113 // string. | |
114 // | |
115 // If a sub-message is specified in the last position of the field mask for an | |
116 // update operation, then the existing sub-message in the target resource is | |
117 // overwritten. Given the target message: | |
118 // | |
119 // f { | |
120 // b { | |
121 // d : 1 | |
122 // x : 2 | |
123 // } | |
124 // c : 1 | |
125 // } | |
126 // | |
127 // And an update message: | |
128 // | |
129 // f { | |
130 // b { | |
131 // d : 10 | |
132 // } | |
133 // } | |
134 // | |
135 // then if the field mask is: | |
136 // | |
137 // paths: "f.b" | |
138 // | |
139 // then the result will be: | |
140 // | |
141 // f { | |
142 // b { | |
143 // d : 10 | |
144 // } | |
145 // c : 1 | |
146 // } | |
147 // | |
148 // However, if the update mask was: | |
149 // | |
150 // paths: "f.b.d" | |
151 // | |
152 // then the result would be: | |
153 // | |
154 // f { | |
155 // b { | |
156 // d : 10 | |
157 // x : 2 | |
158 // } | |
159 // c : 1 | |
160 // } | |
161 // | |
162 // In order to reset a field's value to the default, the field must | 110 // In order to reset a field's value to the default, the field must |
163 // be in the mask and set to the default value in the provided resource. | 111 // be in the mask and set to the default value in the provided resource. |
164 // Hence, in order to reset all fields of a resource, provide a default | 112 // Hence, in order to reset all fields of a resource, provide a default |
165 // instance of the resource and set all fields in the mask, or do | 113 // instance of the resource and set all fields in the mask, or do |
166 // not provide a mask as described below. | 114 // not provide a mask as described below. |
167 // | 115 // |
168 // If a field mask is not present on update, the operation applies to | 116 // If a field mask is not present on update, the operation applies to |
169 // all fields (as if a field mask of all fields has been specified). | 117 // all fields (as if a field mask of all fields has been specified). |
170 // Note that in the presence of schema evolution, this may mean that | 118 // Note that in the presence of schema evolution, this may mean that |
171 // fields the client does not know and has therefore not filled into | 119 // fields the client does not know and has therefore not filled into |
(...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
237 // mask { | 185 // mask { |
238 // paths: "sub_message" | 186 // paths: "sub_message" |
239 // } | 187 // } |
240 // | 188 // |
241 // Note that oneof type names ("test_oneof" in this case) cannot be used in | 189 // Note that oneof type names ("test_oneof" in this case) cannot be used in |
242 // paths. | 190 // paths. |
243 message FieldMask { | 191 message FieldMask { |
244 // The set of field mask paths. | 192 // The set of field mask paths. |
245 repeated string paths = 1; | 193 repeated string paths = 1; |
246 } | 194 } |
OLD | NEW |