Working with Optional Elements

LightWave Server has several mechanisms to indicate the presence of optional elements. These mechanisms use a schema attribute to indicate the presence or absence of the element.

Using the hideIfEmpty Attribute

The hideIfEmpty="1" attribute may be set on any element to indicate that if the source element is empty, it should not be included in the response payload. An element is considered empty when it is completely filled with the element's string padding character. Note that the string padding may be explicitly set on the element using the stringPadding attribute, or inherited from its parent. In the following example, if element optionalIfSpaces is filled with spaces, or optionalIfZeros is filled with zeros, the elements will not be included in the response payload.

XML

<type name="SampleType">
	<element name="optionalIfSpaces" type="string" size="32" hideIfEmpty="1" stringPadding="spaces" />
	<element name="optionalIfZeroes" type="aStructureType" hideIfEmpty="1" stringPadding="zeros" />
</type>

Using the isSet Attribute

The isSet attribute may be set on any element, and references a target integer element which is used to indicate the presence or absence of the source element. In the following example, if the value of the element isAddressSet is non-zero, then the theAddress is included in the response. In this example, the hide attribute is set on the isAddressSet element to indicate that it is never included in the response payload. Note that when a response is received, the isSet target element will be set to zero if the source element is not present in the response, or non-zero if it is present.

XML

<type name="SampleType">
    <element name="isAddressSet" type="int" size="4" hide="1" />
    <element name="theAddress" type="AddressType" isSet="isAddressSet" />
</type>

Using the minOccurs Attribute

Using the minOccurs attribute has a mechanism to hide string elements is deprecated. New definitions should use hideIfEmpty.

The minOccurs="0" attribute may be set on elements with type="string" to indicate that if the source element is filled with the string padding character, it should not be included in the response payload. In the following example, if element optionalIfSpaces is filled with spaces, or optionalIfZeros is filled with zeros, the elements will not be included in the response payload.

XML

<type name="SampleType">
	<element name="optionalIfSpaces" type="string" size="32" minOccurs="0" stringPadding="spaces" />
	<element name="optionalIfZeros" type="string" size="32" minOccurs="0" stringPadding="zeros" />
</type>