Skip Headers
Oracle® XML DB Developer's Guide
11g Release 2 (11.2)

Part Number E10492-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

23 Using XLink and XInclude with Oracle XML DB

This chapter describes how to use XLink and XInclude with resources in Oracle XML DB Repository. It contains these topics:

Overview of XLink and XInclude

A document-oriented, or content-management, application often tracks relationships, between documents, and those relationships are often represented and manipulated as links of various kinds. Such links can affect application behavior in various ways, including affecting the document content and the response to user operations such as mouse clicks.

W3C has two recommendations that are pertinent in this context, for documents that are managed in XML repositories:

Each of these standards is very general, and it is not limited to modeling relationships between XML documents. There is no requirement that the documents linked using XLink or included in an XML document using XInclude be XML documents.

Using XLink and XInclude to represent document relationships provides flexibility for applications, facilitates reuse of component documents, and enables their fine-grained manipulation (access control, versioning, metadata, and so on). Whereas using XML data structure (an ancestor–descendents hierarchy) to model relationships requires those relationships to be relatively fixed, using XLink and XInclude to model relationships can easily allow for change in those relationships.

Note:

For XML schema-based documents to be able to use XLink and XInclude attributes, the XML schema must either explicitly declare those attributes or allow any attributes.

See Also:

XLink and XInclude Link Types

This section describes XLink and XInclude link types and the relation between these and Oracle XML DB Repository links. XLink links are more general than repository links. XLink links can be simple or extended. Oracle XML DB supports only simple XLink links, not extended links.

XLink and XInclude Links Model Document Relationships

XLink and XInclude links model arbitrary relationships among documents; the semantics of a relationship is determined by the applications that use the link; it is not inherent in the link itself. XLink and XInclude links can be mapped to Oracle XML DB document links. When document links target Oracle XML DB Repository resources, they can (according to a configuration option) be hard or weak links; in this, they are similar to repository links in that context. Repository links can be navigated using file system-related protocols such as FTP and HTTP; document links cannot, but they can be navigated using the XPath 2.0 function fn:doc.

XLink and XInclude Link Types

XLink and XInclude can provide links to other documents. In the case of XInclude, attributes href and xpointer are used to specify the target document.

Xlink links can be simple or extended. Simple links are unidirectional, from a source to a target. Extended links (sometimes called complex) can model relationships between multiple documents, with different directionalities. Both simple and extended links can include link metadata. XLink links are represented in XML data using various attributes of the namespace http://www.w3.org/1999/xlink, which has the predefined prefix xlink. Simple links are represented in XML data using attribute type with value simple, that is, xlink:type = "simple". Extended Xlink links are represented using xlink:type = "extended".

Third-party extended Xlink links are not contained in any of the documents whose relationships they model. Third-party links can thus be used to relate documents, such as binary files, that, themselves, have no way of representing a link.

The source end of a simple Xlink link (that is, the document containing the link) must be an XML document; the target end can be any document; there are no such restrictions for extended links. Example 23-3 shows examples of simple links; the link targets are represented using attribute xlink:href.

XInclude: Compound Documents

XInclude is the W3C recommendation for the syntax and processing model for merging the infosets of multiple XML documents into a single infoset. Element xi:include is used to include another document, specifying its URI as the value of an href attribute. Element xi:include can be nested; that is, an included document can itself include other documents.

(However, an inclusion cycle raises an error in Oracle XML DB. The resources are created, but an error is raised when the inclusions are expanded.)

XInclude thus provides for compound documents: repository file resources that include other XML documents or fragments. The included objects can be file resources in the same repository or documents or fragments outside the repository.

A book might be an example of a typical compound document, as managed by a content-management system. Each book includes chapter documents, which can each be managed as separate objects, with their own URLs. A chapter document can have its own metadata and access control, and it can be versioned. A book can include (reference) a specific version of a chapter document. The same chapter document can be included in multiple book documents, for reuse. Because inclusion is modeled using XInclude, content management is simplified. It is easy, for example, to replace one chapter in a book by another.

