aboutsummaryrefslogtreecommitdiff
path: root/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
diff options
context:
space:
mode:
authorJon Skeet <jonskeet@google.com>2015-11-06 18:38:31 +0000
committerJon Skeet <jonskeet@google.com>2015-11-06 18:38:31 +0000
commitcff900e8f9e4b8f3a8f314f0f44eab222ebb870b (patch)
tree9bb37e2e6639faa7c020caaccc918e7f81ac844c /csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
parentf4f601bd477e01c98d95dece5a694107205a8134 (diff)
downloadprotobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.tar.gz
protobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.tar.bz2
protobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.zip
Generated code for previous commit.
Diffstat (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs')
-rw-r--r--csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs26
1 files changed, 26 insertions, 0 deletions
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
index 33c814ef..e71e4af6 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
@@ -42,19 +42,25 @@ namespace Google.Protobuf.WellKnownTypes {
#region Messages
/// <summary>
/// `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 {
@@ -64,20 +70,25 @@ namespace Google.Protobuf.WellKnownTypes {
/// y : 13
/// }
/// z: 8
+ ///
/// The result will not contain specific values for fields x,y and z
/// (there 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
/// field mask.
+ ///
/// 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 applies 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
@@ -87,18 +98,22 @@ namespace Google.Protobuf.WellKnownTypes {
/// 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.
+ ///
/// 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
@@ -106,19 +121,26 @@ namespace Google.Protobuf.WellKnownTypes {
/// 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;
@@ -127,12 +149,16 @@ namespace Google.Protobuf.WellKnownTypes {
/// 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"
/// }