DB2 Version 9.7 for Linux, UNIX, and Windows

db2-xdb:locationPath decomposition annotation

The db2-xdb:locationPath annotation maps an XML element or attribute globally declared or as part of a reusable group, to different table and column pairs, depending on the ancestry of the element or attribute. Reusable groups are globally declared named complex types, named model groups, and named attribute groups.

db2-xdb:locationPath 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 <xs:attribute>, or attribute of <db2-xdb:rowSetMapping>

How to specify

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

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

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

Namespace

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

Valid values

The value of db2-xdb:locationPath must have the following syntax:

location path := ‘⁄' (locationstep ‘⁄')* lastlocationstep
locationstep := (prefix‘:')? name
lastlocationstep := locationstep | ‘@' (prefix:)? name

where name is an element or attribute name, and prefix is a namespace prefix.

Notes:

All namespace prefixes used in the location path must have been associated with a namespace in the schema document that contains the annotation specifying this location path.
A namespace prefix binding can be created by adding a namespace declaration to the <xs:schema> element of the schema document.
If prefix is empty, then name is assumed to be in no namespace. If a default namespace is declared in the schema document, and a name in locationstep belongs to that namespace, a namespace prefix must be declared for the default namespace and used to qualify the name; in db2-xdb:locationPath, an empty prefix does not refer to the default namespace.

Details

The db2-xdb:locationPath annotation is used to describe the mappings for elements or attributes that are either declared globally or as part of either a:

named model group
named attribute group
global complex type declaration
global element or attribute of simple or complex type

For element or attribute declarations that cannot be reused (local declarations that are not part of named complex type definitions or named model or attribute groups), the db2-xdb:locationPath annotation has no effect.

db2-xdb:locationPath should be used when global element or attribute declarations are used as references from various ancestry lines. (for example: <xs:element ref="abc">). Because annotations cannot be specified directly on references, they must instead be specified on the corresponding global element or attribute declaration. Because the corresponding element or attribute declaration is global, the element or attribute can be referenced from many different contexts within the XML schema. In general, db2-xdb:locationPath should be used to distinguish the mappings in these different contexts. For named complex types, model groups, and attribute groups, the element and attribute declarations should be annotated for each context in which they are mapped for decomposition. The db2-xdb:locationPath annotation should be used to specify the target rowSet and column pair for each locationPath. The same db2-xdb:locationPath value can be used for different rowSet and column pairs.

Example

The following example shows how the same attribute can be mapped to different tables depending on the context in which this attribute appears. A section of the annotated schema is presented first.

  <!-- global attribute -->
  <xs:attribute name="title" type="xs:string"
                db2-xdb:rowSet="BOOKS"
                db2-xdb:column="TITLE"
                db2-xdb:locationPath="/books/book/@title">
    <xs:annotation>
      <xs:appinfo>
        <db2-xdb:rowSetMapping db2-xdb:locationPath="/books/book/chapter/@title">
          <db2-xdb:rowSet>BOOKCONTENTS</db2-xdb:rowSet>
          <db2-xdb:column>CHPTTITLE</db2-xdb:column>
        </db2-xdb:rowSetMapping>
      </xs:appinfo>
    </xs:annotation>
  </xs:attribute>
  
  <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" />
            <xs:attribute ref="title" />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="chapterType">
    <xs:sequence>
      <xs:element name="paragraph" type="paragraphType" maxOccurs="unbounded" />
    </xs:sequence>
    <xs:attribute name="number" type="xs:integer" />
    <xs:attribute ref="title" />
  </xs:complexType>

  <xs:simpleType name="paragraphType">
    <xs:restriction base="xs:string"/>
  </xs:simpleType>

Note that there is only one attribute declaration named "title", but there are two references to this attribute in different contexts. One reference is from the <book> element, and the other is from the <chapter> element. The value of the "title" attribute needs to be decomposed into different tables depending on the context. This annotated schema specifies that a "title" value is decomposed into the BOOKS table if it is a book title and into the BOOKCONTENTS table if it is a chapter title.

The <books> element that is being mapped is presented next, followed by the resulting BOOKS table after the decomposition has completed.

<books>
  <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>
    <chapter number="2" title="XML and Databases">
      <paragraph>XML can be used with...</paragraph>
    </chapter>
    ...
    <chapter number="10" title="Further Reading">
      <paragraph>Recommended tutorials...</paragraph>
    </chapter>
  </book>
...
</books>

Table 1. BOOKS
ISBN	TITLE	CONTENT
NULL	My First XML Book	NULL

Table 2. BOOKCONTENTS
ISBN	CHPTNUM	CHPTTITLE	CHPTCONTENT
NULL	NULL	Introduction to XML	NULL
NULL	NULL	XML and Databases	NULL
…	…	…	…
NULL	NULL	Further Reading	NULL