PROMOTE MODULARITY AND REUSABILITY WITH XINCLUDE

When working with XML documents, there are several basic concepts that
you need to master. The ability to include external documents within an
XML document is one of the basic functional elements of XML. We'll look
at a few applications of Xinclude, as well as examples of how to put
this basic concept to use.

MODULAR XML

There are many ways to implement and use inclusions in XML documents.
One of the main reasons for using includes is to promote modularity and
reusability. By building XML documents from smaller "component" XML
documents using includes, you'll be able to reuse more components and
write less code from scratch. You will also begin to see various
patterns in your XML documents that result in modules or components.
XInclude allows you to take advantage of XML modularity and implement 
it
effectively in your XML solutions.

INCLUSION EXAMPLE

Using XInclude is essentially a trivial process. The XInclude
specification is comprised of two elements - <xi:include /> and
<xi:fallback />. The <xi:include /> tag handles the actual inclusion of
external documents into the current document. The <xi:fallback /> tag 
is
a child element of <xi:include /> and it handles conditions where the
include doesn't succeed (due to a missing file, network failure, or for
some other reason).

Let's look at applying XInclude to a sample scenario. We'll start with
an example XML document, called PurchaseOrder.xml. This document
contains some basic purchase order data, such as customer information
and the ordered items.

PurchaseOrder.xml:

<?xml version='1.0' ?>
<PurchaseOrder>
  <CustomerInformation>
    <Account>99829923</Account>
    <Address type="ship">
      <Line>ATTN: Mr. Wobbles</Line>
      <Line>Widgetwoo Corp.</Line>
      <Line>1234 W Broadway</Line>
      <Line>New York, NY 10010</Line>
    </Address>
    <Address type="bill">
      <Line>ATTN: Accounts</Line>
      <Line>Widgetwoo Corp.</Line>
      <Line>1234 W Broadway</Line>
      <Line>New York, NY 10010</Line>
    </Address>
  </CustomerInformation>
  <OrderInformation>
    <Item>
      <Quantity>50</Quantity>
      <SKU>88344</SKU>
      <Description>Super Foowacker</Description>
      <PricePer>602.33</PricePer>
    </Item>
    <Item>
      <Quantity>200</Quantity>
      <SKU>9003</SKU>
      <Description>Turbo Electrifoo</Description>
      <PricePer>58.50</PricePer>
    </Item>
  </OrderInformation>
</PurchaseOrder>

Now, we'll split this document into two documents. We'll place all of
the <CustomerInformation/> elements into the first document, which 
we'll

call CustomerInformation.xml. Then, in the PurchaseOrder.xml document,
we'll include the customer information using XInclude.

CustomerInformation.xml:

<?xml version='1.0' ?>
<CustomerInformation>
  <Account>99829923</Account>
  <Address type="ship">
    <Line>ATTN: Mr. Wobbles</Line>
    <Line>Widgetwoo Corp.</Line>
    <Line>1234 W Broadway</Line>
    <Line>New York, NY 10010</Line>
  </Address>
  <Address type="bill">
    <Line>ATTN: Accounts</Line>
    <Line>Widgetwoo Corp.</Line>
    <Line>1234 W Broadway</Line>
    <Line>New York, NY 10010</Line>
  </Address>
</CustomerInformation>

PurchaseOrder.xml:

<?xml version='1.0' ?>
<PurchaseOrder  xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="CustomerInformation.xml">
  <OrderInformation>
    <Item>
      <Quantity>50</Quantity>
      <SKU>88344</SKU>
      <Description>Super Foowacker</Description>
      <PricePer>602.33</PricePer>
    </Item>
    <Item>
      <Quantity>200</Quantity>
      <SKU>9003</SKU>
      <Description>Turbo Electrifoo</Description>
      <PricePer>58.50</PricePer>
    </Item>
  </OrderInformation>
</PurchaseOrder>

The result of processing the new PurchaseOrder.xml will be the same as
if the document looked like the one we started out with. The essential
difference is that now we have moved some of the data out of the main
document and used XInclude.

CAVEATS

There are a handful of caveats related to using XInclude. The first is
that your include may fail. To illustrate, what happens when the
document you're including is on a Web server in Germany and the network
goes down? To handle this scenario, the XInclude specification provides
the <xi:fallback /> element. You can use <xi:fallback /> to indicate
alternate behavior when an <xi:include /> fails.

Another major caveat is to avoid circular references. Imagine if our
CustomerInformation.xml document contained an include of
PurchaseOrder.xml (which includes CustomerInformation.xml). Because 
each
document includes the other, the references become circular and
infinitely nested. A mechanism that uses circular references is not 
only
badly designed but also does not fall within the XInclude 
specification.


To find out more about XInclude and read the specification, visit the
W3C's Web site.
http://www.w3.org/TR/xinclude/

Brian Schaffner is a senior consultant for Fujitsu Consulting. He
provides architecture, design, and development support for Fujitsu's
Telcom360
group.