XML was originally created simply to allow for documents to be authored (marked up) in a variety of formats. Because XML is primarily a language for representing static data, the idea of variables, value substitution, and other dynamic data representations were not considered (at least, not much!). As a result, XML documents often end up with redundant data, inconsistent data, and a variety of other problems that result from purely static data formats.

XML does have a limited facility for dynamic data, and it turns out that this facility can empower XML authors greatly. That facility, of course, is entity references. In this tip, I examine entity references in detail, explaining how they are used and what they offer you, the XML document author.

I realize that this is one of those topics in XML that can seem a little mysterious and obscure. However, you can simply think of an entity reference as a variable in XML; that variable has a value that's declared somewhere, and every time the variable occurs, the parser substitutes that value in the output. More specifically and accurately, an entity reference is like a static, final variable in the Java language. It cannot change from its initial value, which is defined in a DTD somewhere.

While many times an entity reference refers to an online resource, it can also have a value defined for it in a DTD, as in Listing 1.

<!ENTITY variableName "variable value">

Instead of typing "variable value" several times in your XML document (and possibly introducing typos and user error), you can just refer to the value through the reference, as shown in Listing 2.

<content>The variable's value is &variableName;.</content>

Of course, this seems pretty trivial, so let's look at a more realistic example. Listing 3 shows a simple XML document fragment that's intended for display on a Web page somewhere.

<page>
  <title>Simplify with entity references</title>
  <content type="html">
    <center><h1>Simplify with entity references</h1></center>
    <p>
      This tip, <i>Simplify with entity references</i>, details an underused facet of
	  XML document authoring. So on and so on, ad nauseum, ad infinitum.
    </p>
  </content>
</page>

Notice that the title "Simplify with entity references" was repeated three times. Not only does this introduce room for error, it makes it a pain to change all occurrences (of which there may be a dozen or more in this and related documents in the future). This makes the document a good candidate for an entity reference. First, add the definition of the entity to your DTD, as in Listing 4.

<!ENTITY articleTitle "Simplify with entity references">

Then, change the XML to look like that in Listing 5.

<page>
  <title>&articleTitle;</title>
  <content type="html">
    <center><h1>&articleTitle;</h1></center>
    
    <p>
      This tip, <i>&articleTitle;</i>, details an underused facet of
	  XML document authoring. So on and so on, ad nauseum, ad infinitum.
    </p>
  </content>
</page>

Now, by simply changing the entity reference's value, you can change all references in the XML document to the new value.

In addition, you can move the entity definition from the DTD into the XML document itself, as seen in Listing 6.

<?xml version="1.0"?>
<!DOCTYPE page [
  <!ENTITY articleTitle "O'Reilly J2EE Best Practices">
]>

<page>
  <title>&articleTitle;</title>
  <content type="html">
    <center><h1>&articleTitle;</h1></center>
    <p>
      This tip, <i>&articleTitle;</i>, details an underused facet of
	  XML document authoring. So on and so on, ad nauseum, ad infinitum.
    </p>
  </content>
</page>

While this won't necessarily improve the performance of your document parsing, it certainly is a better organizational approach, and makes maintenance significantly easier. The only time you might want to move the entity reference outside of the document is when multiple documents share data, and all use a shared entity reference.

This tends to be one of those features of XML that many people see and dismiss as trivial. However, in large documents entity references can be a life-saver, allowing you to avoid typos that result from typing the same data over and over again. Adding entity references to your arsenal of XML tools will only improve your document authoring. So brush up on the entity reference, and I'll see you soon!

Resources

• Check out the SAX API to find out more about the Simple API for XML.
  
  
• Take an in-depth look at SAX right here on developerWorks with Nicholas Chase's tutorial Understanding SAX, which examines the use of SAX 2.0. (September 2001)
  
  
• Doug Tidwell's Introduction to XML tutorial on developerWorks provides a solid foundation for understanding XML issues like document rules, defining document content, programming interfaces, and XML standards. (August 2002)
  
  
• Find more XML resources on the developerWorks XML zone. For a complete list of XML tips to date, check out the tips summary page.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  
• Find out how you can become an IBM Certified Developer in XML and related technologies.
  
  
• Want us to send you useful XML tips like this every week? Sign up for the developerWorks XML Tips newsletter.
  
  

About the author

Brett McLaughlin has been working in computers since the Logo days (remember the little triangle?). He currently specializes in building application infrastructure using the Java language and Java-related technologies. He has spent the last several years implementing these infrastructures at Nextel Communications and Allegiance Telecom, Inc. Brett is one of the co-founders of the Java Apache project Turbine, which builds a reusable component architecture for Web application development using Java servlets. He is also a contributor of the EJBoss project, an open source EJB application server, and Cocoon, an open source XML Web-publishing engine.

Rate this article

Comments

Back to top

Table of contents

• Resources
• About the author
• Comments