[
https://issues.apache.org/jira/browse/THRIFT-3756?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15213671#comment-15213671
]
ASF GitHub Bot commented on THRIFT-3756:
----------------------------------------
Github user jsirois commented on a diff in the pull request:
https://github.com/apache/thrift/pull/961#discussion_r57536860
--- 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.
--- End diff --
This also seems misleading. I added commentary on
https://issues.apache.org/jira/browse/THRIFT-3752, but the java generator, for
example, only emits default requiredness collections when they are non-null;
which seems like the only thing to do in order for the read-side of the wire to
correctly interpret the field as not set (unless there were a special
byte-sequence in the protocol for indicating unset or null). As such, this
language seems misleading to me. Perhaps something like: "Write: Fields that
are set are always written" ?
> 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)
