Presents your 
XML E-NEWSLETTER for June 19, 2002

<------------------------------------------->

EASE CONFIGURATIONS USING INTERNAL ENTITIES

XML has proliferated through much of software architecture and one area
in which it is used extensively is in configuration. Particularly in
Web-based application servers, XML is very useful in specifying 
configuration
parameters.

A common problem is the necessity of having to change parameters 
between
development and testing and development environments. This is 
especially
a nuisance when the parameter is a directory or file-system path, which
has to be changed in multiple places. Let's look at how you can ease 
some
of these configuration issues by using internal entities.

SAMPLE PROBLEM

We'll start by creating a simplified example of this problem. Listing 1
shows a small XML configuration file for an application. As you can 
see,
there are multiple parameters that reference a physical file-system 
path.
Moving this configuration from one machine to another may require you 
to
retype every parameter!

Listing 1: myapp.xml

<?xml version="1.0" ?>
<MyConfiguration>
  <Templates>
    <Template name="temp1">C:\MyApp\Templates\template1.xsl</Template>
    <Template name="temp2">C:\MyApp\Templates\template2.xsl</Template>
    <Template name="temp3">C:\MyApp\Templates\template3.xsl</Template>
  </Templates>
  <Logs>
    <Log name="stdout">C:\MyApp\Logs\myapp.log</Log>
    <Log name="error">C:\MyApp\Logs\error.log</Log>
  </Logs>
</MyConfiguration>

Keep in mind that this is a simplistic example. A real configuration
file might be hundreds of lines long. Also, it's unlikely that the
path-oriented parameters are nicely grouped together like they are 
here.

SIMPLE SOLUTION

To solve this problem, we'll use "internal entities." You are probably
already familiar with XML entities. Basically, an entity is a piece of
data used in the XML document with a reference rather than literal 
content.
A good example is the "greater-than" symbol. Because it is a special
character in XML, you can't simply put one in your document. Instead, 
you
have to reference it through the associated XML entity. Rather than 
placing
> in your document, you use &gt;.

Every XML entity has this form (ampersand-name-semicolon). There are
five predefined entities available in every XML document. They are:


* ampersand = &amp;

* greater-than = &gt;

* less-than = &lt;

* apostrophe = &apos;

* double-quote = &quot;


We can easily define new entities inside of our XML document in what is
called the "internal subset." The internal subset is a subset of a DTD
that is defined internal to the XML document. Here's an example of a 
simple
DTD declaration used in an XML file:

<!DOCTYPE MyConfiguration SYSTEM "MyConfiguration.dtd">

This declaration references only an external subset of the DTD. We want
to add an internal subset to this DTD. Simply appending our internal
entity declarations within square brackets and within the DOCTYPE 
declaration
accomplishes this. Here's an example:

<!DOCTYPE MyConfiguration SYSTEM "MyConfiguration.dtd" [
<!ENTITY MyEntity "the value of the entity">
]>

Notice that because the ENTITY and DOCTYPE declarations are part of the
DTD specifications (and not the XML specifications) they have no close
tags or trailing slashes. You may not be using DTD validation for your
document, in which case, you won't have an external subset. Here's an 
example
that has only an internal subset:

<!DOCTYPE MyConfiguration [
<!ENTITY MyEntity "the value of the entity">
]>

Right now, our configuration file has literal text for the content of
the Template and Log elements. In order to use entity references, we'll
define a new entity in the internal subset of our document. Because we 
are
not currently using a DTD to validate this configuration file, we'll 
use
the simple internal subset like this:

<!DOCTYPE MyConfiguration [
<!ENTITY InstallDir "C:\MyApp">
]>

Now, we can create a new configuration document that should have only
one place to modify the path where software is installed. Listing 2 
shows
the revised XML file.

Listing 2: myapp.xml

<?xml version="1.0" ?>
<!DOCTYPE MyConfiguration [
<!ENTITY InstallDir "C:\MyApp">
]>
<MyConfiguration>
  <Templates>
    <Template
name="temp1">&InstallDir;\Templates\template1.xsl</Template>
    <Template
name="temp2">&InstallDir;\Templates\template2.xsl</Template>
    <Template
name="temp3">&InstallDir;\Templates\template3.xsl</Template>
  </Templates>
  <Logs>
    <Log name="stdout">&InstallDir;\Logs\myapp.log</Log>
    <Log name="error">&InstallDir;\Logs\error.log</Log>
  </Logs>
</MyConfiguration>

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

----------------------------------------