Example 23-1 illustrates an XML Book element that includes four documents. One of those documents, part1.xml, is also shown; it includes other documents, representing chapters.

Example 23-1 XInclude Used in a Book Document to Include Parts and Chapters

The top-level document representing a book contains element Book.

<Book xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href=toc.xml"/>
  <xi:include href=part1.xml"/>
  <xi:include href=part2.xml"/>
  <xi:include href=index.xml"/>
</Book>

A major book part, file (resource) part2.xml, contains a Part element, which includes multiple chapter documents.

<?xml version="1.0"?>
<Part xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="chapter5.xml"/>
  <xi:include href="chapter6.xml"/>
  <xi:include href="chapter8.xml"/>
  <xi:include href="chapter9.xml"/>
</Part>

These are some additional features of XInclude:

Using XLink with Oracle XML DB

Oracle XML DB supports only simple XLink links, not extended XLink links.

When an XML document containing XLink attributes is added to Oracle XML DB Repository, either as resource content or as user-defined resource metadata, special processing can occur, depending on how the repository or individual repository resources are configured. Element XLinkConfig of the resource configuration document, XDBResConfig.xsd, determines this behavior. In particular, you can configure resources so that XLink links are ignored, or so that they are mapped to Oracle XML DB document links. In the latter case, configuration can specify that the document links are to be hard or weak. Hard and weak document links have the same properties as hard and weak repository links.

The privileges needed to create or update document links are the same as those needed to create or update repository links. Even partially updating a document requires the same privileges needed to delete the entire document and reinsert it. In particular, this means that even if you update just one document link, you must have delete and insert privileges for each of the documents linked by the document containing the link.

If configuration maps XLink links to document links, then, whenever a document containing XLink links is added to the repository, the XLink information is extracted and stored in a system link table. Link target (destination) locations are replaced by direct paths that are based on the resource OIDs. Configuration can also specify whether OID paths are to be replaced by named paths (URLs) upon document retrieval. Using OID paths instead of named paths generally offers a performance advantage when links are processed, including when resource contents are retrieved.

You can use XLink within resource content, but not within resource metadata.

Using XInclude with Oracle XML DB

Oracle XML DB supports XInclude 1.0 as the standard mechanism for managing compound documents. It does not support attribute xpointer and the inclusion of document fragments, however; only complete documents can be included (using attribute href).

You can use XInclude to create XML documents that include existing content. You can also configure the implicit decomposition of non-schema-based XML documents, creating a set of repository resources that contain XInclude inclusion references.

The content of included documents must be XML data or plain text (with attribute parse = "text"). You cannot include binary content directly using XInclude, but you can use XLink to link to binary content.

You can use XInclude within resource content, but not within resource metadata.

Expanding Compound-Document Inclusions

When you retrieve a compound document from Oracle XML DB Repository, you have a choice:

  • Retrieve it as is, with the xi:include elements remaining as such. This is the default behavior.

  • Retrieve it after replacing the xi:include elements with their targets, recursively, that is, after expansion of all inclusions. An error is raised if any xi:include element cannot be resolved.

To retrieve the document in expanded form, use PL/SQL constructor XDBURIType, passing a value of '1' or '3' as the second argument (flags). Example 23-2 illustrates this. These are the possible values for the XDBURIType constructor second argument:

  • 1 – Expand all XInclude inclusions before returning the result. If any such inclusion cannot be resolved according to the XInclude standard fallback semantics, then raise an error.

  • 2 – Suppress all errors that might occur during document retrieval. This includes dangling href pointers.

  • 3 – Same as 1 and 2 together.

Example 23-2 retrieves all documents that are under repository folder public/bookdir, expanding each inclusion:

Example 23-2 Expanding Document Inclusions using XDBURIType

SELECT XDBURIType(ANY_PATH, '1').getXML() FROM RESOURCE_VIEW
  WHERE under_path(RES, '/public/bookdir') = 1;

