WebSphere Message Broker, Version 8.0.0.7 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Handling null values

A business message might contain fields that are either empty or have a specific out-of-range value. In these cases, the application that receives the message is expected to treat the field as if it did not have a value. The logical message tree supports this concept by enabling the value of any element to be set to NULL.

Ways to represent a null value

In an XML document, the usual way to represent a null value is to leave the element or attribute empty.

For example: <price></price> or <element price=""/>

The xsi:nil attribute provides a way to make this more explicit: price=<xsi:nil="true"/>

Some business messages use a special value to represent a null value: <price>-999</price>. This style of null representation is supported by the DFDL and MRM parsers.

DFDL parser support for null values

The DFDL parser can detect a null value that is represented by an out-of-range value. The null value must be specified in the DFDL schema, and can be the same or different for each element. In DFDL it is called a nil value. While parsing, the DFDL parser checks the nil value for each element in the message. If the value in the bit stream matches the nil value in the DFDL schema, the DFDL parser sets the value in the message tree to NULL. The same check is performed when converting a message tree to a bit stream. If the value in the message tree is NULL, the DFDL parser outputs the nil value from the DFDL schema.

For more information, see The DFDL 1.0 specification, section 13.15.

Graphical Data Mapper support for null values

Use the following XPath functions to implement conditional processing for mapping the XML NULL value:
  • fn:empty tests whether a set of elements is empty. fn:empty returns true when the element or elements are not present in the logical tree.
    Note: To test whether a xsd:string typed element is present and contains the empty string value, you can use the following expression: if ($<element> = '' ).
  • fn:nilled tests whether an XML element has the xsi:nil attribute set.
  • fn:exists tests whether an element is present. An XML element that has the xsi:nil attribute set is considered to be present.
When you map null values, consider the following behavior:
  • When you map the logical data tree NULL value from an input to an output produces an output element with an empty value. If the element is defined as nillable in the model, an empty output element with the xsi:nil attribute set is produced. The same effect occurs when an output element is set by calling a custom ESQL function that returns the ESQL NULL value.
  • When you use fn:nilled against a non-XML element, for example a nil value element in a DFDL message, fn:nilled will return true if the element value is set to NULL.
  • When you use a Move transform to copy an input XML element that has an xsi:nil attribute set, to an output XML element that is defined as nillable in the schema, produces an output XML element that has the xsi:nil attribute set.
  • When you use a Move transform to copy an input element that has a NULL value to an output element, an output element with an empty value is set.
  • When you use a Move transform to copy a non-XML input element to an XML output element that is defined as nillable in the schema, the output XML element also has the xsi:nil attribute set.

ESQL support for null values

Using ESQL, you can set the value of a message tree element to NULL:

SET OutputRoot.XMLNSC.myField VALUE = NULL;

Note that this is different from SET OutputRoot.XMLNSC.myField = NULL; which would cause myField to be deleted from the message tree.

The same effect can be achieved using Java.

XMLNSC parser support for null values

Typically, the XML parsers (XMLNSC, XMLNS, and XML) do not create null values in the message tree; an empty element or an empty attribute value merely produces an empty string value in the message tree.

If validation is enabled, the XMLNSC parser detects and processes any xsi:nil attributes in the input document. If the xsi:nil attribute is set to 'true', and the element is nullable, the attribute's parent element in the message tree is given a null value.

For more information about XML parser support for empty elements and null values, see XMLNSC empty elements and null values and XMLNS empty elements and null values.

MRM parser support for null values

XML physical format

When parsing, the MRM XML parser can detect and process xsi:nil attributes in the input XML document. If the xsi:nil attribute is set to 'true', and the element is nullable, the attribute's parent element in the message tree is given a null value.

For information about enabling xsi:nil support in the MRM parser, see Message Sets: XML Null handling options.

The following topics provide more information about handling null values in the MRM parser:

All physical formats

The MRM parser can detect a null value that is represented by an out-of-range value. The null value must be specified in the physical format of the message set.

While parsing, the MRM parser checks the null value for each element in the message. If the value in the bit stream matches the null value in the message set, the MRM parser sets the value in the message tree to NULL.

The same check is performed when converting a message tree to a bit stream. If the value in the message tree is NULL, the MRM parser outputs the null value from the message set.

JSON parser support for null values

The JSON format supports NULL as a JSON value type.

When a JSON message includes an object with a null value, the JSON parser sets the value in the message tree to NULL.

When serializing an element in the message tree with a null value, the JSON bit stream is constructed as a JSON object with a value of null.

Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2016Copyright IBM Corporation 1999, 2016.

        
        Last updated:
        
        Last updated: 2016-05-23 14:46:36


Concept topicConcept topic | Version 8.0.0.7 | ac70560_