Using XInclude
by Elliotte Rusty Harold | Pages: 1, 2

Unparsed Text

Technical articles like this one often need to include example code: programs, XML and HTML documents, e-mail messages, and so on. Within these examples characters like < and & should be treated as raw text rather than parsed as markup. To include a document as plain text, you have to add a parse="text" attribute to the xi:include element. For example, this fragment loads the source code for the Java program SpellChecker.java from the examples directory into a code element:

<code> 
  <xi:include parse="text" 
              href="examples/SpellChecker.java" />
</code>

Processes that are downstream from the XInclusion will see the complete text of the file SpellChecker.java like they would any other text. For instance, such data would be passed to a SAX code>ContentHandler object's characters() method. This is pretty much exactly the way a parser would treat the content if it were typed in a CDATA section.

Fallback

Servers crash. Network connections fail. The domain name system gets congested. For these reasons and many others, documents included from remote servers may be temporarily unavailable. The default action for an XInclude processor in such a case is simply to give up and report a fatal error. However, the xi:include element may contain an xi:fallback element which contains alternate content to be used if the requested resource cannot be found. For example, this xi:include element tries to load the file at http://www.whitehouse.gov/malapropisms.xml. However, if somebody deletes that file, then it provides some literal content instead:

<xi:include href="http://www.whitehouse.gov/malapropisms.xml">
  <xi:fallback>
    <para>
      This administration is doing everything we can to end the stalemate in
      an efficient way. We're making the right decisions to bring the solution
      to an end.
    </para>
  </xi:fallback>
</xi:include>

The xi:fallback element can even include another xi:include element. For example, this xi:include element begins by attempting to include the document at http://www.whitehouse.gov/malapropisms.xml. However, if somebody deletes that file, then it will try http://politics.slate.msn.com/default.aspx?id=76886 instead.

<xi:include href="http://www.whitehouse.gov/malapropisms.xml">
  <xi:fallback>
    <xi:include 
      href="http://politics.slate.msn.com/default.aspx?id=76886l" />
  </xi:fallback>
</xi:include>

The xi:fallback element is not used if the document can be located but is malformed. That is always a fatal error.

Processing

Related Reading XML in a Nutshell, 2nd Edition A Desktop Quick Reference By W. Scott Means, Elliotte Rusty Harold Table of Contents Index Sample Chapter Read Online--Safari

XInclusion is not part of XML 1.0 or the XML Infoset. XML parsers do not perform inclusions automatically. To resolve XIncludes, a document must be passed through an XInclude processor that replaces the xi:include elements with the documents they point to. This may be done automatically by a server side process or it might be done on the client side by an XInclude-aware browser. It may be hooked into a custom SAX program using a SAX filter that resolves the XIncludes. However, if you want this to happen, you need to ask for it and install the necessary software to make it possible.

One of the most common questions about XInclude is how inclusion interacts with validation, XSL transformation, and other processes that may be applied to an XML document. The short answer is that it doesn't. XInclusion is not part of any other XML process. It is a separate step which you may or may not perform when and where it is useful to you.

For example, consider validation against a schema. A document can be validated before inclusion, after inclusion, or both. If you validate the document before the xi:include elements are replaced, then the schema has to declare the xi:include elements just like it would declare any other element. If you validate the document after the xi:include elements are replaced, then the schema has to declare the replacement elements. Inclusion and validation are separate, orthogonal processes that can be performed in any order which is convenient in the local environment.

Software Support

Current support for XInclude is limited, though that is slowly changing. In particular,

• Libxml, the XML C library for Gnome, <http://xmlsoft.org/> includes fairly complete support for XInclude.

• The Apache Cocoon application server <http://xml.apache.org/cocoon/index.html> can resolve XIncludes in a document before sending it to a client. Processing instructions in the document's prolog control the exact operations performed and the order they're applied in.

• The 4Suite XML library for Python <http://4suite.org/> has an option to resolve XIncludes when parsing.

• GNU JAXP <http://www.gnu.org/software/classpathx/jaxp/> includes a SAX filter that resolves XIncludes, provided no XPointers are used.

---

---

2. include a part of an xml more times in the same file
   2004-06-29 03:37:54 Ste
4. xi:include - possible hitch
   2003-05-02 05:58:29 Jack Cane
6. Can a blob object be an attribute value in an XML file?
   2002-11-21 07:51:57 R 22
8. HREF source
   2002-08-14 16:23:26 Peter Ainsworth
10. What about IDREFs?
    2002-07-31 20:37:42 Micah Dubinko
• What about IDREFs?
  2002-08-02 05:05:20 user2048 user2048
• What about IDREFs?
  2002-08-03 21:56:15 Micah Dubinko