XDBURITYPE(ANY_PATH,'1').GETXML()
---------------------------------
<Book>
  <Title>A book</Title>
  <Chapter id="1">
    <Title>Introduction</Title>
    <Body>
      <Para>blah blah</Para>
      <Para>foo bar</Para>
    </Body>
  </Chapter>
  <Chapter id="2">
    <Title>Conclusion</Title>
    <Body>
      <Para>xyz xyz</Para>
      <Para>abc abc</Para>
    </Body>
  </Chapter>
</Book>
 
<Chapter id="1">
  <Title>Introduction</Title>
  <Body>
    <Para>blah blah</Para>
    <Para>foo bar</Para>
  </Body>
</Chapter>
 
<Chapter id="2">
  <Title>Conclusion</Title>
  <Body>
    <Para>xyz xyz</Para>
    <Para>abc abc</Para>
  </Body>
</Chapter>
 
3 rows selected.

(The result shown here corresponds to the resource bookfile.xml shown in Example 23-8, together with its included resources, chap1.xml and chap2.xml.)

See Also:

Validating Compound Documents

You validate a compound document the way you would any XML document. However, you can choose to validate it in either form: with xi:include elements as is or after replacing them with their targets.

You can also choose to use one XML schema to validate the unexpanded form, and another to validate the expanded form. For example, you might use one XML schema to validate without first expanding, in order to set up storage structures, and then use another XML schema to validate the expanded document after it is stored.

Updating Compound Documents

You can update a compound document just as you would update any resource. This replaces the resource with a new value; that is, it corresponds to a resource deletion followed by a resource insertion. This means, in particular, that any xi:include elements in the original resource are deleted. Any xi:include elements in the replacement (inserted) document are processed as usual, according to the configuration defined at the time of insertion.

Versioning, Locking, and Controlling Access to Compound Documents

