Processing Xml With Java - A Guide To Sax, Dom, Jdom, Jaxp, And Trax

Some Grammatical Notes

The rules of English grammar were laid down, written in stone, and encoded in the DNA of elementary school teachers long before computers were invented. Unfortunately, this means that sometimes I have to decide between syntactically correct code and syntactically correct English. When forced to do so, English normally loses. This means that sometimes a punctuation mark appears outside a quotation mark when you'd normally expect it to appear inside, a sentence begins with a lowercase letter, or something similarly unsettling occurs. For the most part, I've tried to use various typefaces to make the offending phrase less jarring. In particular, please note the following:

• Italicized text is used for emphasis, the first occurrence of an important term, titles of books and other cited works, words in languages other than English, words as words themselves (for example, Booboisie is a very funny word), Java system properties, host names, and resolvable URLs.

• Monospaced text is used for XML and Java source code, namespace URLs, system prompts, and program output.

• Italicized monospace text is used for pieces of XML and Java source code that should be replaced by some other text.

• Bold monospaced text is used for literal text that the user types at a command line, as well as for emphasis in code.

It's not just English grammar that gets a little squeezed, either. The necessities of fitting code onto a printed page rather than a computer screen have occasionally caused me to deviate from the ideal Java coding conventions. The worst problem is line length. I can fit only 65 characters across the page in a line of code. To try to make maximum use of this space, I indent each block by two spaces and indent line continuations by one space, rather than the customary four spaces and two spaces respectively. Even so, I still have to break lines where I otherwise would prefer not to. For example, I originally wrote this line of code for Chapter 4:

result.append("          <Amount>" + amount + "</Amount>\r\n"); 

To fit it on the page, however, I had to split it into two pieces, like this:

result.append("          <Amount>"); 
result.append(amount +"</Amount>\r\n");

This wasn't too bad, but sometimes even this wasn't enough and I had to remove indents from the front of the line that would otherwise be present. This occasionally forced the indentation not to line up as prettily as it otherwise might, as in this example from Chapter 3:

  wout.write( 
"xmlns='http://namespaces.cafeconleche.org/xmljava/ch3/'\r\n"
  );

The silver lining to this cloud is that sometimes the extra attention I give to the code when I'm trying to cut down its size results in better code. For example, in Chapter 4, I found I needed to remove a few characters from this line:

OutputStreamWriter wout = new OutputStreamWriter(out, "UTF8"); 

On reflection I realized that nowhere did the program actually need to know that wout was an OutputStreamWriter as opposed to merely a Writer. Thus I could easily rewrite the offending line as follows:

Writer wout = new OutputStreamWriter(out, "UTF8"); 

This follows the general object-oriented principle of using the least-specific type that will suit. This polymorphism makes the code more flexible in the future should I find a need to swap in a different kind of Writer.