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:

• XLink – Defines various types of links between resources. These links can model arbitrary relationships between documents. Those documents can reside inside or outside the repository.

• XInclude – Defines ways to include the content of multiple XML documents or fragments in a single infoset. This provides for compound documents, which model inclusion relationships. Compound documents are documents that contain other documents. More precisely, they are file resources that include documents or document fragments. The included objects can be file resources in the same repository or documents or fragments outside the repository.

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.

XLink and XInclude link types are described, as well as the relation between these and Oracle XML DB Repository links. XLink links (deprecated) are more general than repository links. XLink links can be simple or extended. Oracle XML DB supports only simple, not extended, XLink links.

• XLink and XInclude Links Model Document Relationships
  XLink (deprecated) and XInclude links model arbitrary relationships among documents. The meaning and behavior of a relationship are determined by the applications that use the link. They are not inherent in the link itself. XLink and XInclude links can be mapped to Oracle XML DB document links.
• XLink Link Types and XInclude Link Types
  XLink (deprecated) and XInclude can provide links to other documents. In the case of XInclude, attributes href and xpointer are used to specify the target document.

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, so that 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. Document part1.xml includes other documents, representing chapters.

These are some additional features of XInclude:

• Inclusion of plain text – You can include unparsed, non-XML text using attribute parse with a value of text: parse = "text".

• Inclusion of XML fragments – You can use an xpointer attribute in an xi:include element to specify an XML fragment to include, instead of an entire document.

• Fallback processing – In case of error, such as inability to access the URI of an included document, an xi:include syntax error, or an xpointer reference that returns null, XInclude performs the treatment specified by element xi:fallback. This generally specifies an alternative element to be included. The alternative element can itself use xi:include to include other documents.

<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>

<?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>

You can configure Oracle XML DB Repository resources so that XLink links are ignored, or so that they are mapped to Oracle XML DB document links. However, the use of XLink with Oracle XML DB Repository is deprecated.

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.

If you configure resources so that XLink links are mapped to Oracle XML DB document links, you 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, 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.

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
  You can optionally expand xi:include elements with their targets when you retrieve a compound document from Oracle XML DB Repository.
• Validation of 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.
• Update of a Compound Document
  You can update a compound document just as you would update any resource. This replaces the resource with a new value.
• Compound Document Versioning, Locking, and Access Control
  The components of a compound document are separate resources. They are versioned and locked independently, and their access is controlled independently.

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

• SOURCE_ID – The source resource OID. RAW(16).

• TARGET_ID – The target resource OID. RAW(16).

• TARGET_PATH – Always NULL. Reserved for future use. VARCHAR2(4000).

• LINK_TYPE – The document link type: Hard or Weak. VARCHAR2(8).

• LINK_FORM – Whether the original link was of form XLink or XInclude. VARCHAR2(8).

• SOURCE_TYPE – Always Resource Content. VARCHAR2(17).

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

• The resource is a link source, and you have the privilege read-contents or read-properties on it.

• The resource is a link target, and you have the privilege read-properties on it.

• Querying DOCUMENT_LINKS for XLink Information
  If the folder containing a given resource has been configured to map XLink links to document hard links then you can query public view DOCUMENT_LINKS to obtain system information about the document links.
• Querying DOCUMENT_LINKS for XInclude Information
  You can query view DOCUMENT_LINKS to show the document links that are mapped from XInclude links.

The resource configuration file that you use as a resource to configure XLink (deprecated) and XInclude processing for other resources is described.

You configure XLink and XInclude treatment for Oracle XML DB Repository resources as you would configure any other treatment of repository resources: using a resource configuration file. See Configuring a Resource for an example.

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_REPOS.processLinks, after specifying the appropriate resource configuration parameters.

• Configure the Treatment of Unresolved Links: Attribute UnresolvedLink
  A LinkConfig element can have an UnresolvedLink attribute with a value of Error (default value) or Skip. This determines what happens if an XLink (deprecated) or XInclude link cannot be resolved at the time of document insertion into the repository (resource creation).
• Configure the Type of Document Links to Create: Element LinkType
  You use the LinkType element of a resource configuration file to specify the type of document link to be created whenever an XLink (deprecated) or XInclude link is encountered when a document is stored in Oracle XML DB Repository. The LinkType element has these possible values (element content):
• Configure the Path Format for Retrieval: Element PathFormat
  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.
• Configure Conflict-Resolution for XInclude: Element ConflictRule
  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):
• Configure the Decomposition of Documents Using XInclude: Element SectionConfig
  You use element SectionConfig of a resource configuration file to specify how non-schema-based XML documents are to be decomposed when they are added to Oracle XML DB Repository to create a set of resources that contain XInclude inclusion references.
• XLink and XInclude Configuration Examples
  Examples show how XLink (deprecated) and XInclude are to be related to Oracle XML DB Repository resources and links.

You can use PL/SQL procedure DBMS_XDB_REPOS.processLinks to manually process all XLink (deprecated) 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.