Chapter 6 Working With Concepts : Configuring How to Handle Null Concept Property Values

Configuring How to Handle Null Concept Property Values
This section explains three cases for special handling of null concept property values:
This section also provides related procedures and a reference to the properties used to define the handling of null concept property values.
Enabling Use of the Nillable Attribute
The presence of the xsd:nillable attribute in an XSD element means that the corresponding element in the XML file permits null values.
Setting java.property.tibco.be.schema.nil.attribs=true in designer.tra causes the xsd:nillable attribute ("xsd:nillable=true") to be set on all elements in the BusinessEvents concept XSD. When an element in the XML file generated using that XSD has a null value, the xsi:nil="true" attribute is set on that element.
When set to false, the xsd:nillable attribute is not added and the corresponding XML file does not treat empty elements as null values.
In the absence of the xsd:nillable attribute in the XSD element, a corresponding empty element in the XML file is assumed to have a value. Elements that have no value are treated as empty strings ("").
Effect on schema generation tool  The setting for this property affects the concept XSD files output by the schema generation tool (see Generating XML Schemas (XSD files) for Concepts and Events).
Enabling Null Property Values to Appear When Serializing Concepts to XML
By default concept properties with null values are excluded when concept objects (instances) are serialized to XML. You can override this behavior.
Setting the following property to false in the TIBCO Designer TRA file causes properties with null values to be included in the XML representation of a concept:
java.property.tibco.be.schema.exclude.null.props=false
This property is set in the designer.tra file.
Examples of Nillable Attribute and Null Properties Settings
These examples illustrate the effect of the following properties on concept serialization:
java.property.tibco.be.schema.nil.attribs
java.property.tibco.be.schema.exclude.null.props
If Null Properties are Excluded
java.property.tibco.be.schema.nil.attribs= true or false
java.property.tibco.be.schema.exclude.null.props=true
Suppose a Customer concept instance has no value for its CustomerName property. By default, the CustomerName property is excluded from the XML output. The output might look like the following:

 
<CustomerID>111</CustomerID>
<Country>Japan</Country>
<City>Tokyo</City>

 
If null properties are excluded when concepts are serialized, the java.property.tibco.be.schema.nil.attribs property has no effect on concept serialization.
If Null Properties are Included and the Nillable Attribute is Set
java.property.tibco.be.schema.nil.attribs=true
java.property.tibco.be.schema.exclude.null.props=false
The output for the Customer concept instance shown above would be as follows, where there is no value for the CustomerName element in the concept instance:

 
<CustomerID>111</CustomerID>
<Country>Japan</Country>
<City>Tokyo</City>
<CustomerName
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xsi:nil="true"/>

 
If Null Properties are Included and the Nillable Attribute is not Set
java.property.tibco.be.schema.nil.attribs=false
java.property.tibco.be.schema.exclude.null.props=false
In this case, each null property is considered to be an empty string, and is represented, for example, as follows:
<CustomerName/>
Enabling and Setting Special Treatment of Numeric Null Values
If you enable null values to be output to XML (see Enabling Null Property Values to Appear When Serializing Concepts to XML), then you may also want to configure additional properties for defining how to treat null values for numeric types, as explained in this section.
BusinessEvents does not implicitly support null values for numeric types. This can lead to interoperability issues when working with external sources, such as databases, which do permit blank (null) values.
To address such issues, you can enable special treatment of numeric null values at design time. At runtime, BusinessEvents then uses a special numeric value for each numeric datatype to represent a null value. Default special values are provided and you can override the defaults at runtime (see Table 10, Properties for Null Property Handling).
The special numeric values that indicate null are used in BusinessEvents when serializing and deserializing a concept to and from its XML representation, and when performing various operations on database concepts and the database tables to which they are linked.
The special numeric values that indicate null appear only in BusinessEvents. The appropriate null value is used in the XML or database representation of the concept property.
Conversely, when deserializing or importing a concept instance, BusinessEvents represents numeric null values using the special numeric values that indicate null in the concept instance.
To enable special treatment of numeric null values, set the following property in designer.tra:
java.property.tibco.be.schema.treat.null.values=true
At runtime you can override the default values using the following properties in be-engine.tra:
java.property.tibco.be.property.int.null.value=value
java.property.tibco.be.property.long.null.value=value
java.property.tibco.be.property.double.null.value=value
Setting Designtime Properties for Handling of Null Property Values
This section provides the procedure for setting properties in the TIBCO Designer properties file to set all properties described earlier in this section. After you change any of these properties, you must rebuild and redeploy the EAR file for the project.
To Set Designtime Properties for Handling of Null Property Values
1.
2.
Open the TIBCO_DESIGNER_HOME/bin/designer.tra file for editing.
3.
java.property.tibco.be.schema.exclude.null.props=false
java.property.tibco.be.schema.nil.attribs=true
      java.property.tibco.be.schema.treat.null.values=true
Also see Setting Runtime Properties for Special Treatment of Null Values
4.
Setting Runtime Properties for Special Treatment of Null Values
If you have enabled special treatment of null numeric properties (Enabling and Setting Special Treatment of Numeric Null Values), you can override the default special numeric values that indicate numeric null values in BusinessEvents as follows.
1.
Open the BE_HOME/bin/be-engine.tra file for editing.
2.
java.property.tibco.be.property.int.null.value=value
java.property.tibco.be.property.long.null.value=value
java.property.tibco.be.property.double.null.value=value
Choose values that will not be misinterpreted as literal values.
3.
4.
5.
TIBCO Designer Property Reference for Null Property Handling
Set the following properties in the designer.tra file as needed to configure the output for your needs before you generate the EAR file.
Properties Set in designer.tra
Setting this property to true causes the xsd:nillable attribute ("xsd:nillable=true") to be set on all elements in the BusinessEvents concept XSD.
When this property is set to true, null-valued concept properties are not output when the concept is serialized to XML.
Setting this property to true causes BusinessEvents to use special numeric values that indicate null for numeric datatypes. The special numeric values are set using the properties listed next.
Properties Set in be-engine.tra
These properties define a special numeric value that indicates null. Use a value that will not be confused with an actual numeric value.
These properties are used only if java.property.tibco.be.schema.treat.null.values is set to true.
For Integer and Long these constants represent the most negative value. For Double the constant represents smallest positive nonzero value (4.9e-324).