opwvhk commented on a change in pull request #1411:
URL: https://github.com/apache/avro/pull/1411#discussion_r764192266
##########
File path:
lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
##########
@@ -90,6 +90,7 @@ import org.apache.commons.lang3.StringEscapeUtils;
*/
public class Idl implements Closeable {
static JsonNodeFactory FACTORY = JsonNodeFactory.instance;
+ private static final String OPTIONAL_NULLABLE_TYPE_PROPERTY =
"org.apache.avro.compiler.idl.Idl.NullableType.optional";
Review comment:
This field is used as marker: `NullableType()` adds it, and
`fixOptionalSchema` _always_ removes it.
##########
File path: doc/src/content/xdocs/idl.xml
##########
@@ -301,17 +301,36 @@ record Card {
<section id="unions">
<title>Unions</title>
<p>Union types are denoted as <code>union { typeA, typeB, typeC, ...
}</code>. For example,
- this record contains a string field that is optional (unioned with
<code>null</code>):
+ this record contains a string field that is optional (unioned with
<code>null</code>), and
+ a field containing either a precise or a imprecise number:
</p>
<source>
record RecordWithUnion {
union { null, string } optionalString;
+ union { decimal(12, 6), float } number;
}
</source>
<p>
Note that the same restrictions apply to Avro IDL unions as apply
to unions defined in the
- JSON format; namely, a record may not contain multiple elements of
the same type.
+ JSON format; namely, a record may not contain multiple elements of
the same type. Also,
+ fields/parameters that use the union type and have a default
parameter must specify a
+ default value of the same type as the <em>first</em>em> union type.
</p>
+ <p>Because it occurs so often, there is a special shorthand to
denote a union of
+ <code>null</code> with another type. In the following snippet, the
first three fields have
+ identical types:
+ </p>
+ <source>
+record RecordWithUnion {
+ union { null, string } optionalString1 = null;
+ string? optionalString2 = null;
+ string? optionalString3; // No default value
+ string? optionalString4 = "something";
+}
+ </source>
+ <p>Note that unlike explicit unions, the position of the
<code>null</code> type is fluid; it will be
+ the first or last type depending on the default value (if any). So
in the example above, all fields
+ are valid.</p>
Review comment:
These last two fields and the "fluid" unions are a recent addition; this
makes the '?' syntax more useful.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