The components of a compound document are separate resources. This means that they are versioned and locked independently, and their access is controlled independently.

  • Document links to version-controlled resources (VCRs) always resolve to the latest version of the target resource, or the selected version within the current workspace. You can, however, explicitly refer to any specific version, by identifying the target resource by its OID-based path.

  • Locking a document that contains xi:include elements does not also lock the included documents. Locking an included document does not also lock documents that include it.

  • The access control list (ACL) on each referenced document is checked whenever you retrieve a compound document with expansion. This is done using the privileges of the current user (invoker's rights). If privileges are insufficient for any of the included documents, the expansion is canceled and an error is raised.

Examining XLink and XInclude Links using DOCUMENT_LINKS View

You can query the read-only public view DOCUMENT_LINKS to obtain system information about document links derived from both XLink and XInclude links. The information in this view includes the following columns, for each link:

You can obtain information about a resource from this view only if one of the following conditions holds:

See Also:

Oracle Database Reference for more information on public view DOCUMENT_LINKS

Querying DOCUMENT_LINKS for XLink Information

Example 23-3 shows how XLink links are treated when resources are created, and how to obtain system information about document links from view DOCUMENT_LINKS. It assumes that the folder containing the resource has been configured to map XLink links to document hard links.

Example 23-3 Querying Document Links Mapped From XLink Links

DECLARE
  b BOOLEAN;
BEGIN
  b := DBMS_XDB.createResource(
         '/public/hardlinkdir/po101.xml', 
         '<PurchaseOrder id="101" xmlns:xlink="http://www.w3.org/1999/xlink">
            <Company xlink:type="simple" 
                     xlink:href="/public/hardlinkdir/oracle.xml">Oracle Corporation</Company>
            <Approver xlink:type="simple"
                      xlink:href="/public/hardlinkdir/quine.xml">Willard Quine</Approver>
          </PurchaseOrder>');
 
  b := DBMS_XDB.createResource(
         '/public/hardlinkdir/po102.xml', 
         '<PurchaseOrder id="102" xmlns:xlink="http://www.w3.org/1999/xlink">
            <Company xlink:type="simple" 
                     xlink:href="/public/hardlinkdir/oracle.xml">Oracle Corporation</Company>
            <Approver xlink:type="simple" 
                      xlink:href="/public/hardlinkdir/curry.xml">Haskell Curry</Approver>
            <ReferencePO xlink:type="simple"
                         xlink:href="/public/hardlinkdir/po101.xml"/>
          </PurchaseOrder>');
END;
/

SELECT r1.ANY_PATH source, r2.ANY_PATH target, dl.LINK_TYPE, dl.LINK_FORM
  FROM DOCUMENT_LINKS dl, RESOURCE_VIEW r1, RESOURCE_VIEW r2 
  WHERE dl.SOURCE_ID = r1.RESID and dl.TARGET_ID = r2.RESID;

SOURCE                        TARGET                         LINK_TYPE LINK_FORM
----------------------------- ------------------------------ --------- ---------
/public/hardlinkdir/po101.xml /public/hardlinkdir/oracle.xml Hard      XLink
/public/hardlinkdir/po101.xml /public/hardlinkdir/quine.xml  Hard      XLink
/public/hardlinkdir/po102.xml /public/hardlinkdir/oracle.xml Hard      XLink
/public/hardlinkdir/po102.xml /public/hardlinkdir/curry.xml  Hard      XLink
/public/hardlinkdir/po102.xml /public/hardlinkdir/po101.xml  Hard      XLink

See Also:

"Mapping XInclude Links to Hard Document Links, with OID Retrieval" for an example of configuring a folder to map XLink links to hard links

Querying DOCUMENT_LINKS for XInclude Information

Example 23-4 queries view DOCUMENT_LINKS to show all document links.

Example 23-4 Querying Document Links Mapped From XInclude Links

DECLARE
  ret BOOLEAN;
BEGIN
  ret := DBMS_XDB.createResource(
           '/public/hardlinkdir/book.xml',
           '<Book xmlns:xi="http://www.w3.org/2001/XInclude">
              <xi:include href="/public/hardlinkdir/toc.xml"/>
              <xi:include href="/public/hardlinkdir/part1.xml"/>
              <xi:include href="/public/hardlinkdir/part2.xml"/>
              <xi:include href="/public/hardlinkdir/index.xml"/>
            </Book>');
END;

SELECT r1.ANY_PATH source, r2.ANY_PATH target, dl.LINK_TYPE, dl.LINK_FORM
  FROM DOCUMENT_LINKS dl, RESOURCE_VIEW r1, RESOURCE_VIEW r2
  WHERE dl.SOURCE_ID = r1.RESID and dl.TARGET_ID = r2.RESID;

SOURCE                       TARGET                        LINK_TYPE LINK_FORM
------                       ------                        --------- ---------
/public/hardlinkdir/book.xml /public/hardlinkdir/toc.xml   Hard      XInclude
/public/hardlinkdir/book.xml /public/hardlinkdir/part1.xml Hard      XInclude
/public/hardlinkdir/book.xml /public/hardlinkdir/part2.xml Hard      XInclude
/public/hardlinkdir/book.xml /public/hardlinkdir/index.xml Hard      XInclude

Configuring Resources for XLink and XInclude

You configure XLink and XInclude treatment for Oracle XML DB Repository resources as you would configure any other treatment of repository resources — see "Configuring a Resource". The rest of this section describes the resource configuration file that you use as a resource to configure XLink and XInclude processing for other resources.

A resource configuration file is an XML file that conforms to the XML schema XDBResConfig.xsd, which is accessible in Oracle XML DB Repository at path /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBResConfig.xsd. You use elements XLinkConfig and XIncludeConfig, children of element ResConfig, to configure XLink and XInclude treatment, respectively. If one of these elements is absent, then there is no treatment of the corresponding type of links.

Both XLinkConfig and XIncludeConfig can have attribute UnresolvedLink and child elements LinkType and PathFormat. Element XIncludeConfig can also have child element ConflictRule. If the LinkType element content is None, however, then there must be no PathFormat or ConflictRule element.

You cannot define any preconditions for XLinkConfig or XIncludeConfig. During repository resource creation, the ResConfig element of the parent folder determines the treatment of XLink and XInclude links for the new resource. If the parent folder has no ResConfig element, then the repository-wide configuration applies.

Any change to the resource configuration file applies only to documents that are created or updated after the configuration-file change. To process links in existing documents, use PL/SQL procedure DBMS_XDB.processLinks, after specifying the appropriate resource configuration parameters.

Configuring Treatment of Unresolved Links: UnresolvedLink Attribute

A LinkConfig element can have an UnresolvedLink attribute with a value of Error (default value) or Skip. This determines what happens if an XLink or XInclude link cannot be resolved at the time of document insertion into the repository (resource creation): Error means raise an error and roll back the current operation; Skip means skip any treatment of the XLink or XInclude link. Skipping treatment creates the resource with no corresponding document links, and sets the resource's HasUnresolvedLinks attribute to true, to indicate that the resource has unresolved links.

Using Skip as the value of attribute UnresolvedLink can be especially useful when you create a resource that contains a cycle of weak links, which would otherwise lead to unresolved-link errors during resource creation. After the resource and all of its linked resources have been created, you can use PL/SQL procedure DBMS_XDB.processLinks to process the skipped links. If all XLink and XInclude links have been resolved by this procedure, then attribute HasUnresolvedLinks is set to false.

Resource attribute HasUnresolvedLinks is also set to true for a resource that has a weak link to a resource that has been deleted. Deleting a resource thus effectively also deletes any weak links pointing to that resource. In particular, whenever the last hard link to a resource is deleted, the resource is itself deleted, and all resources that point to the deleted resource with a weak link have attribute HasUnresolvedLinks set to true.

Configuring the Document Links to Create: LinkType Element

You use the LinkType element of a resource configuration file to specify the type of document link to be created whenever an XLink or XInclude link is encountered when a document is stored in Oracle XML DB Repository. The LinkType element has these possible values (element content):

  • None (default) – Ignore XLink or XInclude links: create no corresponding document links.

  • Hard – Map XLink or XInclude links to hard document links in repository documents.

  • Weak – Map XLink or XInclude links to weak document links in repository documents.

Configuring the Path Format for Retrieval: PathFormat Element

You use the PathFormat element of a resource configuration file to specify the path format to be used when retrieving documents with xlink:href or xi:include:href attributes. The PathFormat element has these possible values (element content) for hard and weak document links:

  • OID (default) – Map XLink or XInclude href paths to OID-based paths in repository documents — that is, use OIDs directly.

  • Named – Map XLink or XInclude href paths to named paths (URLs) in repository documents. The path is computed from the internal OID when the document is retrieved, so retrieval can be slower than in the case of using OID paths directly.

Configuring Conflict-Resolution for XInclude: ConflictRule Element

You use the ConflictRule element of a resource configuration file to specify the conflict-resolution rules to use if the path computed for a component document is already present in Oracle XML DB Repository. The ConflictRule element has these possible values (element content):

  • Error (default) – Raise an error.

  • Overwrite – Update the document targeted by the existing repository path, replacing it with the document to be included. If the existing document is a version-controlled resource, then it must already be checked out, unless it is autoversioned; otherwise, an error is raised.

  • Syspath – Change the path to the included document to a new, system-defined path.

See Also:

Chapter 24, "Managing Resource Versions" for information about version-controlled resources

Configuring Decomposition of Documents using XInclude: SectionConfig Element

You use the SectionConfig element of a resource configuration file to specify how non-schema-based XML documents are to be decomposed when added to Oracle XML DB Repository, to create a set of resources that contain XInclude inclusion references. You use simple XPath expressions in the resource configuration file to identify which parts of a document to map to separate resources, and which resources to map them to.

Element SectionConfig contains one or more Section elements, each of which contains the following child elements:

  • sectionPath – Simple XPath 1.0 expression that identifies a section root. This must use only child and descendant axes, and it must not use wildcards.

  • documentPath (optional) – Simple XPath 1.0 expression that is evaluated to identify the resources to be created from decomposing the document according to sectionPath. The XPath expression must use only child, descendant, and attribute axes.

  • namespace (optional) – Namespace in effect for sectionPath and documentPath.

Element Section also has a type attribute that specifies the type of section to be created. Value Document means create a document. The default value, None, means do not create anything; it is equivalent to removing the SectionConfig element. You can thus set the type attribute to None to disable a SectionConfig element temporarily, without removing it, and then set it back to Document to enable it again.

If an element in the document being added to the repository matches more than one sectionPath value, only the first such expression (in document order) is used.

If no documentPath element is present, then the resource created has a system-defined name, and is put into the folder specified for the original document.

XLink and XInclude Configuration Examples

Example 23-5 shows a configuration-file section that configures XInclude treatment, mapping XInclude attributes to Oracle XML DB Repository hard document links. Repository paths in retrieved resources are configured to be based on resource OIDs.

Example 23-5 Mapping XInclude Links to Hard Document Links, with OID Retrieval

<ResConfig>
  . . .
  <XIncludeConfig UnresolvedLink="Skip">
    <LinkType>Hard</LinkType>
    <PathFormat>OID</PathFormat>
  </XIncludeConfig>
  . . .
</ResConfig>

Example 23-6 shows an XLinkConfig section that maps XLink links to weak document links in the repository. In this case, retrieval of a document uses named paths (URLs).

Example 23-6 Mapping XLInk Links to Weak Links, with Named-Path Retrieval

<ResConfig>
  . . .
  <XLinkConfig UnresolvedLink="Skip">
    <LinkType>Weak</LinkType>
    <PathFormat>Named</PathFormat>
  </XLinkConfig>
  . . .
</ResConfig>

Example 23-7 shows a SectionConfig section that specifies that each Chapter element in an input document is to become a separate repository file, when the input document is added to Oracle XML DB Repository. The repository path for the resulting file is specified using configuration element documentPath, and this path is relative to the location of the resource configuration file of Example 23-6.

Example 23-7 Configuring XInclude Document Decomposition

<ResConfig>
  . . .
  <SectionConfig>
    <Section type = "Document">
      <sectionPath>//Chapter</sectionPath>
      <documentPath>concat("chap", @id, ".xml")</documentPath>
    </Section>
  </SectionConfig>
  . . .
</ResConfig>

The XPath expression here uses XPath function concat to concatenate the following strings to produce the resulting repository path to use:

  • chap – (prefix) chap.

  • The value of attribute id of element Chapter in the input document.

  • .xml as a file extension.

For example, a repository path of chap27.xml would result from an input document with a Chapter element that has an id attribute with value 27:

<Chapter id="27"> ... </Chapter>

If the configuration document of Example 23-6 and the book document that contains the XInclude elements are in repository folder /public/bookdir, then the individual chapter files generated from XInclude decomposition are in files /public/bookdir/chapN.xml, where the values of N are the values of the id attributes of Chapter elements.

The book document that is added to the repository is derived from the input book document. The embedded Chapter elements in the input book document are replaced by xi:include elements that reference the generated chapter documents — Example 23-8 illustrates this.

Example 23-8 Repository Document, Showing Generated xi:include Elements

SELECT XDBURIType('/public/bookdir/bookfile.xml').getclob() FROM DUAL;
 
XDBURITYPE('/PUBLIC/BOOKDIR/BOOKFILE.XML').GETCLOB()
--------------------------------------------------------------------------------
<Book>
  <Title>A book</Title>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="/public/bookdir/chap1.xml"/>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="/public/bookdir/chap2.xml"/>
</Book>

Managing XLink and XInclude Links using DBMS_XDB.processLinks

You can use PL/SQL procedure DBMS_XDB.processLinks to manually process all XLink and XInclude links in a single document or in all documents of a folder. Pass RECURSIVE as the mode argument to this procedure, if you want to process all hard-linked subfolders recursively. All XLink and XInclude links are processed according to the corresponding configuration parameters. If any of the links within a resource cannot be resolved, the resource's HasUnresolvedLinks attribute is set to true, to indicate that the resource has unresolved links. The default value of attribute HasUnresolvedLinks is false.