Author: buildbot
Date: Wed Mar 30 20:57:55 2016
New Revision: 984280
Log:
Staging update by buildbot for thrift
Modified:
websites/staging/thrift/trunk/content/ (props changed)
websites/staging/thrift/trunk/content/docs/idl.html
Propchange: websites/staging/thrift/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 30 20:57:55 2016
@@ -1 +1 @@
-1731569
+1737163
Modified: websites/staging/thrift/trunk/content/docs/idl.html
==============================================================================
--- websites/staging/thrift/trunk/content/docs/idl.html (original)
+++ websites/staging/thrift/trunk/content/docs/idl.html Wed Mar 30 20:57:55 2016
@@ -178,7 +178,7 @@ h2:hover > .headerlink, h3:hover > .head
<p>N.B.: The <code>xsd_all</code> keyword has some purpose internal to
Facebook but serves no purpose in Thrift itself. Use of this feature is
strongly discouraged</p>
<h3 id="union">Union<a class="headerlink" href="#union" title="Permanent
link">¶</a></h3>
-<p>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.</p>
+<p>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).</p>
<div class="codehilite"><pre><span class="p">[</span>13<span
class="p">]</span> <span class="n">Union</span> <span
class="p">::=</span> <span class="s">'union'</span> <span
class="n">Identifier</span> <span class="s">'xsd_all'</span>? <span
class="s">'{'</span> <span class="n">Field</span><span
class="o">*</span> <span class="s">'}'</span>
</pre></div>
@@ -207,10 +207,37 @@ h2:hover > .headerlink, h3:hover > .head
<h3 id="field-requiredness">Field Requiredness<a class="headerlink"
href="#field-requiredness" title="Permanent link">¶</a></h3>
+<p>There are two explicit requiredness values, and a third one that is applied
implicity if neither <em>required</em> nor <em>optional</em> are given:
<em>default</em> requiredness.</p>
<div class="codehilite"><pre><span class="p">[</span>18<span
class="p">]</span> <span class="n">FieldReq</span> <span
class="p">::=</span> <span class="s">'required'</span> <span
class="o">|</span> <span class="s">'optional'</span>
</pre></div>
+<p>The general rules for requiredness are as follows:</p>
+<h4 id="required">required<a class="headerlink" href="#required"
title="Permanent link">¶</a></h4>
+<ul>
+<li>Write: Required fields are always written and are expected to be set.</li>
+<li>Read: Required fields are always read and are expected to be contained in
the input stream.</li>
+<li>Defaults values: are always written</li>
+</ul>
+<p>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. </p>
+<p>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.</p>
+<h4 id="optional">optional<a class="headerlink" href="#optional"
title="Permanent link">¶</a></h4>
+<ul>
+<li>Write: Optional fields are only written when they are set</li>
+<li>Read: Optional fields may, or may not be part of the input stream. </li>
+<li>Default values: are written when the isset flag is set</li>
+</ul>
+<p>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. </p>
+<h4 id="default-requiredness-implicit">default requiredness (implicit)<a
class="headerlink" href="#default-requiredness-implicit" title="Permanent
link">¶</a></h4>
+<ul>
+<li>Write: In theory, the fields are always written. There are some exceptions
to that rule, see below.</li>
+<li>Read: Like optional, the field may, or may not be part of the input
stream. </li>
+<li>Default values: may not be written (see next section)</li>
+</ul>
+<p>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.</p>
+<h4 id="semantics-of-default-values">Semantics of Default Values<a
class="headerlink" href="#semantics-of-default-values" title="Permanent
link">¶</a></h4>
+<p>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. </p>
+<p>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.</p>
<h3 id="xsd-options">XSD Options<a class="headerlink" href="#xsd-options"
title="Permanent link">¶</a></h3>
<p>N.B.: These have some internal purpose at Facebook but serve no current
purpose in Thrift. Use of these options is strongly discouraged.</p>
<div class="codehilite"><pre><span class="p">[</span>19<span
class="p">]</span> <span class="n">XsdFieldOptions</span> <span
class="p">::=</span> <span class="s">'xsd_optional'</span>? <span
class="s">'xsd_nillable'</span>? <span class="n">XsdAttrs</span>?
