Java and XML - Beginning Java 2 SDK - page 995

Defining General Entities
There is a frequent requirement to repeat a given block of parsed character data in the body of a
document. An obvious example of this is some kind of copyright notice that you may want to insert in
various places. You can define a named block of parsed text like this:
<!ENTITY copyright "© 2002 Wrox Press">
This is an example of declaration of a general entity . You can put declarations of general entities within
a DOCTYPE declaration in the document prolog or within an external DTD. We will describe how a
little later in this chapter. The block of text that appears between the double quotes in the entity
declaration is identified by the name copyright . You could equally well use single quotes as
delimiters for the string. Wherever you want to insert this text in the document, you just need to insert
the name delimited by an & at the beginning and ; at the end, thus:
&copyright;
This is called an entity reference. This is exactly the same notation as the predefined entities
representing markup characters that we saw earlier. It will cause the equivalent text to be inserted at this
point when the document is parsed. Of course, since a general entity is parsed text, you need to take
care that the document is still well-formed and valid after the substitution has been made.
An entity declaration can include entity references. For instance, we could declare the copyright
entity like this:
<!ENTITY copyright "© 2002 Wrox Press &documentDate;">
The text contains a reference to a documentDate entity. Entity references may only appear in a
document after their corresponding entity declarations so the declaration for the documentDate entity
must precede the declaration for the copyright entity:
<!ENTITY documentDate "24th January 2002">
<!ENTITY copyright "© 2002 Wrox Press &documentDate;">
Entity declarations can contain nested entity references to any depth so the declaration for the
documentDate entity could contain other entity references. Substitutions for entity references will be
made recursively by the XML processor until all references have been resolved. An entity declaration
must not directly or indirectly contain a reference to itself though.
You can also use general entities that are defined externally. You use the SYSTEM keyword followed by
the URL for where the text is stored in place of the text in the ENTITY declaration. For instance:
<!ENTITY usefulstuff SYSTEM "http://www.some-server.com/inserts/stuff.txt">
The reference &usefulstuff; represents the contents of the file stuff.txt .