DB2 Version 10.1 for Linux, UNIX, and Windows

db2-xdb:rowSetMapping decomposition annotation

The <db2-xdb:rowSetMapping> annotation maps a single XML element or attribute to one or more column and table pairs.

<db2-xdb:rowSetMapping> 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

Child element of <xs:appinfo> (which is a child element of <xs:annotation>) that is a child element of <xs:element> or <xs:attribute>

How to specify

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

<xs:element>
  <xs:annotation>
    <xs:appinfo>
      <db2-xdb:rowSetMapping>
        <db2-xdb:rowSet>value</db2-xdb:rowSet>
        ...
      </db2-xdb:rowSetMapping>
    </xs:appinfo>
  </xs:annotation>
  ...
</xs:element>

<xs:attribute>
  <xs:annotation>
    <xs:appinfo>
      <db2-xdb:rowSetMapping>
        <db2-xdb:rowSet>value</db2-xdb:rowSet>
        ...
      </db2-xdb:rowSetMapping>
    </xs:appinfo>
  </xs:annotation>
  ...
</xs:attribute>

Namespace

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

Valid structure

The following are supported attributes of <db2-xdb:rowSetMapping>:

db2-xdb:contentHandling: Enables specification of the type of content that will be decomposed into a table for an element that is of complex type.
db2-xdb:locationPath: Enables mapping of an XML element or attribute declared as part of a reusable group, to different table and column pairs, depending on the ancestry of the element or attribute.
db2-xdb:normalization: Enables specification of the normalization behavior for the content of the XML element or attribute mapped to a character target column, before the content is inserted.
db2-xdb:truncate: Enables specification of whether truncation is permitted when an XML value is inserted into a character target column.

These attributes of <db2-xdb:rowSetMapping> are also available as attributes of XML element or attribute declarations; the same behaviors and requirements apply to these whether they are attributes of <db2-xdb:rowSetMapping> or of <xs:element> or <xs:attribute>. Refer to the individual corresponding documentation of these annotations for details.

The following are supported children elements of <db2-xdb:rowSetMapping>, listed in the order in which they must appear if they are specified:

<db2-xdb:rowSet>: Maps an XML element or attribute to a target base table.
<db2-xdb:column>: (Optional) Maps an XML element or attribute to a base table column. This element is required if db2-xdb:expression is present in the db2-xdb:rowSetMapping annotation.
<db2-xdb:column> can be optional in cases where a value is not intended to be inserted into the table, but is used only for conditional processing. For example, if an element is to be decomposed based on the value of another element, then the other element does not require a column mapping, as its value is not being inserted.
<db2-xdb:expression>: (Optional) Specifies a customized expression, the result of which is inserted into the table named by the db2-xdb:rowSet attribute.
If db2-xdb:expression specifies $DECOMP_CONTENT and db2-xdb:normalization is specified in the same mapping, then the $DECOMP_CONTENT value for db2-xdb:expression will be normalized before it is passed to the expression for evaluation, if applicable.
<db2-xdb:condition>: (Optional) Specifies a condition for evaluation.

Note that these children elements of <db2-xdb:rowSetMapping> have the same semantics and syntax as their corresponding attribute annotations, except that quotation marks do not need to be escaped.

For further details, refer to the corresponding documentation of the attribute versions of these annotations.

Details

<db2-xdb:rowSetMapping> can be used to map an XML element or attribute to a single target table and column, to multiple target columns of the same table, or to multiple tables and columns. There are two equivalent methods for mapping to a single table and column: the combination of the db2-xdb:rowSet and db2-xdb:column annotations (which are attributes of the element or attribute being mapped), or specifying <db2-xdb:rowSetMapping> (which is a child element of the element or attribute being mapped). Both methods yield the same results and differ only in their notation.

All whitespace in the character content of the child elements of <db2-xdb:rowSetMapping> is significant; no whitespace normalization is performed. For delimited SQL identifiers specified in the children elements, the quotation marks delimiter must be included in the character content and not escaped. The '&' and '<' characters used in SQL identifiers, however, must be escaped.

Example

The following example shows how a single attribute, named "isbn", can be mapped to more than one table with the <db2-xdb:rowSetMapping> annotation. A section of the annotated schema is presented first. It shows how the isbn value is mapped to both the BOOKS and BOOKCONTENTS tables.

<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">
      <xs:annotation>
        <xs:appinfo>
          <db2-xdb:rowSetMapping>
            <db2-xdb:rowSet>BOOKS</db2-xdb:rowSet>
            <db2-xdb:column>ISBN</db2-xdb:column>
          </db2-xdb:rowSetMapping>
          <db2-xdb:rowSetMapping>
            <db2-xdb:rowSet>BOOKCONTENTS</db2-xdb:rowSet>
            <db2-xdb:column>ISBN</db2-xdb:column>
          </db2-xdb:rowSetMapping>
        </xs:appinfo>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="title" type="xs:string" />
  </xs:complexType>
</xs:element>

The <book> element that is being mapped is presented next, followed by the resulting BOOKS and BOOKCONTENTS tables after the decomposition has completed.

<book isbn="1-11-111111-1" title="My First XML Book">
  <authorID>22</authorID>
  <!-- this book does not have a preface -->
  <chapter number="1" title="Introduction to XML">
    <paragraph>XML is fun...</paragraph>
    ...
  </chapter>
  ...
</book>

Table 1. BOOKS
ISBN	TITLE	CONTENT
1-11-111111-1	NULL	NULL

Table 2. BOOKCONTENTS
ISBN	CHPTNUM	CHPTTITLE	CHPTCONTENT
1-11-111111-1	NULL	NULL	NULL

Alternative mapping using combination of <db2-xdb:rowSetMapping> and db2-xdb:rowSet and db2-xdb:column

The following section of an annotated schema is equivalent to the XML schema fragment presented previously, as it yields the same decomposition results. The difference between the two schemas is that this schema replaces one mapping with the db2-xdb:rowSet and db2-xdb:column combination, instead of using only the <db2-xdb:rowSetMapping> annotation.

<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="BOOKS" db2-xdb:column="ISBN" >
      <xs:annotation>
        <xs:appinfo>
          <db2-xdb:rowSetMapping>
            <db2-xdb:rowSet>BOOKCONTENTS</db2-xdb:rowSet>
            <db2-xdb:column>ISBN</db2-xdb:column>
          </db2-xdb:rowSetMapping>
        </xs:appinfo>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="title" type="xs:string" />
  </xs:complexType>
</xs:element>