DB2 Version 9.7 for Linux, UNIX, and Windows

db2-xdb:contentHandling decomposition annotation

The db2-xdb:contentHandling annotation specifies the type of content that will be decomposed into a table for an element of complex type or simple type.

db2-xdb:contentHandling belongs to the set of decomposition annotations that can be added to an XML schema document to describe the mappings between elements and attributes of XML documents to DB2® base tables. The decomposition process uses the annotated XML schema to determine how elements and attributes of an XML document should be decomposed into DB2 tables.

Annotation type

Attribute of <xs:element>, or attribute of <db2-xdb:rowSetMapping>, that applies to complex type or simple type element declarations

How to specify

db2-xdb:contentHandling is specified in any of the following ways (where value represents a valid value for the annotation):

<xs:element db2-xdb:contentHandling="value" />

<db2-xdb:rowSetMapping db2-xdb:contentHandling="value">
  <db2-xdb:rowSet>value</db2-xdb:rowSet>
  …
</db2-xdb:rowSetMapping>

Namespace

http://www.ibm.com/xmlns/prod/db2/xdb1

Valid values

One of the following case-sensitive tokens:

text
stringValue
serializeSubtree

Details

The db2-xdb:contentHandling annotation, specified as an attribute in the declaration of an XML element, indicates what value is to be inserted into the tables and columns specified by db2-xdb:rowSet and db2-xdb:column, respectively, during decomposition. The three valid values for db2-xdb:contentHandling are:

text

What is inserted: the concatenation of character data (including character content of CDATA sections) within this element.
What is excluded: this element's comments and processing instructions, CDATA section delimiters ("<![CDATA[" "]]>"), as well as this element's descendants (including tags and content).

stringValue

What is inserted: the concatenation of this element's character data (including character content of CDATA sections) with the character data in this element's descendants, in document order.
What is excluded: comments, processing instructions, CDATA section delimiters ("<![CDATA[" "]]>"), and the start and end tags of this element's descendants.

serializeSubtree

What is inserted: the markup of everything between this element's start and end tags, including this element's start and end tags. This includes comments, processing instructions, and CDATA section delimiters ("<![CDATA[" "]]>").
What is excluded: nothing.
Notes: The serialized string that is inserted might not be identical to the corresponding section in the XML document because of factors such as: default values specified in the XML schema, expansion of entities, order of attributes, whitespace normalization of attributes, and processing of CDATA sections.
Because the serialized string that results from this setting is an XML entity, there are code page issues that should be considered. If the target column is of character or graphic types, the XML fragment is inserted in the database's code page. When such an entity is passed by an application to an XML processor, the application must explicitly inform the processor of the entity's encoding, because the processor would not automatically detect encodings other than UTF-8. If the target column is of type BLOB, however, then the XML entity is inserted in UTF-8 encoding. In this case, the XML entity can be passed to the XML processor without needing to specify an encoding.

If an XML element declaration that is annotated for decomposition is of complex type and contains complex content, but does not have db2-xdb:contentHandling specified, then the default behavior follows the "serializeSubtree" setting. For all other cases of annotated element declarations, the default behavior if db2-xdb:contentHandling is not specified follows the "stringValue" setting.

If an element is declared to be of complex type and has an element-only or empty content model (that is, the "mixed" attribute of the element declaration is not set to true or 1), then db2-xdb:contentHandling cannot be set to "text".

Specifying the db2-xdb:contentHandling annotation on an element does not affect the decomposition of any of the element's descendants.

The setting of db2-xdb:contentHandling affects the value that is substituted for $DECOMP_CONTENT in either of the db2-xdb:expression or db2-xdb:condition annotations. The substituted value is first processed according to the db2-xdb:contentHandling setting, before it is passed for evaluation.

Note that if validation has been performed, either prior to decomposition or during, the content being processed by db2-xdb:contentHandling will already have its entities resolved.

Example

The following example illustrates how the different settings of the db2-xdb:contentHandling annotation can be used to yield different results in the target table. The annotated schema is presented first, showing how the <paragraph> element is annotated with db2-xdb:contentHandling. (The annotated schema is presented only once, with db2-xdb:contentHandling set to "text". Subsequent examples in this section assume the same annotated schema, which differ only by the value db2-xdb:contentHandling is set to.)

