Handling nulls in message maps
A message might contain fields that can carry a specific out-of-range value. This is distinct from the field being empty. Such values are termed nil or null, and the field is said to be nillable or nullable.
About this task
The logical message tree supports the concept of out-of-range values by using one of two techniques, depending on the data format:
- For XML, the schema model allows for elements to be defined as nillable to indicate that they support an out-of-range null value. An XML element in a document is identified as being nilled, representing the null value, by having a xsi:nil attribute with the value true. The XMLNSC parser logical tree for a nilled element has an empty value and a child attribute set to xsi:nil, with the value true. For elements that are not defined as nillable, it is not possible to distinguish between having an empty value or the null value.
- For other text and binary messages that are modeled with a DFDL schema or MRM message set, elements can also be defined as nillable to indicate that they support an out-of-range value. In the message bit stream, a reserved value is identified to indicate the nullable state. The DFDL and MRM parsers logical tree for a nilled element have the value set to the special value NULL.
- For JSON messages, JSON objects and JSON arrays implicitly support the JSON null value to indicate that they support an out-of-range value. In JSON, data has a special value that is called null which can be set on any type of data including arrays, objects, number, and boolean types. In the Graphical Data Mapping editor, the JSON format supports null as a JSON value type for an object or an array. When a JSON message includes an object with a null value, the value in the message tree is set to NULL.
When you map nilled values, consider the behavior when you use the Move transform, Custom Java, or Custom ESQL to set a target.
The
following table details the result when you map nilled values to different
target types:
Source | Target (XML nillable) | Target (XML not nillable) | Target (Non-XML nillable) | Target (JSON object or JSON array) |
---|---|---|---|---|
Logical Message Tree XML nillable element | Target created as nilled, has xsi:nil attribute 'true', if source has xsi:nil attribute 'true'. | Target created with empty value. | Target created with NULL value, if source has xsi:nil attribute 'true'. | Target created with NULL value, if source has xsi:nil attribute 'true'. |
Logical Message Tree XML element set to NULL | Target created with empty value. A Source XML having NULL value is not considered a nilled element. | Target created with empty value. | Target created with empty value. A Source XML having NULL value is not considered a nilled element. | Target created with NULL value. |
Logical Message Tree non-XML | Target created as nilled. Target has xsi:nil attribute 'true', if source is NULL. | Target created with empty value. | Target created with NULL value, if source is NULL. | Target created with NULL value, if source is NULL. |
Database nullable column | Target created as nilled. Target has xsi:nil attribute 'true', if source is SQL NULL. | Target created with empty value. | Target created with NULL value, if source is SQL NULL. | Target created with NULL value, if source is SQL NULL. |
Custom ESQL | Target created as nilled. Target has xsi:nil attribute 'true', if return is ESQL NULL. | Target created with empty value. | Target created with NULL value, if return is ESQL NULL. | |
Custom Java™ | Target created as nilled. Target has xsi:nil attribute 'true', if return is an MbElement with type set to "TYPE_UNKNOWN" and a value of "null" and a child element xsi:nil 'true'. | Target created with empty value. | Target created with value NULL, if return is an MbElement with type set to "TYPE_UNKNOWN" and a value of "null". | |
Custom XPath expression: iib:setNull() |
Target created as nilled. Target has xsi:nil attribute 'true', if source has xsi:nil attribute 'true'. | Target created with empty value. | Target created as nilled, has xsi:nil attribute 'true', if source has xsi:nil attribute 'true'. | Target created with JSON null value. |