[
https://issues.apache.org/jira/browse/THRIFT-3756?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15218786#comment-15218786
]
ASF GitHub Bot commented on THRIFT-3756:
----------------------------------------
Github user Jens-G commented on a diff in the pull request:
https://github.com/apache/thrift/pull/961#discussion_r57957660
--- Diff: doc/specs/idl.md ---
@@ -126,8 +126,39 @@ A service provides the interface for a set of
functionality provided by a Thrift
### Field Requiredness
- [18] FieldReq ::= 'required' | 'optional'
+There are two explicit requiredness values, and a third one that is
applied implicity if neither *required* nor *optional* are given: *default*
requiredness.
+ [18] FieldReq ::= 'required' | 'optional'
+
+The general rules for requiredness are as follows:
+
+#### required
+
+- Write: Required fields are always written and are expected to be set.
+- Read: Required fields are always read and are expected to be contained
in the input stream.
+- Defaults values: are always written
+
+If a required field is missing during read, the expected behaviour is to
indicate an unsuccessful read operation to the caller, e.g. by throwing an
exception or returning an error.
+
+Because of this behaviour, required fields drastically limit the options
with regard to soft versioning. Because they must be present on read, the
fields cannot be deprecated. If a required field would be removed (or changed
to optional), the data are no longer compatible between versions.
+
+#### optional
+
+- Write: Optional fields are only written when they are set
+- Read: Optional fields may, or may not be part of the input stream.
+- Default values: are written when the isset flag is set
+
+Most language implementations use the recommended pratice of so-called
"isset" flags to indicate whether a particular optional field is set or not.
Only fields with this flag set are written, and conversely the flag is only set
when a field value has been read from the input stream.
+
+#### default requiredness (implicit)
+
+- Write: Like required, the fields are always written.
+- Read: Like optional, the field may, or may not be part of the input
stream.
+- Default values: may not be written
--- End diff --
Actually it is a "may", but you hit an interesting point. There are some
lengthy discussions in JIRA about the semantics of optional fields, so I tried
to reflect the current status quo here. There are arguments for both, whether
an default value should be written or not, and at the very end this depends on
how "default value" in the Thrift context should be defined. If it means that
the value is assigned by default, then the only difference would be how the
field is set. But if "default" implies that any value that equals the default
should be omitted during serialization, that's something completely different.
From my understanding, the latter is not really implemented anywhere (think of
a default value consisting of a struct that contains a list of structs which
...) so for the sake of having one clear definition, I assume the former, much
easier semantics is the one intended by the inventor. I admit that I took a bit
of freedom here. I will add a note to at least point out that this topic is
still not finally settled.
More information here:
- https://issues.apache.org/jira/browse/THRIFT-2429
- https://issues.apache.org/jira/browse/THRIFT-1528
- http://lionet.info/asn1c/blog/2010/07/18/thrift-semantics/
> Improve requiredness documentation
> ----------------------------------
>
> Key: THRIFT-3756
> URL: https://issues.apache.org/jira/browse/THRIFT-3756
> Project: Thrift
> Issue Type: Improvement
> Components: Documentation, Website
> Reporter: Jens Geyer
> Assignee: Jens Geyer
> Priority: Minor
>
> The documentation on the Apache Thrift web site regarding requiredness is
> very minorish (that's an euphemism) and needs to be improved.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