<xs:schema>
  <xs:element name="books">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="book">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="authorID" type="xs:integer" />
              <xs:element name="chapter" type="chapterType" maxOccurs="unbounded" />
            </xs:sequence>
            <xs:attribute name="isbn" type="xs:string"
                          db2-xdb:rowSet="BOOKCONTENTS" db2-xdb:column="ISBN" />
            <xs:attribute name="title" type="xs:string" />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="chapterType">
    <xs:sequence>
      <xs:element name="paragraph" type="paragraphType" maxOccurs="unbounded"
                  db2-xdb:rowSet="BOOKCONTENTS" db2-xdb:column="CHPTCONTENT"
                  db2-xdb:contentHandling="text" />
    </xs:sequence>
    <xs:attribute name="number" type="xs:integer"
                  db2-xdb:rowSet="BOOKCONTENTS" db2-xdb:column="CHPTNUM" />
    <xs:attribute name="title" type="xs:string"
                  db2-xdb:rowSet="BOOKCONTENTS" db2-xdb:column="CHPTTITLE" />
  </xs:complexType>

  <xs:complexType name="paragraphType" mixed="1">
    <xs:choice>
      <xs:element name="b" type="xs:string" minOccurs="0" maxOccurs="unbounded" />
    </xs:choice>
  </xs:complexType>
</xs:schema>

The <books> element that is being mapped is presented next.

<books>
  <book isbn="1-11-111111-1" title="My First XML Book">
    <authorID>22</authorID>
    <chapter number="1" title="Introduction to XML">
      <paragraph>XML is <b>lots of</b> fun...</paragraph>
    </chapter>
    <chapter number="2" title="XML and Databases">
      <paragraph><!-- Start of chapter -->XML can be used with...</paragraph>
      <paragraph><?processInstr example?>
        Escape characters such as <![CDATA[ <, >, and & ]]>...</paragraph>
    </chapter>
    ...
    <chapter number="10" title="Further Reading">
      <paragraph>Recommended tutorials...</paragraph>
    </chapter>
  </book>
  …
<books>

The next three tables show the result of decomposing the same XML element with differing values for db2-xdb:contentHandling.

Note: The resulting tables below contain quotation marks around the values in the CHPTTITLE and CHPTCONTENT columns. These quotation marks do not exist in the columns, but are presented here only to show the boundaries and whitespaces of the inserted strings.

db2-xdb:contentHandling="text"

Table 1. BOOKCONTENTS
ISBN	CHPTNUM	CHPTTITLE	CHPTCONTENT
1-11-111111-1	1	"Introduction to XML"	"XML is fun..."
1-11-111111-1	2	"XML and Databases"	"XML can be used with..."
1-11-111111-1	2	"XML and Databases"	" Escape characters such as <, >, and & ..."
…	…	…	…
1-11-111111-1	10	"Further Reading"	"Recommended tutorials..."

Observe how the content of the <b> element of the first paragraph of chapter 1 is not inserted when the "text" setting is used. This is because the "text" setting excludes any content from descendants. Notice also that the comment and processing instruction from the first paragraph of chapter 2 are excluded when the "text" setting is used. Whitespace from the concatenation of character data from the <paragraph> elements is preserved.

db2-xdb:contentHandling="stringValue"

Table 2. BOOKCONTENTS
ISBN	CHPTNUM	CHPTTITLE	CHPTCONTENT
1-11-111111-1	1	"Introduction to XML"	"XML is lots of fun..."
1-11-111111-1	2	"XML and Databases"	"XML can be used with..."
1-11-111111-1	2	"XML and Databases"	" Escape characters such as <, >, and & ..."
…	…	…	…
1-11-111111-1	10	"Further Reading"	"Recommended tutorials..."

The difference between this table and the previous table is found in the CHPTCONTENT column of the first row. Notice how the string "lots of", which comes from the <b> descendant of the <paragraph> element, has been inserted. When db2-xdb:contentHandling was set to "text", this string was excluded, because the "text" setting excludes the content of descendants. The "stringValue" setting, however, includes content from descendants. Like the "text" setting, comments and processing instructions are not inserted, and whitespace is preserved.

db2-xdb:contentHandling="serializeSubtree"

Table 3. BOOKCONTENTS
ISBN	CHPTNUM	CHPTTITLE	CHPTCONTENT
1-11-111111-1	1	"Introduction to XML"	"<paragraph>XML is <b>lots of</b> fun...</paragraph>"
1-11-111111-1	2	"XML and Databases"	"<paragraph><!-- Start of chapter -->XML can be used with...</paragraph>"
1-11-111111-1	2	"XML and Databases"	"<paragraph><?processInstr example?> Escape characters such as <![CDATA[ <, >, and & ]]>...</paragraph>"
…	…	…	…
1-11-111111-1	10	"Further Reading"	"<paragraph>Recommended tutorials...</paragraph>"

The difference between this table and the previous two tables is that all markup from the descendants of <paragraph> elements are inserted (including the <paragraph> start and end tags). This includes the <b> start and end tags in the CHPTCONTENT column of the first row, as well as the comment and processing instruction in the second and third rows, respectively. As in the previous two examples, whitespace from the XML document has been preserved.