thrift git commit: THRIFT-3756 Improve requiredness documentation Client: Website Patch: Jens Geyer

[je...@apache.org]

Repository: thrift
Updated Branches:
  refs/heads/master 3bf5bf993 -> fe9222a6e


THRIFT-3756 Improve requiredness documentation
Client: Website
Patch: Jens Geyer

This closes #961


Project: http://git-wip-us.apache.org/repos/asf/thrift/repo
Commit: http://git-wip-us.apache.org/repos/asf/thrift/commit/fe9222a6
Tree: http://git-wip-us.apache.org/repos/asf/thrift/tree/fe9222a6
Diff: http://git-wip-us.apache.org/repos/asf/thrift/diff/fe9222a6

Branch: refs/heads/master
Commit: fe9222a6ec20d23d9cfd3ec9c793887f7212b313
Parents: 3bf5bf9
Author: Jens Geyer <je...@apache.org>
Authored: Thu Mar 24 00:33:06 2016 +0200
Committer: Jens Geyer <je...@apache.org>
Committed: Wed Mar 30 22:43:56 2016 +0200

----------------------------------------------------------------------
 doc/specs/idl.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/thrift/blob/fe9222a6/doc/specs/idl.md
----------------------------------------------------------------------
diff --git a/doc/specs/idl.md b/doc/specs/idl.md
index e8cf39f..b7eb23c 100644
--- a/doc/specs/idl.md
+++ b/doc/specs/idl.md
@@ -98,7 +98,7 @@ N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no
 
 ### Union
 
-Unions are similar to structs, except that they provide a means to transport exactly one field of a possible set of fields, just like union {} in C++. Consequently, union members cannot be required fields.
+Unions are similar to structs, except that they provide a means to transport exactly one field of a possible set of fields, just like union {} in C++. Consequently, union members are implicitly considered optional (see requiredness).
 
     [13] Union          ::=  'union' Identifier 'xsd_all'? '{' Field* '}'
 
@@ -126,7 +126,43 @@ 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: In theory, the fields are always written. There are some exceptions to that rule, see below.
+- Read: Like optional, the field may, or may not be part of the input stream. 
+- Default values: may not be written (see next section)
+
+Default requiredess is a good starting point. The desired behaviour is a mix of optional and required, hence the internal name "opt-in, req-out". Although in theory these fields are supposed to be written ("req-out"), in reality unset fields are not always written. This is especially the case, when the field contains a <null> value, which by definition cannot be transported through thrift. The only way to achieve this is by not writing that field at all, and that's what most languages do.
+	
+#### Semantics of Default Values
+
+There are ongoing discussions about that topic, see JIRA for details. Not all implementations treat default values in the very same way, but the current status quo is more or less that default fields are typically set at initialization time. Therefore, a value that equals the default may not be written, because the read end will set the value implicitly. On the other hand, an implementation is free to write the default value anyways, as there is no hard restriction that prevents this. 
+
+The major point to keep in mind here is the fact, that any unwritten default value implicitly becomes part of the interface version. If that default is changed, the interface changes. If, in contrast, the default value is written into the output data, the default in the IDL can change at any time without affecting serialized data.
 
 ### XSD Options