An XML document is said to be well-formed if there is exactly one root element, it and every sub-element has delimiting start and end tags that are properly nested within each other and all attributes are quoted.

The following is a simple XML document with an XML declaration followed by a number of elements. The structure represents a list of jobs that could be used in the Agency case study example. In Listing 16.3, the <jobSummary> tag is the root tag followed by a number of jobs.

Listing 16.3 Example jobSummary XML

<?xml version ="1.0"?>
<jobSummary>
 <job>
 <customer>winston</customer>
 <reference>Cigar Trimmer</reference>
 <location>London</location>
 <description>Must like to talk and smoke</description>
 <skill>Cigar maker</skill>
 <skill>Critic</skill>
 </job>
 <job>
 <customer>george</customer>
 <reference>Tree pruner</reference>
 <location>Washington</location>
 <description>Must be honest</description>
 <skill>Tree surgeon</skill>
 </job>
</jobSummary>

Attributes

Attributes are name/value pairs that are associated with elements. There can be any number of attributes, and an element's attributes all appear inside the start tag. The names of attributes are case sensitive and are limited to the following characters: letters, digits, underscores _, periods ., and hyphens -. An attribute name must begin with a letter or underscore.

The value of an attribute is a text string delimited by quotes, either single or double quotes may be used. Unlike HTML, all attribute values in an XML document must be enclosed in quotes. Listing 16.4 shows the jobSummary XML document re-written to use attributes to hold some of the data.

Listing 16.4 JobSummary.xml XML with Attributes

<?xml version ="1.0"?>
<jobSummary>
 <job customer="winston" reference="Cigar Trimmer">
 <location>London</location>
 <description>Must like to talk and smoke</description>
 <skill>Cigar maker</skill>
 <skill>Critic</skill>
 </job>
 <job customer="george" reference="Tree pruner">
 <location>Washington</location>
 <description>Must be honest</description>
 <skill>Tree surgeon</skill>
 </job>
</jobSummary>

The choice of using nested elements or attributes is a contentious area. There are many schools of thought and it usually ends up being a matter of personal taste or corporate standards. Prior to the introduction of XML Schemas (see section "XML Schemas") there were advantages to using attributes when the values were constrained in some way; such as values that are numbers or specific patterns. XML Schemas also allow element values to be constrained in the same way as attribute values.

Comments

XML comments are introduced by <!-- and ended with -->, for example

<!-- this is a comment -->

Comments can appear anywhere in a document except within the tags, for example,

<item quantity="1lb">Cream cheese <!-- this is a comment --></item>

is acceptable, whereas the following is not

<item <!-- this is a comment --> quantity="1lb">Cream cheese </item>

---

Note - As with commenting code, the comments you add to your XML should be factually correct, useful, and to the point. They should be used to make the XML document easier to read and comprehend.

---

Any character is allowed in a comment, including those that cannot be used in elements and tags, but to maintain compatibility with SGML, the combination of two hyphens together (--) cannot be used within the text of a comment.

Comments should be used to annotate the XML, but you should be aware that the parser might remove the comments, so they may not always be accessible to a receiving application.

This chapter is from Teach Yourself J2EE in 21 Days, second edition, by Martin Bond et. al. (Sams, 2004, ISBN: 0-672-32558-6). Check it out at your favorite bookstore today. Buy this book now.