epubjs
Version:
Render ePub documents in the browser, across many devices
66 lines (65 loc) • 9.27 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>XInclude</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="XInclude"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-24-SECT-6"/>XInclude</h1></div></div></div><p><a id="idx11208" class="indexterm"/> <a id="idx11227" class="indexterm"/>XInclude is a very simple “import” facility for XML
documents. With the XInclude directive, you can easily include one XML
document in another either as XML or as plain (and escaped) text. This
means that you can break down your documents into as many files as you see
fit and reference the pieces in a simple, standard way. We should note
that it is also possible to do this in another way, using XML entity
declarations, but they are fraught with problems. XInclude is simpler and
does what its name implies, including the specified document at the
current location; you just have to declare the proper namespace for the
new <a id="I_indexterm24_id832834" class="indexterm"/><code class="literal"><include></code> element.
Here is an example:</p><a id="I_24_tt1326"/><pre class="programlisting"> <code class="o"><</code><code class="n">Book</code> <code class="nl">xmlns:</code><code class="n">xi</code><code class="o">=</code><code class="s">"http://www.w3.org/2001/XInclude"</code><code class="o">></code>
<code class="o"><</code><code class="n">Title</code><code class="o">></code><code class="n">Learning</code> <code class="n">Java</code><code class="o"></</code><code class="n">Title</code><code class="o">></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">href</code><code class="o">=</code><code class="s">"chapter1.xml"</code><code class="o">/></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">href</code><code class="o">=</code><code class="s">"chapter2.xml"</code><code class="o">/></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">href</code><code class="o">=</code><code class="s">"chapter3.xml"</code><code class="o">/></code>
<code class="o">...</code>
<code class="o"></</code><code class="n">Book</code><code class="o">></code></pre><p>We’ve used the namespace identifier <code class="literal">xi</code> to qualify the <code class="literal"><include></code> elements that we use to import
the chapters of our book. By default, the file is imported as XML content,
which means that the parser incorporates the included document as part of
our document. The resulting DOM or SAX view will show the merged documents
as one. Alternatively, we can use the <a id="I_indexterm24_id832875" class="indexterm"/><code class="literal">parse</code> attribute to
specify that we want the target included as text only. In this case, the
text is automatically escaped for us like a CDATA section. For example, we
could use it to include an XML example in our book without danger of it
being intepreted as part of our file:</p><a id="I_24_tt1327"/><pre class="programlisting"> <code class="o"><</code><code class="n">Example</code><code class="o">></code>
<code class="o"><</code><code class="n">Title</code><code class="o">></code><code class="n">The</code> <code class="n">Zoo</code> <code class="n">Inventory</code> <code class="n">Example</code><code class="o"></</code><code class="n">Title</code><code class="o">></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">parse</code><code class="o">=</code><code class="s">"text"</code> <code class="n">href</code><code class="o">=</code><code class="s">"zooinventory.xml"</code><code class="o">/></code>
<code class="o"></</code><code class="n">Example</code><code class="o">></code></pre><p>Here, the entire <span class="emphasis"><em>zooinventory.xml</em></span> file will be
included as nicely escaped text for us (not added to our document as
XML).</p><p>XInclude also allows for “fallback” content to be specified using a
nested <a id="I_indexterm24_id832909" class="indexterm"/><code class="literal">fallback</code> element. The
<code class="literal">fallback</code> element may point to another
file or simply hold XML to be used if the included file can’t be found.
For example:</p><a id="I_24_tt1328"/><pre class="programlisting"><code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">parse</code><code class="o">=</code><code class="s">"text "</code> <code class="n">href</code><code class="o">=</code><code class="s">"zooinventory.xml"</code><code class="o">></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">fallback</code> <code class="n">href</code><code class="o">=</code><code class="s">"filenotfound.xml"</code><code class="o">/></code>
<code class="o"></</code><code class="nl">xi:</code><code class="n">include</code><code class="o">></code>
<code class="err"> </code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">include</code> <code class="n">parse</code><code class="o">=</code><code class="s">"text"</code> <code class="n">href</code><code class="o">=</code><code class="s">"example.xml"</code><code class="o">></code>
<code class="o"><</code><code class="nl">xi:</code><code class="n">fallback</code><code class="o">></code><code class="n">This</code> <code class="n">example</code> <code class="n">is</code> <code class="n">missing</code><code class="o">...</</code><code class="nl">xi:</code><code class="n">fallback</code><code class="o">></code>
<code class="o"></</code><code class="nl">xi:</code><code class="n">include</code><code class="o">></code></pre><p>In the first case, if <span class="emphasis"><em>zooinventory.xml</em></span> is not
found, the <span class="emphasis"><em>filenotfound.xml</em></span> file will be included. In
the second case, the “missing” text will be included instead of the file.
If there is no fallback specified, a parse-time fatal error occurs. An
empty <code class="literal">fallback</code> element can be used to
suppress any error. Fallbacks may also be nested within fallbacks to
combine these behaviors.</p><div class="sect2" title="Enabling XInclude"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-24-SECT-6.1"/>Enabling XInclude</h2></div></div></div><p>Getting XInclude to work for us requires simply turning on a
couple of flags before we begin parsing our file. First, because the
XInclude facility uses namespaces, we have to turn on namespace
processing in our parser factory. Second, we have to explicitly tell the
parser to interpret the include directives. To modify our <code class="literal">PrintDOM</code> example to perform the includes before printing the
result, we turn these flags on the factory before creating a <code class="literal">DocumentBuilder</code> instance:</p><a id="I_24_tt1329"/><pre class="programlisting"><code class="n">DocumentBuilderFactory</code> <code class="n">factory</code> <code class="o">=</code> <code class="n">DocumentBuilderFactory</code><code class="o">.</code><code class="na">newInstance</code><code class="o">();</code>
<code class="err"> </code>
<code class="c1">// enable XInclude processing</code>
<code class="n">factory</code><code class="o">.</code><code class="na">setNamespaceAware</code><code class="o">(</code> <code class="kc">true</code> <code class="o">);</code>
<code class="n">factory</code><code class="o">.</code><code class="na">setXIncludeAware</code><code class="o">(</code> <code class="kc">true</code> <code class="o">);</code>
<code class="err"> </code>
<code class="n">DocumentBuilder</code> <code class="n">parser</code> <code class="o">=</code> <code class="n">factory</code><code class="o">.</code><code class="na">newDocumentBuilder</code><code class="o">();</code>
<code class="n">Document</code> <code class="n">document</code> <code class="o">=</code> <code class="n">parser</code><code class="o">.</code><code class="na">parse</code><code class="o">(</code> <code class="n">input</code> <code class="o">);</code></pre><p>Both of those options should really be the defaults these days.
But they have historically come later to XML and so been treated as
special features that have to be enabled. We should also mention before
we move on that XInclude can make use of XPath expressions (via an API
called XPointer) in order to include just selected parts of an XML
document.<a id="I_indexterm24_id833005" class="indexterm"/><a id="I_indexterm24_id833012" class="indexterm"/></p></div></div></body></html>