<?xml version="1.0" encoding="UTF-16"?>
<rss version="2.0"><channel><title>SoftXML | JAXPSAX Tutorials</title><link>http://www.softxml.com/rss/tutorials/jaxpsax.xml</link><description>Tutorials</description><pubDate>Sun, 11 Jan 2009 14:27:51 EST</pubDate><language>en-us</language><image><title>SoftXML | JAXPSAX Tutorials</title><url>http://www.softxml.com/images/rsscategory.gif</url><link>http://www.softxml.com/rss/tutorials/jaxpsax.xml</link><width>80</width><height>73</height></image><item><title>Simple API for XML</title><link>http://www.softxml.com/LearnTutorial.asp?id=2862224685&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;a name="wp66436"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In this chapter we focus on the Simple API for XML (SAX), an
event-driven, serial-access mechanism for accessing XML documents. This
protocol is frequently used by servlets and network-oriented programs
that need to transmit and receive XML documents, because it's the
fastest and least memory-intensive mechanism that is currently
available for dealing with XML documents, other than StAX.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp98989"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: In a nutshell, SAX is oriented towards &lt;span style="font-style: italic;"&gt;state independent&lt;/span&gt;
processing, where the handling of an element does not depend on the
elements that came before. StAX, on the other hand, is oriented towards
&lt;span style="font-style: italic;"&gt;state dependent&lt;/span&gt; processing. For a more detailed comparison, see SAX and StAX in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/XMLStandards2.html#wp81561"&gt;Basic Standards&lt;/a&gt; and &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPSAX2.html#wp72451"&gt;When to Use SAX&lt;/a&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64005"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Setting up a program to use SAX requires a bit more work than setting
up to use the Document Object Model (DOM). SAX is an event-driven model
(you provide the callback methods, and the parser invokes them as it
reads the XML data), and that makes it harder to visualize. Finally,
you can't "back up" to an earlier part of the document, or rearrange
it, any more than you can back up a serial data stream or rearrange
characters you have read from that stream.
&lt;/p&gt;
&lt;a name="wp64006"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;For those reasons, developers
who are writing a user-oriented application that displays an XML
document and possibly modifies it will want to use the DOM mechanism
described in Chapter &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPDOM.html#wp79996"&gt;6&lt;/a&gt;.
&lt;/p&gt;
&lt;a name="wp64010"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
However, even if you plan to build DOM applications exclusively, there
are several important reasons for familiarizing yourself with the SAX
model: &lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp64011"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;&lt;span style="font-weight: bold;"&gt;Same Error Handling:&lt;/span&gt; The same kinds of exceptions are generated by the SAX and DOM APIs, so the error handling code is virtually identical.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp64013"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;&lt;span style="font-weight: bold;"&gt;Handling Validation Errors:&lt;/span&gt;
By default, the specifications require that validation errors (which
you'll learn more about in this part of the tutorial) are ignored. If
you want to throw an exception in the event of a validation error (and
you probably do), then you need to understand how SAX error handling
works.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=2862224685&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>When to Use SAX</title><link>http://www.softxml.com/LearnTutorial.asp?id=1597174412&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;a name="wp97869"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
It is helpful to understand the SAX event model when you want to convert existing data to XML. As you'll see in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPXSLT5.html#wp64712"&gt;Generating XML from an Arbitrary Data Structure&lt;/a&gt;, the key to the conversion process is to modify an existing application to deliver SAX events as it reads the data.
&lt;/p&gt;
&lt;a name="wp97878"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
SAX is fast and efficient, but its event model makes it most useful for
such state-independent filtering. For example, a SAX parser calls one
method in your application when an element tag is encountered and calls
a different method when text is found. If the processing you're doing
is state-independent (meaning that it does not depend on the elements
have come before), then SAX works fine.
&lt;/p&gt;
&lt;a name="wp97915"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;On the other hand, for
state-dependent processing, where the program needs to do one thing
with the data under element A but something different with the data
under element B, then a &lt;span style="font-style: italic;"&gt;pull parser&lt;/span&gt;
such as the Streaming API for XML (StAX) would be a better choice. With
a pull parser, you get the next node, whatever it happens to be, at any
point in the code that you ask for it. So it's easy to vary the way you
process text (for example), because you can process it multiple places
in the program. (For more detail, see &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPSAX13.html#wp93295"&gt;Further Information&lt;/a&gt;.)
&lt;/p&gt;
&lt;a name="wp97889"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
SAX requires much less memory than DOM, because SAX does not construct
an internal representation (tree structure) of the XML data, as a DOM
does. Instead, SAX simply sends data to the application as it is read;
your application can then do whatever it wants to do with the data it
sees.
&lt;/p&gt;
&lt;a name="wp97879"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Pull parsers and the SAX API
both act like a serial I/O stream. You see the data as it streams in,
but you can't go back to an earlier position or leap ahead to a
different position. In general, such parsers work well when you simply
want to read data and have the application act on it.
&lt;/p&gt;
&lt;a name="wp97873"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;But when you need to modify an
XML structure--especially when you need to modify it interactively--an
in-memory structure makes more sense. DOM is one such model. However,
although DOM provides many powerful capabilities for large-scale
documents (like books and articles), it also requires a lot of complex
coding. The details of that process are highlighted in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPDOM2.html#wp67733"&gt;When to Use DOM&lt;/a&gt;.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=1597174412&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Echoing an XML File with the SAX Parser</title><link>http://www.softxml.com/LearnTutorial.asp?id=13479781032&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
In real life, you will have little need to echo an XML file with a SAX
parser. Usually, you'll want to process the data in some way in order
to do something useful with it. (If you want to echo it, it's easier to
build a DOM tree and use that for output.) But echoing an XML structure
is a great way to see the SAX parser in action, and it can be useful
for debugging. &lt;/p&gt;
&lt;a name="wp64192"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In this exercise, you'll echo SAX parser events to &lt;code class="cCode"&gt;System.out&lt;/code&gt;.
Consider it the "Hello World" version of an XML-processing program. It
shows you how to use the SAX parser to get at the data and then echoes
it to show you what you have. &lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64193"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code discussed in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo01.java" target="_blank"&gt;Echo01.java&lt;/a&gt;&lt;/code&gt;. The file it operates on is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample01.xml" target="_blank"&gt;slideSample01.xml&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp67589"&gt;Writing a Simple XML File&lt;/a&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample01-xml.html" target="_blank"&gt;slideSample01-xml.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64195"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Creating the Skeleton
&lt;/h3&gt;
&lt;a name="wp64196"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Start by creating a file named&lt;span style="font-weight: bold;"&gt; &lt;/span&gt;&lt;code class="cCode"&gt;Echo.java&lt;/code&gt; and enter the skeleton for the application:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCode"&gt;public class Echo
&lt;/code&gt;{
  public static void main(String argv[])
  {&lt;a name="wp64197"&gt; &lt;/a&gt;
     }&lt;a name="wp64198"&gt; &lt;/a&gt;
}&lt;a name="wp64199"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64200"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Because you'll run it standalone, you need a &lt;code class="cCode"&gt;main&lt;/code&gt; method. And you need command-line arguments so that you can tell the application which file to echo.
&lt;/p&gt;
&lt;a name="wp64202"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Importing Classes
&lt;/h3&gt;
&lt;a name="wp64203"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, add the &lt;code class="cCode"&gt;import&lt;/code&gt; statements for the classes the application will use:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;import java.io.*;
import org.xml.sax.*;
import org.xml.sax.helpers.DefaultHandler;
import javax.xml.parsers.SAXParserFactory; 
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParser;&lt;a name="wp64204"&gt; &lt;/a&gt;
public class Echo
{
  ...&lt;a name="wp64205"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64206"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The classes in &lt;code class="cCode"&gt;java.io&lt;/code&gt;, of course, are needed to do output. The &lt;code class="cCode"&gt;org.xml.sax&lt;/code&gt; package defines all the interfaces we use for the SAX parser. The &lt;code class="cCode"&gt;SAXParserFactory&lt;/code&gt; class creates the instance we use. It throws a &lt;code class="cCode"&gt;ParserConfigurationException&lt;/code&gt;
if it cannot produce a parser that matches the specified configuration
of options. (Later, you'll see more about the configuration options.)
The &lt;code class="cCode"&gt;SAXParser&lt;/code&gt; is what the factory returns for parsing, and the &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; defines the class that will handle the SAX events that the parser generates. 
&lt;/p&gt;
&lt;a name="wp64208"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Setting Up for I/O
&lt;/h3&gt;
&lt;a name="wp64209"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The first order of business is to process the command-line argument,
get the name of the file to echo, and set up the output stream. Add the
following highlighted text to take care of those tasks and do a bit of
additional housekeeping: &lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public static void main(String argv[])

{
&lt;code class="cCodeBold"&gt;  if (argv.length != 1) {
    System.err.println("Usage: cmd filename");
    System.exit(1);
  }
  try {
    // Set up output stream
    out = new OutputStreamWriter(System.out, "UTF8");
  } 
  catch (Throwable t) {
      t.printStackTrace();
  }
  System.exit(0);
&lt;/code&gt;}

&lt;code class="cCodeBold"&gt;static private Writer out;&lt;/code&gt;&lt;a name="wp64210"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64213"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When we create the output stream writer, we are selecting the UTF-8
character encoding. We could also have chosen US-ASCII or UTF-16, which
the Java platform also supports. For more information on these
character sets, see &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Encodings.html#wp64176"&gt;Java Encoding Schemes&lt;/a&gt;.
&lt;/p&gt;
&lt;a name="wp64218"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Implementing the ContentHandler Interface
&lt;/h3&gt;
&lt;a name="wp64219"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The most important interface for our current purposes is &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt;.
This interface requires a number of methods that the SAX parser invokes
in response to various parsing events. The major event-handling methods
are: &lt;code class="cCode"&gt;startDocument&lt;/code&gt;, &lt;code class="cCode"&gt;endDocument&lt;/code&gt;, &lt;code class="cCode"&gt;startElement&lt;/code&gt;, &lt;code class="cCode"&gt;endElement&lt;/code&gt;, and &lt;code class="cCode"&gt;characters&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp99195"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The easiest way to implement this interface is to extend the &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; class, defined in the &lt;code class="cCode"&gt;org.xml.sax.helpers&lt;/code&gt; package. That class provides do-nothing methods for all the &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; events. Enter the following highlighted code to extend that class:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public class Echo &lt;code class="cCodeBold"&gt;extends DefaultHandler
&lt;/code&gt;{
  ...
}&lt;a name="wp67414"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp67415"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; also defines do-nothing methods for the other major events, defined in the &lt;code class="cCode"&gt;DTDHandler&lt;/code&gt;, &lt;code class="cCode"&gt;EntityResolver&lt;/code&gt;, and &lt;code class="cCode"&gt;ErrorHandler&lt;/code&gt; interfaces. You'll learn more about those methods as we go along.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64224"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Each of these methods is required by the interface to throw a &lt;code class="cCode"&gt;SAXException&lt;/code&gt;.
An exception thrown here is sent back to the parser, which sends it on
to the code that invoked the parser. In the current program, this
sequence means that it winds up back at the &lt;code class="cCode"&gt;Throwable&lt;/code&gt; exception handler at the bottom of the &lt;code class="cCode"&gt;main&lt;/code&gt; method. 
&lt;/p&gt;
&lt;a name="wp64225"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When a start tag or end tag is encountered, the name of the tag is passed as a &lt;code class="cCode"&gt;String&lt;/code&gt; to the &lt;code class="cCode"&gt;startElement&lt;/code&gt; or the &lt;code class="cCode"&gt;endElement&lt;/code&gt; method, as appropriate. When a start tag is encountered, any attributes it defines are also passed in an &lt;code class="cCode"&gt;Attributes&lt;/code&gt; list. Characters found within the element are passed as an array of characters, along with the number of characters (&lt;code class="cCode"&gt;length&lt;/code&gt;) and an offset into the array that points to the first character.
&lt;/p&gt;
&lt;a name="wp64227"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Setting up the Parser
&lt;/h3&gt;
&lt;a name="wp64228"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now (at last) you're ready to set up the parser. Add the following highlighted code to set it up and get it started:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public static void main(String argv[])
{
  if (argv.length != 1) {
    System.err.println("Usage: cmd filename");
    System.exit(1);
  }&lt;a name="wp64229"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;  // Use an instance of ourselves as the SAX event handler
  DefaultHandler handler = new Echo();&lt;/code&gt;&lt;a name="wp64230"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;  // Use the default (non-validating) parser
  SAXParserFactory factory = SAXParserFactory.newInstance();
&lt;/code&gt;  try {
    // Set up output stream
    out = new OutputStreamWriter(System.out, "UTF8");&lt;a name="wp64231"&gt; &lt;/a&gt;
    &lt;code class="cCodeBold"&gt;// Parse the input 
    SAXParser saxParser = factory.newSAXParser();
    saxParser.parse( new File(argv[0]), handler );&lt;/code&gt;&lt;a name="wp64232"&gt; &lt;/a&gt;
  } catch (Throwable t) {
    t.printStackTrace();
  }
  System.exit(0);
}&lt;a name="wp64233"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64234"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
With these lines of code, you create a &lt;code class="cCode"&gt;SAXParserFactory&lt;/code&gt; instance, as determined by the setting of the &lt;code class="cCode"&gt;javax.xml.parsers.SAXParserFactory&lt;/code&gt;
system property. You then get a parser from the factory and give the
parser an instance of this class to handle the parsing events, telling
it which input file to process.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64235"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The &lt;code class="cCode"&gt;javax.xml.parsers.SAXParser&lt;/code&gt; class is a wrapper that defines a number of convenience methods. It wraps the (somewhat less friendly) &lt;code class="cCode"&gt;org.xml.sax.Parser&lt;/code&gt; object. If needed, you can obtain that parser using the &lt;code class="cCode"&gt;SAXParser&lt;/code&gt;'s &lt;code class="cCode"&gt;getParser()&lt;/code&gt; method.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64236"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;For now, you are simply
catching any exception that the parser might throw. You'll learn more
about error processing in a later section of this chapter, &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPSAX5.html#wp64579"&gt;Handling Errors with the Nonvalidating Parser&lt;/a&gt;.
&lt;/p&gt;
&lt;a name="wp64241"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Writing the Output
&lt;/h3&gt;
&lt;a name="wp64242"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; methods throw &lt;code class="cCode"&gt;SAXException&lt;/code&gt;s but not &lt;code class="cCode"&gt;IOException&lt;/code&gt;s, which can occur while writing. The &lt;code class="cCode"&gt;SAXException&lt;/code&gt;
can wrap another exception, though, so it makes sense to do the output
in a method that takes care of the exception-handling details. Add the
following highlighted code to define an &lt;code class="cCode"&gt;emit&lt;/code&gt; method that does that:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCode"&gt;static private Writer out;&lt;/code&gt;&lt;a name="wp64243"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;private void emit(String s)
throws SAXException
{
  try {
    out.write(s);
    out.flush();
  } catch (IOException e) {
    throw new SAXException("I/O error", e);
  }
}
&lt;/code&gt;...&lt;a name="wp64244"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64245"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When &lt;code class="cCode"&gt;emit&lt;/code&gt; is called, any I/O error is wrapped in &lt;code class="cCode"&gt;SAXException&lt;/code&gt;
along with a message that identifies it. That exception is then thrown
back to the SAX parser. You'll learn more about SAX exceptions later.
For now, keep in mind that &lt;code class="cCode"&gt;emit&lt;/code&gt; is a small method that handles the string output. (You'll see it called often in later code.)
&lt;/p&gt;
&lt;a name="wp64247"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Spacing the Output
&lt;/h3&gt;
&lt;a name="wp64248"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here is another bit of infrastructure we need before doing some real
processing. Add the following highlighted code to define an &lt;code class="cCode"&gt;nl()&lt;/code&gt; method that writes the kind of line-ending character used by the current system:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;private void emit(String s) 
  ...
}&lt;a name="wp64249"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;private void nl()
throws SAXException
{
  String lineEnd = System.getProperty("line.separator");
  try {
    out.write(lineEnd);
  } catch (IOException e) {
    throw new SAXException("I/O error", e);
  }
&lt;/code&gt;}&lt;a name="wp64250"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64251"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Although it seems like a bit of a nuisance, you will be invoking &lt;code class="cCode"&gt;nl()&lt;/code&gt;
many times in later code. Defining it now will simplify the code later
on. It also provides a place to indent the output when we get to that
section of the tutorial.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64253"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Handling Content Events
&lt;/h3&gt;
&lt;a name="wp64254"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Finally, let's write some code that actually processes the &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; events. 
&lt;/p&gt;
&lt;a name="wp71040"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Document Events
&lt;/h4&gt;
&lt;a name="wp71041"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted code to handle the start-document and end-document events:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;static private Writer out;
&lt;code class="cCodeBold"&gt;
public void startDocument()
throws SAXException
{
  emit("&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt;");
  nl();
}

public void endDocument()
throws SAXException
{
  try {
    nl();
    out.flush();
  } catch (IOException e) {
    throw new SAXException("I/O error", e);
  }
}&lt;/code&gt;&lt;a name="wp64255"&gt; &lt;/a&gt;
private void echoText()
...&lt;a name="wp64256"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64257"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, you are echoing an XML declaration when the parser encounters the start of the document. Because you set up &lt;code class="cCode"&gt;OutputStreamWriter&lt;/code&gt; using UTF-8 encoding, you include that specification as part of the declaration.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp99927"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: However, the IO classes don't understand the hyphenated encoding names, so you specified &lt;code class="cCode"&gt;UTF8&lt;/code&gt; for the &lt;code class="cCode"&gt;OutputStreamWriter&lt;/code&gt; rather than &lt;code class="cCode"&gt;UTF-8&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp99928"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
At the end of the document, you simply put out a final newline and flush the output stream. Not much going on there. 
&lt;/p&gt;
&lt;a name="wp99288"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Element Events
&lt;/h4&gt;
&lt;a name="wp99289"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now for the interesting stuff. Add the following highlighted code to process the start-element and end-element events:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;public void startElement(String namespaceURI,
        String sName, // simple name
        String qName, // qualified name
        Attributes attrs)
throws SAXException
{
  String eName = sName; // element name
  if ("".equals(eName)) eName = qName; // not namespace-aware
  emit("&amp;lt;"+eName);
  if (attrs != null) {
    for (int i = 0; i &amp;lt; attrs.getLength(); i++) {
      String aName = attrs.getLocalName(i); // Attr name
      if ("".equals(aName)) aName = attrs.getQName(i);
      emit(" ");
      emit(aName+"=\""+attrs.getValue(i)+"\"");
    }
  }
  emit("&amp;gt;");
}&lt;/code&gt;&lt;a name="wp67437"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;public void endElement(String namespaceURI,
        String sName, // simple name
        String qName  // qualified name
        )
throws SAXException
{
  String eName = sName; // element name
  if ("".equals(eName)) eName = qName; // not namespace-aware
  emit("&amp;lt;/"+eName+"&amp;gt;");
}&lt;/code&gt;&lt;a name="wp64261"&gt; &lt;/a&gt;
private void emit(String s)
...&lt;a name="wp64263"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64264"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
With this code, you echo the element tags, including any attributes defined in the start tag. Note that when the &lt;code class="cCode"&gt;startElement()&lt;/code&gt; method is invoked, if namespace processing is not enabled, then the simple name (&lt;span style="font-style: italic;"&gt;local name&lt;/span&gt;)
for elements and attributes could turn out to be the empty string. The
code handles that case by using the qualified name whenever the simple
name is the empty string.
&lt;/p&gt;
&lt;a name="wp71050"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Character Events
&lt;/h4&gt;
&lt;a name="wp64265"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To finish handling the content events, you need to handle the characters that the parser delivers to your application. 
&lt;/p&gt;
&lt;a name="wp99328"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Parsers are not required to
return any particular number of characters at one time. A parser can
return anything from a single character at a time up to several
thousand and still be a standard-conforming implementation. So if your
application needs to process the characters it sees, it is wise to
accumulate the characters in a buffer and operate on them only when you
are sure that all of them have been found.
&lt;/p&gt;
&lt;a name="wp99329"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted line to define the text buffer:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public class Echo01 extends DefaultHandler
{
  &lt;code class="cCodeBold"&gt;StringBuffer textBuffer;
&lt;/code&gt;
  public static void main(String argv[])
  {&lt;a name="wp99330"&gt; &lt;/a&gt;
...&lt;a name="wp71070"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71208"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Then add the following highlighted code to accumulate the characters the parser delivers in the buffer:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void endElement(...)
throws SAXException
{
  ...
}&lt;a name="wp71137"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;public void characters(char buf[], int offset, int len)
throws SAXException
{
  String s = new String(buf, offset, len);
  if (textBuffer == null) {
    textBuffer = new StringBuffer(s);
  } else {
    textBuffer.append(s);
  }
}&lt;/code&gt;&lt;a name="wp71187"&gt; &lt;/a&gt;
private void emit(String s)
...&lt;a name="wp64267"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64268"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, add the following highlighted method to send the contents of the buffer to the output stream.
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void characters(char buf[], int offset, int len)
throws SAXException
{
  ...
}&lt;a name="wp71278"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;private void echoText()
throws SAXException
{
  if (textBuffer == null) return;
  String s = ""+textBuffer;
  emit(s);
  textBuffer = null;
}&lt;/code&gt;&lt;a name="wp71297"&gt; &lt;/a&gt;
private void emit(String s)
...&lt;a name="wp71279"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71267"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;When this method is called
twice in a row (which will happen at times, as you'll see next), the
buffer will be null. In that case, the method simply returns. When the
buffer is not null, however, its contents are sent to the output
stream.
&lt;/p&gt;
&lt;a name="wp71276"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Finally, add the following highlighted code to echo the contents of the buffer whenever an element starts or ends:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void startElement(...)
throws SAXException
{
  &lt;code class="cCodeBold"&gt;echoText();
&lt;/code&gt;  String eName = sName; // element name
  ...
}&lt;a name="wp71356"&gt; &lt;/a&gt;
public void endElement(...)
throws SAXException
{
  &lt;code class="cCodeBold"&gt;echoText();
&lt;/code&gt;  String eName = sName; // element name
  ...
}&lt;a name="wp71402"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71266"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;You're finished accumulating
text when an element ends, of course. So you echo it at that point, and
that action clears the buffer before the next element starts.
&lt;/p&gt;
&lt;a name="wp71419"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;But you also want to echo the
accumulated text when an element starts! That's necessary for
document-style data, which can contain XML elements that are intermixed
with text. For example, consider this document fragment:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;&amp;lt;para&amp;gt;&lt;/code&gt;This paragraph contains &lt;code class="cCodeBold"&gt;&amp;lt;bold&amp;gt;&lt;/code&gt;important&lt;code class="cCodeBold"&gt;&amp;lt;/bold&amp;gt;&lt;/code&gt; 
ideas.&lt;code class="cCodeBold"&gt;&amp;lt;/para&amp;gt;&lt;/code&gt;&lt;a name="wp71432"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71433"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The initial text, &lt;code class="cCode"&gt;This paragraph contains&lt;/code&gt;, is terminated by the start of the &lt;code class="cCode"&gt;&amp;lt;bold&amp;gt;&lt;/code&gt; element. The text &lt;code class="cCode"&gt;important&lt;/code&gt; is terminated by the end tag, &lt;code class="cCode"&gt;&amp;lt;/bold&amp;gt;&lt;/code&gt;, and the final text, &lt;code class="cCode"&gt;ideas.&lt;/code&gt;, is terminated by the end tag, &lt;code class="cCode"&gt;&amp;lt;/para&amp;gt;&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp71462"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Most of the time, though, the accumulated text will be echoed when an &lt;code class="cCode"&gt;endElement()&lt;/code&gt; event occurs. When a &lt;code class="cCode"&gt;startElement()&lt;/code&gt; event occurs after that, the buffer will be empty. The first line in the &lt;code class="cCode"&gt;echoText()&lt;/code&gt; method checks for that case, and simply returns.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp71413"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Congratulations! At this point you have written a complete SAX parser application. The next step is to compile and run it.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64269"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: To be strictly accurate, the character handler should scan the buffer for ampersand characters (&lt;code class="cCode"&gt;&amp;amp;);&lt;/code&gt;and left-angle bracket characters (&amp;lt;) and replace them with the strings &lt;code class="cCode"&gt;&amp;amp;amp;&lt;/code&gt; or &lt;code class="cCode"&gt;&amp;amp;lt;&lt;/code&gt;, as appropriate. You'll find out more about that kind of processing when we discuss entity references in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPSAX6.html#wp64737"&gt;Displaying Special Characters and CDATA&lt;/a&gt;. 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64274"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Compiling and Running the Program
&lt;/h3&gt;
&lt;a name="wp96469"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In the Application Server, the JAXP libraries are in the directory &lt;code class="cVariable"&gt;&amp;lt;J2EE_HOME&amp;gt;&lt;/code&gt;&lt;code class="cCode"&gt;/lib/endorsed&lt;/code&gt;.
These are newer versions of the standard JAXP libraries than those that
are part of the Java 2 platform, Standard Edition versions 1.4.x.
&lt;/p&gt;
&lt;a name="wp96471"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;The Application Server
automatically uses the newer libraries when a program runs. So you
don't have to be concerned with where they reside when you deploy an
application. And because the JAXP APIs are identical in both versions,
you don't need to be concerned at compile time either. So compiling the
program you created is as simple as issuing this command:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;javac Echo.java&lt;a name="wp95842"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp95844"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
But to run the program outside the server container, you must be sure that the &lt;code class="cCode"&gt;java&lt;/code&gt;
runtime finds the newer versions of the JAXP libraries. That situation
can occur, for example, when you're unit-testing parts of your
application outside of server, as well as here, when you're running the
XML tutorial examples.
&lt;/p&gt;
&lt;a name="wp96907"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
There are two ways to make sure that the program uses the latest version of the JAXP libraries:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp96916"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Copy the &lt;code class="cVariable"&gt;&amp;lt;J2EE_HOME&amp;gt;&lt;/code&gt;&lt;code class="cCode"&gt;/lib/endorsed&lt;/code&gt; directory to &lt;code class="cCode"&gt;&amp;lt;&lt;/code&gt;&lt;code class="cVariable"&gt;J2EE_HOME&lt;/code&gt;&lt;code class="cCode"&gt;&amp;gt;/jdk/jre/lib/endorsed&lt;/code&gt; (if you are using the Java 2 SDK that comes with the Application Server) or &lt;code class="cVariable"&gt;&amp;lt;JAVA_HOME&amp;gt;&lt;/code&gt;&lt;code class="cCode"&gt;/jre/lib/endorsed&lt;/code&gt;
(if you are using a version of the Java 2 SDK that you have installed
separately) You can then run the program with this command:&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp96917"&gt; &lt;/a&gt;&lt;p class="pBodyRelative"&gt;
&lt;code class="cCode"&gt;  &amp;lt;&lt;/code&gt;&lt;code class="cVariable"&gt;J2SE SDK installation&amp;gt;&lt;/code&gt;&lt;code class="cCode"&gt;/bin/java Echo slideSample.xml&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp96918"&gt; &lt;/a&gt;&lt;p class="pBodyRelative"&gt;
The libraries will then be found in the endorsed standards directory.
&lt;/p&gt;
&lt;a name="wp96919"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Use the endorsed directories system property to specify the location of the libraries, by specifying this option on the &lt;code class="cCode"&gt;java&lt;/code&gt; command line:&lt;br&gt;&lt;code class="cCode"&gt;&lt;br&gt;  -D"java.endorsed.dirs=&amp;lt;&lt;/code&gt;&lt;code class="cVariable"&gt;J2EE_HOME&lt;/code&gt;&lt;code class="cCode"&gt;&amp;gt;/lib/endorsed"&lt;br&gt;&lt;/code&gt;or&lt;br&gt;&lt;code class="cCode"&gt;-D"java.endorsed.dirs=&lt;/code&gt;&lt;code class="cVariable"&gt;&amp;lt;JAVA_HOME&amp;gt;&lt;/code&gt;&lt;code class="cCode"&gt;/jre/lib/endorsed&lt;/code&gt;&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp99668"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Because the JAXP &lt;span style="font-style: italic;"&gt;APIs&lt;/span&gt;
are already built into the Java 2 platform, Standard Edition, they
don't need to be specified at compile time. However, when the JAXP
factories instantiate an &lt;span style="font-style: italic;"&gt;implementation&lt;/span&gt;, the endorsed directories mechanism is employed to make sure that the desired implementation is instantiated. 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp67478"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Checking the Output
&lt;/h3&gt;
&lt;a name="wp64333"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here is part of the program's output, showing some of its weird spacing:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCode"&gt;...
&lt;/code&gt;&amp;lt;slideshow title="Sample Slide Show" date="Date of publication" 
author="Yours Truly"&amp;gt;


  &amp;lt;slide type="all"&amp;gt;
    &amp;lt;title&amp;gt;Wake up to WonderWidgets!&amp;lt;/title&amp;gt;
  &amp;lt;/slide&amp;gt;
  ...&lt;a name="wp64334"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64336"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The program's output is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo01-01.txt" target="_blank"&gt;Echo01-01.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo01-01.html" target="_blank"&gt;Echo01-01.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp67558"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When we look at this output, a number of questions arise. Where is the
excess vertical whitespace coming from? And why are the elements
indented properly, when the code isn't doing it? We'll answer those
questions in a moment. First, though, there are a few points to note
about the output: &lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp64337"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The comment defined at the top of the file &lt;/li&gt;&lt;/div&gt;
&lt;a name="wp64338"&gt; &lt;/a&gt;&lt;p class="pBodyRelative"&gt;
&lt;code class="cCode"&gt;  &amp;lt;!-- A SAMPLE set of slides --&amp;gt;&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp64339"&gt; &lt;/a&gt;&lt;p class="pBodyRelative"&gt;
does not appear in the listing. Comments are ignored unless you implement a &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt;. You'll see more on that subject later in this tutorial.
&lt;/p&gt;
&lt;a name="wp64340"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Element attributes are listed all together on a single line. If your window isn't really wide, you won't see them all.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp64341"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The single-tag empty element you defined (&lt;code class="cCode"&gt;&amp;lt;item/&amp;gt;&lt;/code&gt;) is treated exactly the same as a two-tag empty element (&lt;code class="cCode"&gt;&amp;lt;item&amp;gt;&amp;lt;/item&amp;gt;&lt;/code&gt;). It is, for all intents and purposes, identical. (It's just easier to type and consumes less space.) &lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp64343"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Identifying the Events
&lt;/h3&gt;
&lt;a name="wp64344"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This version of the echo program might be useful for displaying an XML
file, but it doesn't tell you much about what's going on in the parser.
The next step is to modify the program so that you see where the spaces
and vertical lines are coming from.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64345"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code discussed in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo02.java" target="_blank"&gt;Echo02.java&lt;/a&gt;&lt;/code&gt;. The output it produces is shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo02-01.txt" target="_blank"&gt;Echo02-01.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo02-01.html" target="_blank"&gt;Echo02-01.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64346"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
 Make the following highlighted changes to identify the events as they occur:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void startDocument()
throws SAXException
{
  &lt;code class="cCodeBold"&gt;nl();
  nl(); 
  emit("START DOCUMENT");
  nl(); 
&lt;/code&gt;  emit("&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt;");
&lt;code class="cCodeStruck"&gt;  nl();
&lt;/code&gt;}

public void endDocument()
throws SAXException
{
&lt;code class="cCodeBold"&gt;  nl(); 
  emit("END DOCUMENT");
&lt;/code&gt;  try {
  ...
}

public void startElement(...)
throws SAXException
{
  echoText();
  &lt;code class="cCodeBold"&gt;nl(); 
  emit("ELEMENT: ");
&lt;/code&gt;  String eName = sName; // element name
  if ("".equals(eName)) eName = qName; // not namespac-aware
  emit("&amp;lt;"+eName);
  if (attrs != null) {
    for (int i = 0; i &amp;lt; attrs.getLength(); i++) {
      String aName = attrs.getLocalName(i); // Attr name
      if ("".equals(aName)) aName = attrs.getQName(i);
&lt;code class="cCodeStruck"&gt;      emit(" ");
      emit(aName+"=\""+attrs.getValue(i)+"\"");
&lt;/code&gt;      &lt;code class="cCodeBold"&gt;nl(); 
      emit("   ATTR: ");
      emit(aName);
      emit("\t\"");
      emit(attrs.getValue(i));
      emit("\"");
&lt;/code&gt;    }
  }
  &lt;code class="cCodeBold"&gt;if (attrs.getLength() &amp;gt; 0) nl();
&lt;/code&gt;  emit("&amp;gt;");
}&lt;a name="wp67644"&gt; &lt;/a&gt;
public void endElement(...)
throws SAXException
{
  echoText();
  &lt;code class="cCodeBold"&gt;nl(); 
  emit("END_ELM: ");
&lt;/code&gt;  String eName = sName; // element name
  if ("".equals(eName)) eName = qName; // not namespace-aware
  emit("&amp;lt;"+eName+"&amp;gt;");
}

...&lt;a name="wp71619"&gt; &lt;/a&gt;
private void echoText()
throws SAXException
{ 
  if (textBuffer == null) return;
  &lt;code class="cCodeBold"&gt;nl(); 
  emit("CHARS: |"); 
&lt;/code&gt;  String s = ""+textBuffer;
  emit(s);
  &lt;code class="cCodeBold"&gt;emit("|");
&lt;/code&gt;  textBuffer = null;
}&lt;a name="wp71624"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64350"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Compile and run this version of
the program to produce a more informative output listing. The
attributes are now shown one per line, and that is nice. But, more
importantly, output lines such as the following show that both the
indentation space and the newlines that separate the attributes come
from the data that the parser passes to the &lt;code class="cCode"&gt;characters()&lt;/code&gt; method.
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &lt;code class="cCode"&gt;CHARS: |
&lt;/code&gt;
|&lt;a name="wp71712"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64355"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML specification requires all input line separators to be
normalized to a single newline. The newline character is specified as
in Java, C, and UNIX systems, but goes by the alias "linefeed" in
Windows systems.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64357"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Compressing the Output
&lt;/h3&gt;
&lt;a name="wp64358"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;To make the output more
readable, modify the program so that it outputs only characters whose
values are something other than whitespace.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64359"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code discussed in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo03.java" target="_blank"&gt;Echo03.java&lt;/a&gt;&lt;/code&gt;. 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64360"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Make the following changes to suppress output of characters that are all whitespace:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void echoText()
throws SAXException
{
  nl(); 
  &lt;code class="cCodeStruck"&gt;emit("CHARS: |");
&lt;/code&gt;&lt;code class="cCodeBold"&gt;  emit("CHARS:   ");
&lt;/code&gt;  String s = ""+textBuffer;
  &lt;code class="cCodeBold"&gt;if (!s.trim().equals("")) &lt;/code&gt;emit(s);
&lt;code class="cCodeStruck"&gt;  emit("|");
&lt;/code&gt;}&lt;a name="wp64361"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64362"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, add the following highlighted code to echo each set of characters delivered by the parser:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void characters(char buf[], int offset, int len)
throws SAXException
{
  &lt;code class="cCodeBold"&gt;if (textBuffer != null) {
    echoText();
    textBuffer = null;
  }
&lt;/code&gt;  String s = new String(buf, offset, len);
  ...
}&lt;a name="wp71811"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71794"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;If you run the program now, you
will see that you have also eliminated the indentation, because the
indent space is part of the whitespace that precedes the start of an
element. Add the following highlighted code to manage the indentation:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;static private Writer out;&lt;a name="wp64363"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;private String indentString = "    "; // Amount to indent
private int indentLevel = 0;
&lt;/code&gt;
...&lt;a name="wp64364"&gt; &lt;/a&gt;
public void startElement(...)
throws SAXException
{
  &lt;code class="cCodeBold"&gt;indentLevel++;
&lt;/code&gt;  nl(); 
  emit("ELEMENT: ");
  ...
}&lt;a name="wp64365"&gt; &lt;/a&gt;
public void endElement(...)
throws SAXException
{
  nl(); 
  emit("END_ELM: ");
  emit("&amp;lt;/"+sName+"&amp;gt;");
  &lt;code class="cCodeBold"&gt;indentLevel--;
&lt;/code&gt;}
...
private void nl()
throws SAXException
{
  ...
  try {
    out.write(lineEnd);
    &lt;code class="cCodeBold"&gt;for (int i=0; i &amp;lt; indentLevel; i++)
      out.write(indentString);
&lt;/code&gt;  } catch (IOException e) {
  ... 
}&lt;a name="wp67702"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64368"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This code sets up an indent string, keeps track of the current indent level, and outputs the indent string whenever the &lt;code class="cCode"&gt;nl&lt;/code&gt;
method is called. If you set the indent string to "", the output will
not be indented. (Try it. You'll see why it's worth the work to add the
indentation.)
&lt;/p&gt;
&lt;a name="wp64369"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;You'll be happy to know that
you have reached the end of the "mechanical" code in the Echo program.
From this point on, you'll be doing things that give you more insight
into how the parser works. The steps you've taken so far, though, have
given you a lot of insight into how the parser sees the XML data it
processes. You have also gained a helpful debugging tool that you can
use to see what the parser sees.
&lt;/p&gt;
&lt;a name="wp64371"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Inspecting the Output
&lt;/h3&gt;
&lt;a name="wp64372"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here is part of the output from this version of the program:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;ELEMENT: &amp;lt;slideshow
...
&amp;gt;
CHARS: 
CHARS: 
  ELEMENT: &amp;lt;slide
  ... 
  END_ELM: &amp;lt;/slide&amp;gt;
CHARS: 
CHARS:   &lt;a name="wp64373"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64374"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The complete output is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo03-01.txt" target="_blank"&gt;Echo03-01.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo03-01.html" target="_blank"&gt;Echo03-01.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp95444"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Note that the &lt;code class="cCode"&gt;characters&lt;/code&gt; method is invoked twice in a row. Inspecting the source file &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample01.xml" target="_blank"&gt;slideSample01.xml&lt;/a&gt;&lt;/code&gt; shows that there is a comment before the first slide. The first call to &lt;code class="cCode"&gt;characters&lt;/code&gt;
comes before that comment. The second call comes after. (Later, you'll
see how to be notified when the parser encounters a comment, although
in most cases you won't need such notifications.)
&lt;/p&gt;
&lt;a name="wp64375"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Note, too, that the &lt;code class="cCode"&gt;characters&lt;/code&gt;
method is invoked after the first slide element, as well as before.
When you are thinking in terms of hierarchically structured data, that
seems odd. After all, you intended for the &lt;code class="cCode"&gt;slideshow&lt;/code&gt; element to contain &lt;code class="cCode"&gt;slide&lt;/code&gt; elements and not text. Later, you'll see how to restrict the &lt;code class="cCode"&gt;slideshow&lt;/code&gt; element by using a DTD. When you do that, the &lt;code class="cCode"&gt;characters&lt;/code&gt; method will no longer be invoked. 
&lt;/p&gt;
&lt;a name="wp64376"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In the absence of a DTD, though, the parser must assume that any
element it sees contains text such as that in the first item element of
the overview slide:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;item&amp;gt;Why &amp;lt;em&amp;gt;WonderWidgets&amp;lt;/em&amp;gt; are great&amp;lt;/item&amp;gt;&lt;a name="wp64377"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64378"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, the hierarchical structure looks like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCode"&gt;ELEMENT:        &amp;lt;item&amp;gt;
&lt;/code&gt;CHARS:        Why 
  ELEMENT:         &amp;lt;em&amp;gt;
  CHARS:         WonderWidgets
  END_ELM:        &amp;lt;/em&amp;gt;
CHARS:         are great
END_ELM:        &amp;lt;/item&amp;gt;&lt;a name="wp64379"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64381"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Documents and Data
&lt;/h3&gt;
&lt;a name="wp64382"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;In this example, it's clear
that there are characters intermixed with the hierarchical structure of
the elements.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=13479781032&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Adding Additional Event Handlers</title><link>http://www.softxml.com/LearnTutorial.asp?id=16785995828&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
In addition to &lt;code class="cCode"&gt;ignorableWhitespace&lt;/code&gt;, there are two other &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; methods that can find uses in even simple applications: &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt; and &lt;code class="cCode"&gt;processingInstruction&lt;/code&gt;. In this section, you'll implement those two event handlers. 
&lt;/p&gt;
&lt;a name="wp64503"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Identifying the Document's Location
&lt;/h3&gt;
&lt;a name="wp64504"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
A &lt;span style="font-style: italic;"&gt;locator&lt;/span&gt; is an object that contains the information necessary to find a document. The &lt;code class="cCode"&gt;Locator&lt;/code&gt;
class encapsulates a system ID (URL) or a public identifier (URN) or
both. You would need that information if you wanted to find something
relative to the current document--in the same way, for example, that an
HTML browser processes an &lt;code class="cCode"&gt;href="anotherFile"&lt;/code&gt; attribute in an anchor tag. The browser uses the location of the current document to find &lt;code class="cCode"&gt;anotherFile&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp64505"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You could also use the locator to print good diagnostic messages. In
addition to the document's location and public identifier, the locator
contains methods that give the column and line number of the most
recently processed event. The &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt;
method, however, is called only once: at the beginning of the parse. To
get the current line or column number, you would save the locator when &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt; is invoked and then use it in the other event-handling methods.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp67827"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code discussed in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo04.java" target="_blank"&gt;Echo04.java&lt;/a&gt;&lt;/code&gt;. Its output is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo04-01.txt" target="_blank"&gt;Echo04-01.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo04-01.html" target="_blank"&gt;Echo04-01.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp67828"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Start by removing the extra character-echoing code you added for the last example:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void characters(char buf[], int offset, int len)
throws SAXException
{
  &lt;code class="cCodeStruck"&gt;if (textBuffer != null) {
    echoText();
    textBuffer = null;
  }
&lt;/code&gt;  String s = new String(buf, offset, len);
  ...
}&lt;a name="wp71879"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp71862"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, add the following highlighted method to the Echo program to get
the document locator and use it to echo the document's system ID.
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;...
private String indentString = "    "; // Amount to indent
private int indentLevel = 0;&lt;a name="wp64508"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;public void setDocumentLocator(Locator l)
{
  try {
    out.write("LOCATOR");
    out.write("SYS ID: " + l.getSystemId() );
    out.flush();
  } catch (IOException e) {
    // Ignore errors
  }
}&lt;/code&gt;&lt;a name="wp64509"&gt; &lt;/a&gt;
public void startDocument()
...&lt;a name="wp64510"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64511"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Notes:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp64512"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;This method, in contrast to every other &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; method, does not return a &lt;code class="cCode"&gt;SAXException&lt;/code&gt;. So rather than use &lt;code class="cCode"&gt;emit&lt;/code&gt; for output, this code writes directly to &lt;code class="cCode"&gt;System.out&lt;/code&gt;. (This method is generally expected to simply save the &lt;code class="cCode"&gt;Locator&lt;/code&gt; for later use rather than do the kind of processing that generates an exception, as here.)&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp64513"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The spelling of these methods is &lt;code class="cCode"&gt;Id&lt;/code&gt;, not &lt;code class="cCode"&gt;ID&lt;/code&gt;. So you have &lt;code class="cCode"&gt;getSystemId&lt;/code&gt; and &lt;code class="cCode"&gt;getPublicId&lt;/code&gt;.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp64514"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you compile and run the program on &lt;code class="cCode"&gt;slideSample01.xml&lt;/code&gt;, here is the significant part of the output:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;LOCATOR
SYS ID: file:&lt;code class="cVariable"&gt;&amp;lt;path&amp;gt;&lt;/code&gt;/../samples/slideSample01.xml&lt;a name="wp64515"&gt; &lt;/a&gt;
START DOCUMENT
&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt;
...&lt;a name="wp64516"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64518"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, it is apparent that &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt; is called before &lt;code class="cCode"&gt;startDocument&lt;/code&gt;. That can make a difference if you do any initialization in the event-handling code. 
&lt;/p&gt;
&lt;a name="wp64520"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Handling Processing Instructions
&lt;/h3&gt;
&lt;a name="wp64521"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;It sometimes makes sense to
code application-specific processing instructions in the XML data. In
this exercise, you'll modify the Echo program to display a processing
instruction contained in &lt;code class="cCode"&gt;slideSample02.xml&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64522"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code discussed in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo05.java" target="_blank"&gt;Echo05.java&lt;/a&gt;&lt;/code&gt;. The file it operates on is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample02.xml" target="_blank"&gt;slideSample02.xml&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp67861"&gt;Writing Processing Instructions &lt;/a&gt;. The output is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo05-02.txt" target="_blank"&gt;Echo05-02.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample02-xml.html" target="_blank"&gt;slideSample02-xml.html&lt;/a&gt;&lt;/code&gt; and&lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo05-02.html" target="_blank"&gt; Echo05-02.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64526"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
As you saw in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp67861"&gt;Writing Processing Instructions&lt;/a&gt;, the format for a processing instruction is &lt;code class="cCode"&gt;&amp;lt;?&lt;/code&gt;&lt;code class="cVariable"&gt;target&lt;/code&gt;&lt;code class="cCode"&gt; &lt;/code&gt;&lt;code class="cVariable"&gt;data&lt;/code&gt;&lt;code class="cCode"&gt;?&amp;gt;&lt;/code&gt;, where &lt;code class="cVariable"&gt;target&lt;/code&gt; is the application that is expected to do the processing, and &lt;code class="cVariable"&gt;data&lt;/code&gt; is the instruction or information for it to process. The sample file &lt;code class="cCode"&gt;slideSample02.xml&lt;/code&gt;
contains a processing instruction for a mythical slide presentation
program that queries the user to find out which slides to display
(technical, executive-level, or all):
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;slideshow 
  ...
  &amp;gt;

  &lt;code class="cCodeBold"&gt;&amp;lt;!-- PROCESSING INSTRUCTION --&amp;gt;
  &amp;lt;?my.presentation.Program QUERY="exec, tech, all"?&amp;gt;
&lt;/code&gt;
  &amp;lt;!-- TITLE SLIDE --&amp;gt;&lt;a name="wp64527"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64537"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To display that processing instruction, add the following highlighted code to the Echo application:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void characters(char buf[], int offset, int len)
...
}&lt;a name="wp64538"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;public void processingInstruction(String target, String data)
throws SAXException
{
  nl(); 
  emit("PROCESS: ");
  emit("&amp;lt;?"+target+" "+data+"?&amp;gt;");
}&lt;/code&gt;&lt;a name="wp64539"&gt; &lt;/a&gt;
private void echoText()
...&lt;a name="wp64540"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64541"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When your edits are complete, compile and run the program. The relevant part of the output should look like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;ELEMENT: &amp;lt;slideshow
  ...
&amp;gt;
PROCESS: &amp;lt;?my.presentation.Program QUERY="exec, tech, all"?&amp;gt;
CHARS: 
...</description><guid>http://www.softxml.com/LearnTutorial.asp?id=16785995828&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Handling Errors with the Nonvalidating Parser</title><link>http://www.softxml.com/LearnTutorial.asp?id=878627672&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
The parser can generate three kinds of errors: a fatal error, an error,
and a warning. In this exercise, you'll see how the parser handles a
fatal error.
&lt;/p&gt;
&lt;a name="wp64580"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;This version of the Echo
program uses the nonvalidating parser. So it can't tell whether the XML
document contains the right tags or whether those tags are in the right
sequence. In other words, it can't tell you whether the document is
valid. It can, however, tell whether or not the document is well
formed. &lt;/p&gt;
&lt;a name="wp64581"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In this section, you'll modify the slide-show file to generate various
kinds of errors and see how the parser handles them. You'll also find
out which error conditions are ignored by default, and you'll see how
to handle them. &lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp95501"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML file used in this exercise is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSampleBad1.xml" target="_blank"&gt;slideSampleBad1.xml&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp69037"&gt;Introducing an Error &lt;/a&gt;. The output is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo05-Bad1.txt" target="_blank"&gt;Echo05-Bad1.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSampleBad1-xml.html" target="_blank"&gt;slideSampleBad1-xml.html&lt;/a&gt;&lt;/code&gt; and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo05-Bad1.html" target="_blank"&gt;Echo05-Bad1.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64592"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you created &lt;code class="cCode"&gt;slideSampleBad1.xml&lt;/code&gt;,
you deliberately created an XML file that was not well formed. Run the
Echo program on that file now. The output now gives you an error
message that looks like this (after formatting for readability):
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;org.xml.sax.SAXParseException: 
  The element type "item" must be terminated by the
  matching end-tag "&amp;lt;/item&amp;gt;".
&lt;/code&gt;...
at org.apache.xerces.parsers.AbstractSAXParser...
...
at Echo.main(...)&lt;a name="wp95893"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp70786"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;Note: The foregoing message was
generated by Xerces, the XML parser that is part of the JAXP 1.2
implementation libraries. If you are using a different parser, the
error message is likely to be somewhat different.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64595"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;When a fatal error occurs,
the parser cannot continue. So if the application does not generate an
exception (which you'll see how to do a moment), then the default
error-event handler generates one. The stack trace is generated by the &lt;code class="cCode"&gt;Throwable&lt;/code&gt; exception handler in your &lt;code class="cCode"&gt;main&lt;/code&gt; method:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;    ...
} catch (Throwable t) {
&lt;code class="cCodeBold"&gt;  t.printStackTrace();
&lt;/code&gt;}&lt;a name="wp64596"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64597"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
That stack trace is not very useful. Next, you'll see how to generate better diagnostics when an error occurs.
&lt;/p&gt;
&lt;a name="wp64599"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling a SAXParseException
&lt;/h4&gt;
&lt;a name="wp64600"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When the error was encountered, the parser generated a &lt;code class="cCode"&gt;SAXParseException&lt;/code&gt;--a subclass of &lt;code class="cCode"&gt;SAXException&lt;/code&gt; that identifies the file and location where the error occurred. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64601"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code you'll create in this exercise is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo06.java" target="_blank"&gt;Echo06.java&lt;/a&gt;&lt;/code&gt;. The output is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo06-Bad1.txt" target="_blank"&gt;Echo06-Bad1.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is&lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo06-Bad1.html" target="_blank"&gt; Echo06-Bad1.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64602"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted code to generate a better diagnostic message when the exception occurs: 
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;...
} catch (SAXParseException spe) {
  // Error generated by the parser
  System.out.println("\n** Parsing error" 
    + ", line " + spe.getLineNumber()
    + ", uri " + spe.getSystemId());
  System.out.println("   " + spe.getMessage() );

&lt;/code&gt;} catch (Throwable t) {
  t.printStackTrace();
}&lt;a name="wp64603"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64604"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Running this version of the program on &lt;code class="cCode"&gt;slideSampleBad1.xml&lt;/code&gt; generates an error message that is a bit more helpful:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;** Parsing error, line 22, uri file:&amp;lt;path&amp;gt;/slideSampleBad1.xml
  The element type "item" must be ...&lt;a name="wp64605"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64606"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The text of the error message depends on the parser used. This message was generated using JAXP 1.2.
&lt;/p&gt;
&lt;a name="wp69569"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Catching all throwables is not generally a great idea for production applications.&lt;span style="font-weight: bold;"&gt; &lt;/span&gt;We're
doing it now so that we can build up to full error handling gradually.
In addition, it acts as a catch-all for null pointer exceptions that
can be thrown when the parser is passed a null value.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64608"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling a SAXException
&lt;/h4&gt;
&lt;a name="wp64609"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
A more general &lt;code class="cCode"&gt;SAXException&lt;/code&gt;
instance may sometimes be generated by the parser, but it more
frequently occurs when an error originates in one of application's
event-handling methods. For example, the signature of the &lt;code class="cCode"&gt;startDocument&lt;/code&gt; method in the &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; interface is defined as returning a &lt;code class="cCode"&gt;SAXException&lt;/code&gt;: 
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void startDocument() throws SAXException&lt;a name="wp64610"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64611"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
All the &lt;code class="cCode"&gt;ContentHandler&lt;/code&gt; methods (except for &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt;) have that signature declaration.
&lt;/p&gt;
&lt;a name="wp64612"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
A &lt;code class="cCode"&gt;SAXException&lt;/code&gt; can be constructed using a message, another exception, or both. So, for example, when &lt;code class="cCode"&gt;Echo.startDocument&lt;/code&gt; outputs a string using the &lt;code class="cCode"&gt;emit&lt;/code&gt; method, any I/O exception that occurs is wrapped in a &lt;code class="cCode"&gt;SAXException&lt;/code&gt; and sent back to the parser:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;private void emit(String s)
throws SAXException
{
  try {
    out.write(s);
    out.flush();
  } &lt;code class="cCodeBold"&gt;catch (IOException e)&lt;/code&gt; {
    &lt;code class="cCodeBold"&gt;throw new SAXException("I/O error", e);
&lt;/code&gt;  }
}&lt;a name="wp64613"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp64614"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: If you saved the &lt;code class="cCode"&gt;Locator&lt;/code&gt; object when &lt;code class="cCode"&gt;setDocumentLocator&lt;/code&gt; was invoked, you could use it to generate a &lt;code class="cCode"&gt;SAXParseException&lt;/code&gt;, identifying the document and location, instead of generating a &lt;code class="cCode"&gt;SAXException&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64615"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When the parser delivers the exception back to the code that invoked
the parser, it makes sense to use the original exception to generate
the stack trace. Add the following highlighted code to do that:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;   ...
} catch (SAXParseException err) {
  System.out.println("\n** Parsing error" 
    + ", line " + err.getLineNumber()
    + ", uri " + err.getSystemId());
  System.out.println("   " + err.getMessage());

&lt;code class="cCodeBold"&gt;} catch (SAXException sxe) {
  // Error generated by this application
  // (or a parser-initialization error)
  Exception  x = sxe;
  if (sxe.getException() != null)
    x = sxe.getException();
  x.printStackTrace();
&lt;/code&gt;
} catch (Throwable t) {
  t.printStackTrace();
}&lt;a name="wp64616"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64617"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This code tests to see whether the &lt;code class="cCode"&gt;SAXException&lt;/code&gt;
is wrapping another exception. If it is, it generates a stack trace
originating where the exception occurred to make it easier to pinpoint
the responsible code. If the exception contains only a message, the
code prints the stack trace starting from the location where the
exception was generated.
&lt;/p&gt;
&lt;a name="wp64619"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Improving the SAXParseException Handler
&lt;/h4&gt;
&lt;a name="wp64620"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Because the &lt;code class="cCode"&gt;SAXParseException&lt;/code&gt; can also wrap another exception, add the following highlighted code to use the contained exception for the stack trace:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;    ...
} catch (SAXParseException err) {
  System.out.println("\n** Parsing error" 
    + ", line " + err.getLineNumber()
    + ", uri " + err.getSystemId());
  System.out.println("   " + err.getMessage());

&lt;code class="cCodeBold"&gt;  // Use the contained exception, if any
  Exception  x = spe;
  if (spe.getException() != null)
    x = spe.getException();
  x.printStackTrace();&lt;/code&gt;&lt;a name="wp64621"&gt; &lt;/a&gt;
} catch (SAXException sxe) {
  // Error generated by this application
  // (or a parser-initialization error)
  Exception      x = sxe;
  if (sxe.getException() != null)
    x = sxe.getException();
  x.printStackTrace();&lt;a name="wp64622"&gt; &lt;/a&gt;
} catch (Throwable t) {
  t.printStackTrace();
}      &lt;a name="wp64623"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64624"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;The program is now ready to
handle any SAX parsing exceptions it sees. You've seen that the parser
generates exceptions for fatal errors. But for nonfatal errors and
warnings, exceptions are never generated by the default error handler,
and no messages are displayed. In a moment, you'll learn more about
errors and warnings and will find out how to supply an error handler to
process them. &lt;/p&gt;
&lt;a name="wp64626"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling a ParserConfigurationException
&lt;/h4&gt;
&lt;a name="wp64627"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Recall that the &lt;code class="cCode"&gt;SAXParserFactory&lt;/code&gt;
class can throw an exception if it cannot create a parser. Such an
error might occur if the factory cannot find the class needed to create
the parser (class not found error), is not permitted to access it
(illegal access exception), or cannot instantiate it (instantiation
error).
&lt;/p&gt;
&lt;a name="wp64628"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted code to handle such errors:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;} catch (SAXException sxe) {
  Exception      x = sxe;
  if (sxe.getException() != null)
    x = sxe.getException();
  x.printStackTrace();

&lt;code class="cCodeBold"&gt;} catch (ParserConfigurationException pce) {
  // Parser with specified options can't be built
  pce.printStackTrace();
&lt;/code&gt;
} catch (Throwable t) {
  t.printStackTrace();&lt;a name="wp64629"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64630"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Admittedly, there are quite a few error handlers here. But at least now you know the kinds of exceptions that can occur. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64631"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: A &lt;code class="cCode"&gt;javax.xml.parsers.FactoryConfigurationError&lt;/code&gt;
can also be thrown if the factory class specified by the system
property cannot be found or instantiated. That is a nontrappable error,
because the program is not expected to be able to recover from it.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64633"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling an IOException
&lt;/h4&gt;
&lt;a name="wp64634"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
While we're at it, let's add a handler for &lt;code class="cCode"&gt;IOException&lt;/code&gt;s:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;} catch (ParserConfigurationException pce) {
  // Parser with specified options can't be built
  pce.printStackTrace();

&lt;code class="cCodeBold"&gt;} catch (IOException ioe) {
  // I/O error
  ioe.printStackTrace();
}
&lt;/code&gt;
} catch (Throwable t) {
  ...&lt;a name="wp67967"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp70850"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
We'll leave the handler for &lt;code class="cCode"&gt;Throwables&lt;/code&gt; to catch null pointer errors, but note that at this point it is doing the same thing as the &lt;code class="cCode"&gt;IOException&lt;/code&gt; handler. Here, we're merely illustrating the kinds of exceptions that &lt;span style="font-style: italic;"&gt;can&lt;/span&gt; occur, in case there are some that your application could recover from.
&lt;/p&gt;
&lt;a name="wp70852"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling NonFatal Errors
&lt;/h4&gt;
&lt;a name="wp70853"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
A &lt;span style="font-style: italic;"&gt;nonfatal&lt;/span&gt;
error occurs when an XML document fails a validity constraint. If the
parser finds that the document is not valid, then an error event is
generated. Such errors are generated by a validating parser, given a
DTD or schema, when a document has an invalid tag, when a tag is found
where it is not allowed, or (in the case of a schema) when the element
contains invalid data.
&lt;/p&gt;
&lt;a name="wp70858"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;You won't deal with validation
issues until later in this tutorial. But because we're on the subject
of error handling, you'll write the error-handling code now.
&lt;/p&gt;
&lt;a name="wp70836"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;The most important principle to
understand about nonfatal errors is that they are ignored by default.
But if a validation error occurs in a document, you probably don't want
to continue processing it. You probably want to treat such errors as
fatal. In the code you write next, you'll set up the error handler to
do just that.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64647"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code for the program you'll create in this exercise is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07.java" target="_blank"&gt;Echo07.java&lt;/a&gt;&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64648"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To take over error handling, you override the &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; methods that handle fatal errors, nonfatal errors, and warnings as part of the &lt;code class="cCode"&gt;ErrorHandler&lt;/code&gt; interface. The SAX parser delivers a &lt;code class="cCode"&gt;SAXParseException&lt;/code&gt; to each of these methods, so generating an exception when an error occurs is as simple as throwing it back.
&lt;/p&gt;
&lt;a name="wp64649"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted code to override the handler for errors:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void processingInstruction(String target, String data)
throws SAXException
{
  ...
}&lt;a name="wp70904"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;// treat validation errors as fatal
public void error(SAXParseException e)
throws SAXParseException
{
  throw e;
}&lt;/code&gt;&lt;a name="wp64651"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp70957"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: It can be instructive to examine the error-handling methods defined in &lt;code class="cCode"&gt;org.xml.sax.helpers.DefaultHandler&lt;/code&gt;. You'll see that the &lt;code class="cCode"&gt;error()&lt;/code&gt; and &lt;code class="cCode"&gt;warning()&lt;/code&gt; methods do nothing, whereas &lt;code class="cCode"&gt;fatalError()&lt;/code&gt; throws an exception. Of course, you could always override the &lt;code class="cCode"&gt;fatalError()&lt;/code&gt; method to throw a different exception. But if your code &lt;span style="font-style: italic;"&gt;doesn't&lt;/span&gt; throw an exception when a fatal error occurs, then the SAX parser will. The XML specification requires it.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64656"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Handling Warnings
&lt;/h4&gt;
&lt;a name="wp64657"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Warnings, too, are ignored by
default. Warnings are informative can only be generated in the presence
of a DTD or schema. For example, if an element is defined twice in a
DTD, a warning is generated. It's not illegal, and it doesn't cause
problems, but it's something you might like to know about because it
might not have been intentional.
&lt;/p&gt;
&lt;a name="wp64658"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Add the following highlighted code to generate a message when a warning occurs:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;// treat validation errors as fatal
public void error(SAXParseException e)
throws SAXParseException
{
  throw e;
}&lt;a name="wp64659"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;// dump warnings too
public void warning(SAXParseException err)
throws SAXParseException
{
  System.out.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=878627672&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Displaying Special Characters and CDATA</title><link>http://www.softxml.com/LearnTutorial.asp?id=3529601986&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
The next thing we will do with the parser is to customize it a bit so
that you can see how to get information it usually ignores. In this
section, you'll learn how the parser handles
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp64739"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;  Special characters (&lt;code class="cCode"&gt;&amp;lt;&lt;/code&gt;, &lt;code class="cCode"&gt;&amp;amp;&lt;/code&gt;, and so on)&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp64740"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;  Text with XML-style syntax&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp64742"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Handling Special Characters
&lt;/h3&gt;
&lt;a name="wp64743"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;In XML, an entity is an XML
structure (or plain text) that has a name. Referencing the entity by
name causes it to be inserted into the document in place of the entity
reference. To create an entity reference, you surround the entity name
with an ampersand and a semicolon:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &amp;amp;entityName;&lt;a name="wp64744"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp67017"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Earlier, you put an entity reference into your XML document by coding
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;Market Size &amp;amp;lt; predicted&lt;a name="wp94847"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp68113"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The file containing this XML is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample03.xml" target="_blank"&gt;slideSample03.xml&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp67725"&gt;Using an Entity Reference in an XML Document&lt;/a&gt;. The results of processing it are shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-03.txt" target="_blank"&gt;Echo07-03.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample03-xml.html" target="_blank"&gt;slideSample03-xml.html&lt;/a&gt;&lt;/code&gt; and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-03.html" target="_blank"&gt;Echo07-03.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64796"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you run the Echo program on &lt;code class="cCode"&gt;slideSample03.xml&lt;/code&gt;, you see the following output:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;ELEMENT:        &amp;lt;item&amp;gt;
CHARS:        Market Size &amp;lt; predicted
END_ELM:        &amp;lt;/item&amp;gt;&lt;a name="wp64797"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64798"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The parser has converted the reference into the entity it represents and has passed the entity to the application.
&lt;/p&gt;
&lt;a name="wp64800"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Handling Text with XML-Style Syntax
&lt;/h3&gt;
&lt;a name="wp64801"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you are handling large blocks of XML or HTML that include many special characters, you use a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64802"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML file used in this example is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample04.xml" target="_blank"&gt;slideSample04.xml&lt;/a&gt;&lt;/code&gt;. The results of processing it are shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-04.txt" target="_blank"&gt;Echo07-04.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample04-xml.html" target="_blank"&gt;slideSample04-xml.html&lt;/a&gt;&lt;/code&gt; and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-04.html" target="_blank"&gt;Echo07-04.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64803"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
A &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section works like &lt;code class="cCode"&gt;&amp;lt;pre&amp;gt;...&amp;lt;/pre&amp;gt;&lt;/code&gt; in HTML, only more so: all whitespace in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section is significant, and characters in it are not interpreted as XML. A &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section starts with &lt;code class="cCode"&gt;&amp;lt;![CDATA[ &lt;/code&gt;and ends with &lt;code class="cCode"&gt;]]&amp;gt;&lt;/code&gt;. The file &lt;code class="cCode"&gt;slideSample04.xml&lt;/code&gt; contains this &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section for a fictitious technical slide:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;   ...
&lt;code class="cCodeBold"&gt;  &amp;lt;slide type="tech"&amp;gt;
    &amp;lt;title&amp;gt;How it Works&amp;lt;/title&amp;gt;
    &amp;lt;item&amp;gt;First we fozzle the frobmorten&amp;lt;/item&amp;gt;
    &amp;lt;item&amp;gt;Then we framboze the staten&amp;lt;/item&amp;gt;
    &amp;lt;item&amp;gt;Finally, we frenzle the fuznaten&amp;lt;/item&amp;gt;
    &amp;lt;item&amp;gt;&amp;lt;![CDATA[Diagram:
      frobmorten &amp;lt;--------------- fuznaten
        |            &amp;lt;3&amp;gt;             ^
        | &amp;lt;1&amp;gt;                        | &amp;lt;1&amp;gt; = fozzle
        V                            | &amp;lt;2&amp;gt; = framboze 
      staten-------------------------+ &amp;lt;3&amp;gt; = frenzle
               &amp;lt;2&amp;gt;
    ]]&amp;gt;&amp;lt;/item&amp;gt;
  &amp;lt;/slide&amp;gt;
&lt;/code&gt;&amp;lt;/slideshow&amp;gt;&lt;a name="wp95906"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64806"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you run the Echo program on the new file, you see the following output:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  ELEMENT: &amp;lt;item&amp;gt;
  CHARS:   Diagram:
&lt;span style="font-weight: normal;"&gt;frobmorten &amp;lt;--------------- fuznaten
  |            &amp;lt;3&amp;gt;             ^
  | &amp;lt;1&amp;gt;                        | &amp;lt;1&amp;gt; = fozzle
  V                            | &amp;lt;2&amp;gt; = framboze 
staten-------------------------+ &amp;lt;3&amp;gt; = frenzle
&lt;/span&gt;&lt;code style="font-weight: bold;" class="cCodeBold"&gt;         &lt;/code&gt;&lt;span style="font-weight: normal;"&gt;&amp;lt;2&amp;gt;
&lt;/span&gt;
END_ELM: &amp;lt;/item&amp;gt;&lt;a name="wp72289"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp68850"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You can see here that the text in the &lt;code class="cCode"&gt;CDATA&lt;/code&gt;
section arrived as it was written. Because the parser didn't treat the
angle brackets as XML, they didn't generate the fatal errors they would
otherwise cause. (If the angle brackets weren't in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section, the document would not be well formed.)
&lt;/p&gt;
&lt;a name="wp64811"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Handling CDATA and Other Characters
&lt;/h3&gt;
&lt;a name="wp64812"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The existence of &lt;code class="cCode"&gt;CDATA&lt;/code&gt; makes the proper echoing of XML a bit tricky. If the text to be output is &lt;span style="font-style: italic;"&gt;not&lt;/span&gt; in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt;
section, then any angle brackets, ampersands, and other special
characters in the text should be replaced with the appropriate entity
reference. (Replacing left angle brackets and ampersands is most
important, other characters will be interpreted properly without
misleading the parser.) &lt;/p&gt;
&lt;a name="wp100181"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
But if the output text &lt;span style="font-style: italic;"&gt;is&lt;/span&gt; in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt;
section, then the substitutions should not occur, resulting in text
like that in the earlier example. In a simple program such as our Echo
application, it's not a big deal. But many XML-filtering applications
will want to keep track of whether the text appears in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section, so that they can treat special characters properly. (Later, you will see how to use a &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt; to find out whether or not you are processing a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=3529601986&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Parsing with a DTD</title><link>http://www.softxml.com/LearnTutorial.asp?id=24004234340&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
After the XML declaration, the document prolog can include a DTD,
reference an external DTD, or both. In this section, you'll see the
effect of the DTD on the data that the parser delivers to your
application.
&lt;/p&gt;
&lt;a name="wp64977"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
DTD's Effect on the Nonvalidating Parser
&lt;/h3&gt;
&lt;a name="wp64978"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;In this section, you'll use the
Echo program to see how the data appears to the SAX parser when the
data file references a DTD. &lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp94962"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML file used in this section is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample05.xml" target="_blank"&gt;slideSample05.xml&lt;/a&gt;&lt;/code&gt;, which references &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow1a.dtd" target="_blank"&gt;slideshow1a.dtd&lt;/a&gt;&lt;/code&gt;. The output is shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-05.txt" target="_blank"&gt;Echo07-05.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow1a-dtd.html" target="_blank"&gt;slideshow1a-dtd.html&lt;/a&gt;&lt;/code&gt;, &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample05-xml.html" target="_blank"&gt;slideSample05-xml.html&lt;/a&gt;&lt;/code&gt;, and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo07-05.html" target="_blank"&gt;Echo07-05.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64980"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Running the Echo program on your latest version of &lt;code class="cCode"&gt;slideSample.xml&lt;/code&gt; shows that many of the superfluous calls to the &lt;code class="cCode"&gt;characters&lt;/code&gt; method have now disappeared.
&lt;/p&gt;
&lt;a name="wp72039"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Before, you saw this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  ...
&amp;gt;
PROCESS: ...
&lt;code class="cCodeBold"&gt;CHARS:
&lt;/code&gt;  ELEMENT:        &amp;lt;slide
    ATTR: ...
  &amp;gt;
      ELEMENT:        &amp;lt;title&amp;gt;
      CHARS:        Wake up to ...
      END_ELM:        &amp;lt;/title&amp;gt;
  END_ELM:        &amp;lt;/slide&amp;gt;
&lt;code class="cCodeBold"&gt;CHARS:
&lt;/code&gt;  ELEMENT:        &amp;lt;slide
    ATTR: ...
  &amp;gt;
  ...&lt;a name="wp64981"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64982"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now you see this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  ...
&amp;gt;
PROCESS: ...
  ELEMENT:        &amp;lt;slide
    ATTR: ...
  &amp;gt;
      ELEMENT:        &amp;lt;title&amp;gt;
      CHARS:        Wake up to ...
      END_ELM:        &amp;lt;/title&amp;gt;
  END_ELM:        &amp;lt;/slide&amp;gt;
  ELEMENT:        &amp;lt;slide
    ATTR: ...
  &amp;gt;
  ...&lt;a name="wp72041"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp72040"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
It is evident that the whitespace characters that were formerly being echoed around the &lt;code class="cCode"&gt;slide&lt;/code&gt; elements are no longer being delivered by the parser, because the DTD declares that &lt;code class="cCode"&gt;slideshow&lt;/code&gt; consists solely of &lt;code class="cCode"&gt;slide&lt;/code&gt; elements:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &amp;lt;!ELEMENT slideshow (slide+)&amp;gt;&lt;a name="wp64983"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64985"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Tracking Ignorable Whitespace
&lt;/h3&gt;
&lt;a name="wp64986"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now that the DTD is present, the parser is no longer calling the &lt;code class="cCode"&gt;characters&lt;/code&gt;
method with whitespace that it knows to be irrelevant. From the
standpoint of an application that is interested in processing only the
XML data, that is great. The application is never bothered with
whitespace that exists purely to make the XML file readable.
&lt;/p&gt;
&lt;a name="wp64987"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;On the other hand, if you were
writing an application that was filtering an XML data file and if you
wanted to output an equally readable version of the file, then that
whitespace would no longer be irrelevant: it would be essential. To get
those characters, you add the &lt;code class="cCode"&gt;ignorableWhitespace&lt;/code&gt; method to your application. You'll do that next.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64988"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code written in this section is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo08.java" target="_blank"&gt;Echo08.java&lt;/a&gt;&lt;/code&gt;. The output is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo08-05.txt" target="_blank"&gt;Echo08-05.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo08-05.html" target="_blank"&gt;Echo08-05.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp100236"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To process the (generally) ignorable whitespace that the parser is seeing, add the following highlighted code to implement the &lt;code class="cCode"&gt;ignorableWhitespace&lt;/code&gt; event handler in&lt;span style="font-weight: bold;"&gt; &lt;/span&gt;your version of the Echo program: 
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void characters (char buf[], int offset, int len)
... 
}&lt;a name="wp64990"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;public void ignorableWhitespace (char buf[], int offset, int 
Len)
throws SAXException
{
  nl(); 
  emit("IGNORABLE");
}&lt;/code&gt;&lt;a name="wp64991"&gt; &lt;/a&gt;
public void processingInstruction(String target, String data)
...&lt;a name="wp64992"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64993"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This code simply generates a message to let you know that ignorable whitespace was seen.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp64994"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Again, not all parsers are created equal. The SAX specification
does not require that this method be invoked. The Java XML
implementation does so whenever the DTD makes it possible.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp64995"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you run the Echo application now, your output looks like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;ELEMENT: &amp;lt;slideshow
  ATTR: ...
&amp;gt;
&lt;code class="cCodeBold"&gt;IGNORABLE
IGNORABLE
&lt;/code&gt;PROCESS: ...
&lt;code class="cCodeBold"&gt;IGNORABLE
IGNORABLE
&lt;/code&gt;  ELEMENT: &amp;lt;slide
    ATTR: ...
  &amp;gt;
  &lt;code class="cCodeBold"&gt;IGNORABLE
&lt;/code&gt;    ELEMENT: &amp;lt;title&amp;gt;
    CHARS:   Wake up to ...
    END_ELM: &amp;lt;/title&amp;gt;
  &lt;code class="cCodeBold"&gt;IGNORABLE
&lt;/code&gt;  END_ELM: &amp;lt;/slide&amp;gt;
&lt;code class="cCodeBold"&gt;IGNORABLE
IGNORABLE
&lt;/code&gt;  ELEMENT: &amp;lt;slide
    ATTR: ...
  &amp;gt;
  ...&lt;a name="wp64996"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp64997"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, it is apparent that the &lt;code class="cCode"&gt;ignorableWhitespace&lt;/code&gt; is being invoked before and after comments and slide elements, whereas &lt;code class="cCode"&gt;characters&lt;/code&gt; was being invoked before there was a DTD. 
&lt;/p&gt;
&lt;a name="wp64999"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Cleanup
&lt;/h3&gt;
&lt;a name="wp65000"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Now that you have seen
ignorable whitespace echoed, remove that code from your version of the
Echo program. You won't need it any more in the exercises that follow. &lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65001"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: That change has been made in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo09.java" target="_blank"&gt;Echo09.java&lt;/a&gt;&lt;/code&gt;. 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65008"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Empty Elements, Revisited
&lt;/h3&gt;
&lt;a name="wp65009"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now that you understand how certain instances of whitespace can be
ignorable, it is time revise the definition of an empty element. That
definition can now be expanded to include &lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &amp;lt;foo&amp;gt;   &amp;lt;/foo&amp;gt;&lt;a name="wp65010"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65011"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
where there is whitespace between the tags and the DTD says that the whitespace is ignorable.
&lt;/p&gt;
&lt;a name="wp65166"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Echoing Entity References
&lt;/h3&gt;
&lt;a name="wp95106"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you wrote &lt;code class="cCode"&gt;slideSample06.xml&lt;/code&gt;, you defined entities for the singular and plural versions of the product name in the DTD:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;!ENTITY product  "WonderWidget"&amp;gt;
&amp;lt;!ENTITY products "WonderWidgets"&amp;gt;&lt;a name="wp98135"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp98125"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You referenced them in the XML this way:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;title&amp;gt;Wake up to &amp;amp;products;!&amp;lt;/title&amp;gt;&lt;a name="wp98151"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp98148"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now it's time to see how they're echoed when you process them with the SAX parser.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp95131"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML used here is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample06.xml" target="_blank"&gt;slideSample06.xml&lt;/a&gt;&lt;/code&gt;, which references &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow1b.dtd" target="_blank"&gt;slideshow1b.dtd&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp68104"&gt;Defining Attributes and Entities in the DTD&lt;/a&gt;. The output is shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo09-06.txt" target="_blank"&gt;Echo09-06.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample06-xml.html" target="_blank"&gt;slideSample06-xml.html&lt;/a&gt;&lt;/code&gt;, &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow1b-dtd.html" target="_blank"&gt;slideshow1b-dtd.html&lt;/a&gt;&lt;/code&gt;, and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo09-06.html" target="_blank"&gt;Echo09-06.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp95140"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you run the Echo program on &lt;code class="cCode"&gt;slideSample06.xml&lt;/code&gt;, here is the kind of thing you see:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;ELEMENT:        &amp;lt;title&amp;gt;
CHARS:        Wake up to &lt;code class="cCodeBold"&gt;WonderWidgets&lt;/code&gt;!
END_ELM:        &amp;lt;/title&amp;gt;&lt;a name="wp65168"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65169"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Note that the product name has been substituted for the entity reference.
&lt;/p&gt;
&lt;a name="wp65191"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Echoing the External Entity
&lt;/h3&gt;
&lt;a name="wp95190"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In &lt;code class="cCode"&gt;slideSample07.xml&lt;/code&gt;, you defined an external entity to reference a copyright file.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp95193"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML used here is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample07.xml" target="_blank"&gt;slideSample07.xml&lt;/a&gt;&lt;/code&gt; and in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/copyright.xml" target="_blank"&gt;copyright.xml&lt;/a&gt;&lt;/code&gt;. The output is shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo09-07.txt" target="_blank"&gt;Echo09-07.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample07-xml.html" target="_blank"&gt;slideSample07-xml.html&lt;/a&gt;&lt;/code&gt;, &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/copyright-xml.html" target="_blank"&gt;copyright-xml.html&lt;/a&gt;&lt;/code&gt;, and&lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo09-07.html" target="_blank"&gt; Echo09-07.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65192"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you run the Echo program on that version of the slide presentation, here is what you see:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;...
END_ELM: &amp;lt;/slide&amp;gt;
ELEMENT: &amp;lt;slide
  ATTR: type        "all"
&amp;gt;
  ELEMENT: &amp;lt;item&amp;gt;
  CHARS: 
This is the standard copyright message that our lawyers
make us put everywhere so we don't have to shell out a
million bucks every time someone spills hot coffee in their
lap...
  END_ELM: &amp;lt;/item&amp;gt;
END_ELM: &amp;lt;/slide&amp;gt;
...&lt;a name="wp65193"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65194"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Note that the newline that follows the comment in the file is echoed as
a character, but the comment itself is ignored. That is why the
copyright message appears to start on the next line after the &lt;code class="cCode"&gt;CHARS:&lt;/code&gt; label instead of immediately after the label: the first character echoed is actually the newline that follows the comment.
&lt;/p&gt;
&lt;a name="wp65196"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Summarizing Entities
&lt;/h3&gt;
&lt;a name="wp65197"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
An entity that is referenced in the document content, whether internal or external, is termed a &lt;span style="font-style: italic;"&gt;general entity&lt;/span&gt;. An entity that contains DTD specifications that are referenced from within the DTD is termed a &lt;span style="font-style: italic;"&gt;parameter entity&lt;/span&gt;. (More on that later.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=24004234340&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Choosing Your Parser Implementation</title><link>http://www.softxml.com/LearnTutorial.asp?id=32612322179&amp;f=jaxpsax&amp;fo=tutorials</link><description>If no other factory class is specified, the default SAXParserFactory class is used.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=32612322179&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Using the Validating Parser</title><link>http://www.softxml.com/LearnTutorial.asp?id=25146119571&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
By now, you have done a lot of experimenting with the nonvalidating
parser. It's time to have a look at the validating parser to find out
what happens when you use it to parse the sample presentation. &lt;/p&gt;
&lt;a name="wp65304"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You need to understand about two things about the validating parser at the outset:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp65305"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;A schema or document type definition (DTD) is required.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp65306"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Because the schema or DTD is present, the &lt;code class="cCode"&gt;ignorableWhitespace&lt;/code&gt; method is invoked whenever possible.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp65308"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Configuring the Factory
&lt;/h3&gt;
&lt;a name="wp65309"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The first step is to modify the Echo program so that it uses the validating parser instead of the nonvalidating parser.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65310"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code in this section is contained in&lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10.java" target="_blank"&gt; Echo10.java&lt;/a&gt;&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65311"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To use the validating parser, make the following highlighted changes:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public static void main(String argv[])
{
  if (argv.length != 1) {
    ...
  }
  &lt;code class="cCodeStruck"&gt;// Use the default (non-validating) parser
&lt;/code&gt;  &lt;code class="cCodeBold"&gt;// Use the validating parser
&lt;/code&gt;  SAXParserFactory factory = SAXParserFactory.newInstance();
  &lt;code class="cCodeBold"&gt;factory.setValidating(true);
&lt;/code&gt;  try {
    ...&lt;a name="wp65312"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65313"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, you configure the factory so that it will produce a validating parser when &lt;code class="cCode"&gt;newSAXParser&lt;/code&gt; is invoked. To configure it to return a namespace-aware parser, you can also use &lt;code class="cCode"&gt;setNamespaceAware(true)&lt;/code&gt;.
Sun's implementation supports any combination of configuration options.
(If a combination is not supported by a particular implementation, it
is required to generate a factory configuration error.)
&lt;/p&gt;
&lt;a name="wp90294"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Validating with XML Schema
&lt;/h3&gt;
&lt;a name="wp92449"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Although a full treatment of
XML Schema is beyond the scope of this tutorial, this section shows you
the steps you take to validate an XML document using an existing schema
written in the XML Schema language. (To learn more about XML Schema,
you can review the online tutorial, &lt;span style="font-style: italic;"&gt;XML Schema Part 0: Primer&lt;/span&gt;, at &lt;code class="cCode"&gt;&lt;a href="http://www.w3.org/TR/xmlschema-0/" target="_blank"&gt;http://www.w3.org/TR/xmlschema-0/&lt;/a&gt;&lt;/code&gt;.
You can also examine the sample programs that are part of the JAXP
download. They use a simple XML Schema definition to validate personnel
data stored in an XML file.)
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp92505"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;Note: There are multiple
schema-definition languages, including RELAX NG, Schematron, and the
W3C "XML Schema" standard. (Even a DTD qualifies as a "schema,"
although it is the only one that does not use XML syntax to describe
schema constraints.) However, "XML Schema" presents us with a
terminology challenge. Although the phrase "XML Schema schema" would be
precise, we'll use the phrase "XML Schema definition" to avoid the
appearance of redundancy. &lt;/p&gt;
&lt;hr&gt;&lt;a name="wp90707"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To be notified of validation errors in an XML document, the parser
factory must be configured to create a validating parser, as shown in
the preceding section. In addition, the following must be true:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp90849"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The appropriate properties must be set on the SAX parser.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp90850"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The appropriate error handler must be set.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp90856"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The document must be associated with a schema.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp90829"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Setting the SAX Parser Properties
&lt;/h4&gt;
&lt;a name="wp90830"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
It's helpful to start by defining the constants you'll use when setting the properties:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;static final String &lt;code class="cCodeBold"&gt;JAXP_SCHEMA_LANGUAGE&lt;/code&gt; =
    "http://java.sun.com/xml/jaxp/properties/schemaLanguage";

static final String &lt;code class="cCodeBold"&gt;W3C_XML_SCHEMA&lt;/code&gt; =
    "http://www.w3.org/2001/XMLSchema";&lt;a name="wp90574"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp90760"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, you configure the parser factory to generate a parser that is namespace-aware as well as validating:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;...
  SAXParserFactory factory = SAXParserFactory.newInstance();
  &lt;code class="cCodeBold"&gt;factory.setNamespaceAware(true);
&lt;/code&gt;  factory.setValidating(true);&lt;a name="wp90761"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp90765"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You'll learn more about namespaces in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPDOM8.html#wp76446"&gt;Validating with XML Schema&lt;/a&gt;.
For now, understand that schema validation is a namespace-oriented
process. Because JAXP-compliant parsers are not namespace-aware by
default, it is necessary to set the property for schema validation to
work.
&lt;/p&gt;
&lt;a name="wp90816"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;The last step is to configure
the parser to tell it which schema language to use. Here, you use the
constants you defined earlier to specify the W3C's XML Schema language:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;saxParser.setProperty(&lt;code class="cCodeBold"&gt;JAXP_SCHEMA_LANGUAGE&lt;/code&gt;, &lt;code class="cCodeBold"&gt;W3C_XML_SCHEMA&lt;/code&gt;);&lt;a name="wp90878"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp90912"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In the process, however, there is an extra error to handle. You'll take a look at that error next.
&lt;/p&gt;
&lt;a name="wp91010"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Setting Up the Appropriate Error Handling
&lt;/h4&gt;
&lt;a name="wp91011"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;In addition to the error
handling you've already learned about, there is one error that can
occur when you are configuring the parser for schema-based validation.
If the parser is not 1.2-compliant and therefore does not support XML
Schema, it can throw a &lt;code class="cCode"&gt;SAXNotRecognizedException&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp90967"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To handle that case, you wrap the &lt;code class="cCode"&gt;setProperty()&lt;/code&gt; statement in a &lt;code class="cCode"&gt;try&lt;/code&gt;/&lt;code class="cCode"&gt;catch&lt;/code&gt; block, as shown in the code highlighted here:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;...
SAXParser saxParser = factory.newSAXParser();
&lt;code class="cCodeBold"&gt;try {
&lt;/code&gt;  saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
} 
&lt;code class="cCodeBold"&gt;catch (SAXNotRecognizedException x) {
&lt;/code&gt;  // Happens if the parser does not support JAXP 1.2
  ...
&lt;code class="cCodeBold"&gt;}
&lt;/code&gt;...&lt;a name="wp90980"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp90895"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Associating a Document with a Schema
&lt;/h4&gt;
&lt;a name="wp90896"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now that the program is ready to validate the data using an XML Schema
definition, it is only necessary to ensure that the XML document is
associated with one. There are two ways to do that:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp90987"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;By including a schema declaration in the XML document&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp90993"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;By specifying the schema to use in the application&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp90897"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: When the application specifies the schema to use, it overrides any schema declaration in the document.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp90997"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To specify the schema definition in the document, you create XML such as this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;&lt;code class="cVariable"&gt;documentRoot
&lt;/code&gt;  &lt;code class="cCodeBold"&gt;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
&lt;/code&gt;  &lt;code class="cCodeBold"&gt;xsi:noNamespaceSchemaLocation&lt;/code&gt;='&lt;code class="cVariable"&gt;YourSchemaDefinition&lt;/code&gt;.xsd'
&amp;gt;
  ...&lt;a name="wp91055"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp101243"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The first attribute defines the XML namespace (&lt;code class="cCode"&gt;xmlns&lt;/code&gt;) prefix, &lt;code class="cCode"&gt;xsi&lt;/code&gt;, which stands for XML Schema instance. The second line specifies the schema to use for elements in the document that do &lt;span style="font-style: italic;"&gt;not&lt;/span&gt; have a namespace prefix--that is, for the elements you typically define in any simple, uncomplicated XML document.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp101248"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: You'll learn about namespaces in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPDOM8.html#wp76446"&gt;Validating with XML Schema&lt;/a&gt;.
For now, think of these attributes as the "magic incantation" you use
to validate a simple XML file that doesn't use them. After you've
learned more about namespaces, you'll see how to use XML Schema to
validate complex documents that use them. Those ideas are discussed in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPDOM8.html#wp63997"&gt;Validating with Multiple Namespaces&lt;/a&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp90899"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You can also specify the schema file in the application:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;static final String &lt;code class="cCodeBold"&gt;JAXP_SCHEMA_SOURCE&lt;/code&gt; =
    "http://java.sun.com/xml/jaxp/properties/schemaSource";

...
SAXParser saxParser = spf.newSAXParser();
...
&lt;code class="cCodeBold"&gt;saxParser.setProperty&lt;/code&gt;(&lt;code class="cCodeBold"&gt;JAXP_SCHEMA_SOURCE&lt;/code&gt;,
    new File(schemaSource));&lt;a name="wp90900"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp90925"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now that you know how to use an XML Schema definition, we'll turn to
the kinds of errors you can see when the application is validating its
incoming data. To do that, you'll use a document type definition (DTD)
as you experiment with validation.
&lt;/p&gt;
&lt;a name="wp90292"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Experimenting with Validation Errors
&lt;/h3&gt;
&lt;a name="wp65321"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To see what happens when the XML document does not specify a DTD, remove the &lt;code class="cCode"&gt;DOCTYPE&lt;/code&gt; statement from the XML file and run the Echo program on it.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65322"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The output shown here is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-01.txt" target="_blank"&gt;Echo10-01.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-01.html" target="_blank"&gt;Echo10-01.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65323"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The result you see looks like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt;
** Parsing error, line 9, uri .../slideSample01.xml
  Document root element "slideshow", must match DOCTYPE root 
"null"&lt;a name="wp72070"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp70796"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;Note: This message was
generated by the JAXP 1.2 libraries. If you are using a different
parser, the error message is likely to be somewhat different.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp68533"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This message says that the root element of the document must match the element specified in the &lt;code class="cCode"&gt;DOCTYPE&lt;/code&gt;
declaration. That declaration specifies the document's DTD. Because you
don't yet have one, it's value is null. In other words, the message is
saying that you are trying to validate the document, but no DTD has
been declared, because no &lt;code class="cCode"&gt;DOCTYPE&lt;/code&gt; declaration is present.
&lt;/p&gt;
&lt;a name="wp72093"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
So now you know that a DTD is a requirement for a valid document. That
makes sense. What happens when you run the parser on your current
version of the slide presentation, with the DTD specified?
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65327"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The output shown here is produced using &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample07.xml" target="_blank"&gt;slideSample07.xml&lt;/a&gt;&lt;/code&gt;, as described in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp68336"&gt;Referencing Binary Entities&lt;/a&gt;. The output is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-07.txt" target="_blank"&gt;Echo10-07.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-07.html" target="_blank"&gt;Echo10-07.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65328"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This time, the parser gives a different error message:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  ** Parsing error, line 29, uri file:...
  The content of element type "slide" must match 
"(image?,title,item*)&lt;a name="wp68935"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp68937"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This message says that the element found at line 29 (&lt;code class="cCode"&gt;&amp;lt;item&amp;gt;&lt;/code&gt;) does not match the definition of the &lt;code class="cCode"&gt;&amp;lt;slide&amp;gt;&lt;/code&gt; element in the DTD. The error occurs because the definition says that the &lt;code class="cCode"&gt;slide&lt;/code&gt; element requires a &lt;code class="cCode"&gt;title&lt;/code&gt;. That element is not optional, and the copyright slide does not have one. To fix the problem, add a question mark to make &lt;code class="cCode"&gt;title&lt;/code&gt; an optional element:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;!ELEMENT slide (image?, title&lt;code class="cCodeBold"&gt;?&lt;/code&gt;, item*)&amp;gt;&lt;a name="wp66998"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp66999"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Now what happens when you run the program?
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65333"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: You could also remove the copyright slide, producing the same result shown next, as reflected in&lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-06.txt" target="_blank"&gt; Echo10-06.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-06.html" target="_blank"&gt;Echo10-06.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65334"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The answer is that everything runs fine until the parser runs into the &lt;code class="cCode"&gt;&amp;lt;em&amp;gt;&lt;/code&gt;
tag contained in the overview slide. Because that tag is not defined in
the DTD, the attempt to validate the document fails. The output looks
like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  ...
  ELEMENT: &amp;lt;title&amp;gt;
  CHARS:   Overview
  END_ELM: &amp;lt;/title&amp;gt;
  ELEMENT: &amp;lt;item&amp;gt;
  CHARS:   Why &lt;code class="cCodeBold"&gt;** Parsing error, line 28&lt;/code&gt;, uri: ...
&lt;code class="cCodeBold"&gt;Element "em" must be declared.
&lt;/code&gt;org.xml.sax.SAXParseException: ...
...&lt;a name="wp65335"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65336"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The error message identifies the part of the DTD that caused validation to fail. In this case it is the line that defines an &lt;code class="cCode"&gt;item&lt;/code&gt; element as &lt;code class="cCode"&gt;(#PCDATA | item)&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp65337"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
As an exercise, make a copy of the file and remove all occurrences of &lt;code class="cCode"&gt;&amp;lt;em&amp;gt;&lt;/code&gt;
from it. Can the file be validated now? (In the next section, you'll
learn how to define parameter entries so that we can use XHTML in the
elements we are defining as part of the slide presentation.)
&lt;/p&gt;
&lt;a name="wp65339"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Error Handling in the Validating Parser
&lt;/h3&gt;
&lt;a name="wp65340"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;It is important to recognize
that the only reason an exception is thrown when the file fails
validation is as a result of the error-handling code you entered in the
early stages of this tutorial. That code is reproduced here:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void error(SAXParseException e)
throws SAXParseException
{
  &lt;code class="cCodeBold"&gt;throw e;
&lt;/code&gt;}&lt;a name="wp65341"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65342"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;If that exception is not
thrown, the validation errors are simply ignored. Try commenting out
the line that throws the exception.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=25146119571&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Parsing a Parameterized DTD</title><link>http://www.softxml.com/LearnTutorial.asp?id=23982087786&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
This section uses the Echo program to see what happens when you reference &lt;code class="cCode"&gt;xhtml.dtd&lt;/code&gt; in &lt;code class="cCode"&gt;slideshow2.dtd&lt;/code&gt;. It also covers the kinds of warnings that are generated by the SAX parser when a DTD is present.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp95208"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The XML file used here is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample08.xml" target="_blank"&gt;slideSample08.xml&lt;/a&gt;&lt;/code&gt;, which references &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow2.dtd" target="_blank"&gt;slideshow2.dtd&lt;/a&gt;&lt;/code&gt;. The output is contained in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-08.txt" target="_blank"&gt;Echo10-08.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample08-xml.html" target="_blank"&gt;slideSample08-xml.html&lt;/a&gt;&lt;/code&gt;, &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideshow2-dtd.html" target="_blank"&gt;slideshow2-dtd.html&lt;/a&gt;&lt;/code&gt;, and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo10-08.html" target="_blank"&gt;Echo10-08.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65452"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you try to echo the slide presentation, you will find that it now
contains a new error. The relevant part of the output is shown here
(formatted for readability):
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt;
** Parsing error, line 22, uri: .../slideshow.dtd
Element type "title" must not be declared more than once.&lt;a name="wp68986"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp70806"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;Note: The foregoing message was
generated by the JAXP 1.2 libraries. If you are using a different
parser, the error message is likely to be somewhat different.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp68987"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The problem is that &lt;code class="cCode"&gt;xhtml.dtd&lt;/code&gt; defines a &lt;code class="cCode"&gt;title&lt;/code&gt; element that is entirely different from the &lt;code class="cCode"&gt;title&lt;/code&gt; element defined in the slideshow DTD. Because there is no hierarchy in the DTD, these two definitions conflict.
&lt;/p&gt;
&lt;a name="wp65469"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;slideSample09.xml&lt;/code&gt;
version solves the problem by changing the name of the slide title. Run
the Echo program on that version of the slide presentation. It should
run to completion and display output like that shown in Echo10-09.
&lt;/p&gt;
&lt;a name="wp65470"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Congratulations! You have now
read a fully validated XML document. The change in that version of the
file has the effect of putting the DTD's &lt;code class="cCode"&gt;title&lt;/code&gt; element into a &lt;code class="cCode"&gt;slideshow&lt;/code&gt; "namespace" that you artificially constructed by hyphenating the name, so the &lt;code class="cCode"&gt;title&lt;/code&gt; element in the "&lt;code class="cCode"&gt;slideshow&lt;/code&gt; namespace" (&lt;code class="cCode"&gt;slide-title&lt;/code&gt;, really) is no longer in conflict with the &lt;code class="cCode"&gt;title&lt;/code&gt; element in &lt;code class="cCode"&gt;xhtml.dtd&lt;/code&gt;. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp95304"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: As mentioned in &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/IntroXML3.html#wp68796"&gt;Using Namespaces&lt;/a&gt;, namespaces let you accomplish the same goal without having to rename any elements.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp95313"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, we'll take a look at the kinds of warnings that the validating parser can produce when processing the DTD. 
&lt;/p&gt;
&lt;a name="wp65472"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
DTD Warnings
&lt;/h3&gt;
&lt;a name="wp65473"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
As mentioned earlier, warnings are generated only when the SAX parser
is processing a DTD. Some warnings are generated only by the validating
parser. The nonvalidating parser's main goal is operate as rapidly as
possible, but it too generates some warnings. (The explanations that
follow tell which does what.)
&lt;/p&gt;
&lt;a name="wp65474"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The XML specification suggests that warnings should be generated as a result of the following:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp65475"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Providing
additional declarations for entities, attributes, or notations. (Such
declarations are ignored. Only the first is used. Also, note that
duplicate definitions of &lt;span style="font-style: italic;"&gt;elements&lt;/span&gt; always produce a fatal error when validating, as you saw earlier.) &lt;/li&gt;&lt;/div&gt;
&lt;a name="wp65476"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Referencing an
undeclared element type. (A validity error occurs only if the
undeclared type is actually used in the XML document. A warning results
when the undeclared element is referenced in the DTD.) &lt;/li&gt;&lt;/div&gt;
&lt;a name="wp65478"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Declaring attributes for undeclared element types.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp65479"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The Java XML SAX parser also emits warnings in other cases: 
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp65480"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;No &lt;code class="cCode"&gt;&amp;lt;!DOCTYPE ...&amp;gt;&lt;/code&gt; when validating.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp65481"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;References to an
undefined parameter entity when not validating. (When validating, an
error results. Although nonvalidating parsers are not required to read
parameter entities, the Java XML parser does so. Because it is not a
requirement, the Java XML parser generates a warning, rather than an
error.)&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp65483"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Certain cases where the character-encoding declaration does not look right.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp65484"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
At this point, you have digested many XML concepts, including DTDs and
external entities.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=23982087786&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Handling Lexical Events</title><link>http://www.softxml.com/LearnTutorial.asp?id=3254898943&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
You saw earlier that if you are writing text out as XML, you need to know whether you are in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section. If you are, then angle brackets (&amp;lt;) and ampersands (&amp;amp;) should be output unchanged. But if you're not in a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section, they should be replaced by the predefined entities &lt;code class="cCode"&gt;&amp;amp;lt;&lt;/code&gt; and &lt;code class="cCode"&gt;&amp;amp;amp;&lt;/code&gt;. But how do you know whether you're processing a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section? 
&lt;/p&gt;
&lt;a name="wp65512"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Then again, if you are filtering XML in some way, you want to pass
comments along. Normally the parser ignores comments. How can you get
comments so that you can echo them? &lt;/p&gt;
&lt;a name="wp65513"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Finally, there are the parsed entity definitions. If an XML-filtering application sees &lt;code class="cCode"&gt;&amp;amp;myEntity;&lt;/code&gt; it needs to echo the same string, and not the text that is inserted in its place. How do you go about doing that? 
&lt;/p&gt;
&lt;a name="wp65514"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This section answers those questions. It shows you how to use &lt;code class="cCode"&gt;org.xml.sax.ext.LexicalHandler&lt;/code&gt; to identify comments, &lt;code class="cCode"&gt;CDATA&lt;/code&gt; sections, and references to parsed entities.
&lt;/p&gt;
&lt;a name="wp65515"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Comments, &lt;code class="cCode"&gt;CDATA&lt;/code&gt; tags, and references to parsed entities constitute &lt;span style="font-style: italic;"&gt;lexical&lt;/span&gt;
information--that is, information that concerns the text of the XML
itself, rather than the XML's information content. Most applications,
of course, are concerned only with the &lt;span style="font-style: italic;"&gt;content&lt;/span&gt; of an XML document. Such applications will not use the &lt;code class="cCode"&gt;LexicalEventListener&lt;/code&gt; API. But applications that output XML text will find it invaluable.
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65516"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: Lexical event handling is an optional parser feature. Parser
implementations are not required to support it. (The reference
implementation does so.) This discussion assumes that your parser does
so.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65518"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
How the LexicalHandler Works
&lt;/h3&gt;
&lt;a name="wp65519"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To be informed when the SAX parser sees lexical information, you configure the &lt;code class="cCode"&gt;XmlReader&lt;/code&gt; that underlies the parser with a &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt;. The &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt; interface defines these event-handling methods:
&lt;/p&gt;
&lt;a name="wp65523"&gt; &lt;/a&gt;&lt;p class="pDefinitionTerm"&gt;
&lt;code class="cCode"&gt;comment(String comment)&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp65524"&gt; &lt;/a&gt;&lt;p class="pDefinition"&gt;
Passes comments to the application
&lt;/p&gt;
&lt;a name="wp65525"&gt; &lt;/a&gt;&lt;p class="pDefinitionTerm"&gt;
&lt;code class="cCode"&gt;startCDATA(), endCDATA()&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp65526"&gt; &lt;/a&gt;&lt;p class="pDefinition"&gt;
Tells when a &lt;code class="cCode"&gt;CDATA&lt;/code&gt; section is starting and ending, which tells your application what kind of characters to expect the next time &lt;code class="cCode"&gt;characters()&lt;/code&gt; is called
&lt;/p&gt;
&lt;a name="wp65527"&gt; &lt;/a&gt;&lt;p class="pDefinitionTerm"&gt;
&lt;code class="cCode"&gt;startEntity(String name), endEntity(String name)&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp65528"&gt; &lt;/a&gt;&lt;p class="pDefinition"&gt;
Gives the name of a parsed entity
&lt;/p&gt;
&lt;a name="wp65529"&gt; &lt;/a&gt;&lt;p class="pDefinitionTerm"&gt;
&lt;code class="cCode"&gt;startDTD(String name, String publicId, String systemId), endDTD()&lt;/code&gt;
&lt;/p&gt;
&lt;a name="wp65530"&gt; &lt;/a&gt;&lt;p class="pDefinition"&gt;
Tells when a DTD is being processed, and identifies it
&lt;/p&gt;
&lt;a name="wp65532"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
Working with a LexicalHandler
&lt;/h3&gt;
&lt;a name="wp69127"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In the remainder of this section, you'll convert the Echo application into a lexical handler and play with its features. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp69128"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code shown in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo11.java" target="_blank"&gt;Echo11.java&lt;/a&gt;&lt;/code&gt;. The output is shown in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo11-09.txt" target="_blank"&gt;Echo11-09.txt&lt;/a&gt;&lt;/code&gt;. (The browsable version is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo11-09.html" target="_blank"&gt;Echo11-09.html&lt;/a&gt;&lt;/code&gt;.)
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp69129"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To start, add the following highlighted code to implement the &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt; interface and add the appropriate methods.
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;span style="font-weight: normal;"&gt;import org.xml.sax.*;
import org.xml.sax.helpers.DefaultHandler;
&lt;/span&gt;&lt;code class="cCodeBold"&gt;import org.xml.sax.ext.LexicalHandler;
...
&lt;/code&gt;public class Echo extends HandlerBase
  &lt;code class="cCodeBold"&gt;implements LexicalHandler
&lt;/code&gt;{ 
  public static void main(String argv[])
    {
      ...
      // Use an instance of ourselves as the SAX event handler
      &lt;code class="cCodeStruck"&gt;DefaultHandler handler = new Echo();
&lt;/code&gt;      &lt;code class="cCodeBold"&gt;Echo handler = new Echo();
&lt;/code&gt;      ...&lt;a name="wp69036"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65537"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
At this point, the &lt;code class="cCode"&gt;Echo&lt;/code&gt;
class extends one class and implements an additional interface. You
have changed the class of the handler variable accordingly, so you can
use the same instance as either a &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; or a &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt;, as appropriate. 
&lt;/p&gt;
&lt;a name="wp65538"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Next, add the following highlighted code to get the &lt;code class="cCode"&gt;XMLReader&lt;/code&gt; that the parser delegates to, and configure it to send lexical events to your lexical handler:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public static void main(String argv[])
{
  ...
  try {
    ...
    // Parse the input
    SAXParser saxParser = factory.newSAXParser();
&lt;code class="cCodeBold"&gt;    XMLReader xmlReader = saxParser.getXMLReader();
    xmlReader.setProperty(
      "http://xml.org/sax/properties/lexical-handler",
      handler
      ); 
&lt;/code&gt;    saxParser.parse( new File(argv[0]), handler);
  } catch (SAXParseException spe) {
    ...&lt;a name="wp65539"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65540"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, you configure the &lt;code class="cCode"&gt;XMLReader&lt;/code&gt; using the &lt;code class="cCode"&gt;setProperty()&lt;/code&gt; method defined in the &lt;code class="cCode"&gt;XMLReader&lt;/code&gt; class. The property name, defined as part of the SAX standard, is the URN, &lt;code class="cCode"&gt;http://xml.org/sax/properties/lexical-handler&lt;/code&gt;.
&lt;/p&gt;
&lt;a name="wp92567"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Finally, add the following highlighted code to define the appropriate methods that implement the interface.
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void warning(SAXParseException err)
  ...
}
&lt;code class="cCodeBold"&gt;
public void comment(char[] ch, int start, int length)
throws SAXException
{
}

public void startCDATA()
throws SAXException
{
}

pubic void endCDATA()
throws SAXException
{
}

public void startEntity(String name)
throws SAXException
{
}

public void endEntity(String name)
throws SAXException
{
}

public void startDTD(
  String name, String publicId, String systemId)
throws SAXException
{
}

public void endDTD()
throws SAXException
{
}
&lt;/code&gt;
private void echoText()
  ...&lt;a name="wp65542"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65551"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
You have now turned the &lt;code class="cCode"&gt;Echo&lt;/code&gt; class into a lexical handler. In the next section, you'll start experimenting with lexical events.
&lt;/p&gt;
&lt;a name="wp65553"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Echoing Comments
&lt;/h4&gt;
&lt;a name="wp65554"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The next step is to do something with one of the new methods. Add the
following highlighted code to echo comments in the XML file:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void comment(char[] ch, int start, int length)
  throws SAXException
{
&lt;code class="cCodeBold"&gt;  String text = new String(ch, start, length);
  nl(); 
  emit("COMMENT: "+text);
&lt;/code&gt;}&lt;a name="wp65555"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65556"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When you compile the Echo program and run it on your XML file, the result looks something like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;COMMENT:   A SAMPLE set of slides 
COMMENT:  FOR WALLY / WALLIES 
COMMENT: 
  DTD for a simple "slide show".&lt;a name="wp65557"&gt; &lt;/a&gt;
COMMENT:  Defines the %inline; declaration 
COMMENT:  ...&lt;a name="wp65558"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65560"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;The line endings in the
comments are passed as part of the comment string, again normalized to
newlines. You can also see that comments in the DTD are echoed along
with comments from the file. (That can pose problems when you want to
echo only comments that are in the data file. To get around that
problem, you can use the &lt;code class="cCode"&gt;startDTD&lt;/code&gt; and &lt;code class="cCode"&gt;endDTD&lt;/code&gt; methods.)
&lt;/p&gt;
&lt;a name="wp65562"&gt; &lt;/a&gt;&lt;h4 class="pHeading3"&gt;
Echoing Other Lexical Information
&lt;/h4&gt;
&lt;a name="wp65563"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
To finish learning about lexical events, you'll exercise the remaining &lt;code class="cCode"&gt;LexicalHandler&lt;/code&gt; methods. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65564"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The code shown in this section is in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo12.java" target="_blank"&gt;Echo12.java&lt;/a&gt;&lt;/code&gt;. The file it operates on is &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample09.xml" target="_blank"&gt;slideSample09.xml&lt;/a&gt;&lt;/code&gt;. The results of processing are in &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo12-09.txt" target="_blank"&gt;Echo12-09.txt&lt;/a&gt;&lt;/code&gt;. (The browsable versions are &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/xml/samples/slideSample09-xml.html" target="_blank"&gt;slideSample09-xml.html&lt;/a&gt;&lt;/code&gt; and &lt;code class="cCode"&gt;&lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/examples/jaxp/sax/samples/Echo12-09.html" target="_blank"&gt;Echo12-09.html&lt;/a&gt;&lt;/code&gt;.) 
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65565"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Make the following highlighted changes to remove the comment echo (you
no longer need that) and echo the other events, along with any
characters that have been accumulated when an event occurs:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;public void comment(char[] ch, int start, int length)
throws SAXException
{
&lt;code class="cCodeStruck"&gt;  String text = new String(ch, start, length);
  nl(); 
  emit("COMMENT: "+text);
&lt;/code&gt;}&lt;a name="wp65566"&gt; &lt;/a&gt;
public void startCDATA()
throws SAXException
{
&lt;code class="cCodeBold"&gt;  echoText();
  nl(); 
  emit("START CDATA SECTION");
&lt;/code&gt;}&lt;a name="wp65567"&gt; &lt;/a&gt;
public void endCDATA()
throws SAXException
{
&lt;code class="cCodeBold"&gt;  echoText();
  nl(); 
  emit("END CDATA SECTION");
&lt;/code&gt;}&lt;a name="wp65568"&gt; &lt;/a&gt;
public void startEntity(String name)
throws SAXException
{
&lt;code class="cCodeBold"&gt;  echoText();
  nl(); 
  emit("START ENTITY: "+name);
&lt;/code&gt;}&lt;a name="wp65569"&gt; &lt;/a&gt;
public void endEntity(String name)
throws SAXException
{
&lt;code class="cCodeBold"&gt;  echoText();
  nl(); 
  emit("END ENTITY: "+name);
&lt;/code&gt;}&lt;a name="wp65570"&gt; &lt;/a&gt;
public void startDTD(String name, String publicId, String 
systemId)
throws SAXException
{ 
  &lt;code class="cCodeBold"&gt;nl(); 
  emit("START DTD: "+name
    +"          publicId=" + publicId
    +"          systemId=" + systemId);&lt;/code&gt; 
}&lt;a name="wp65571"&gt; &lt;/a&gt;
public void endDTD()
throws SAXException
{ 
  &lt;code class="cCodeBold"&gt;nl(); 
  emit("END DTD");&lt;/code&gt; 
}&lt;a name="wp65572"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65573"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here is what you see when the &lt;code class="cCode"&gt;DTD&lt;/code&gt; is processed:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;START DTD: slideshow
      publicId=null
      systemId=slideshow3.dtd
START ENTITY: ...
...
END DTD&lt;a name="wp65574"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;a name="wp65575"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: To see events that occur while the DTD is being processed, use &lt;code class="cCode"&gt;org.xml.sax.ext.DeclHandler&lt;/code&gt;.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65576"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here is some of the additional output you see when the internally defined &lt;code class="cCode"&gt;products&lt;/code&gt; entity is processed with the latest version of the program: 
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code style="font-weight: bold;" class="cCodeBold"&gt;START ENTITY: products
&lt;/code&gt;&lt;span style="font-weight: normal;"&gt;CHARS:   WonderWidgets
&lt;/span&gt;&lt;code class="cCodeBold"&gt;END ENTITY: products&lt;/code&gt;&lt;a name="wp70706"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp70707"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
And here is the additional output you see as a result of processing the external copyright entity: 
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;  START ENTITY: copyright
&lt;/code&gt;  CHARS: 
This is the standard copyright message that our lawyers
make us put everywhere so we don't have to shell out a
million bucks every time someone spills hot coffee in their
lap...</description><guid>http://www.softxml.com/LearnTutorial.asp?id=3254898943&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Using the DTDHandler and EntityResolver</title><link>http://www.softxml.com/LearnTutorial.asp?id=40885547928&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
In this section, we discuss the two remaining SAX event handlers: &lt;code class="cCode"&gt;DTDHandler&lt;/code&gt; and &lt;code class="cCode"&gt;EntityResolver&lt;/code&gt;. The &lt;code class="cCode"&gt;DTDHandler&lt;/code&gt; is invoked when the DTD encounters an unparsed entity or a notation declaration. The &lt;code class="cCode"&gt;EntityResolver&lt;/code&gt; comes into play when a URN (public ID) must be resolved to a URL (system ID).
&lt;/p&gt;
&lt;a name="wp65659"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
The DTDHandler API
&lt;/h3&gt;
&lt;a name="wp65663"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
In &lt;a href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPSAX8.html#wp90267"&gt;Choosing Your Parser Implementation&lt;/a&gt;
you saw a method for referencing a file that contains binary data, such
as an image file, using MIME data types. That is the simplest, most
extensible mechanism. For compatibility with older SGML-style data,
though, it is also possible to define an unparsed entity. &lt;/p&gt;
&lt;a name="wp65664"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;NDATA&lt;/code&gt; keyword defines an unparsed entity:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &amp;lt;!ENTITY myEntity SYSTEM "..URL.." &lt;code class="cCodeBold"&gt;NDATA gif&lt;/code&gt;&amp;gt;&lt;a name="wp65665"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65666"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;NDATA&lt;/code&gt;
keyword says that the data in this entity is not parsable XML data but
instead is data that uses some other notation. In this case, the
notation is named &lt;code class="cCode"&gt;gif&lt;/code&gt;. The DTD must then include a declaration for that notation, which would look something like this:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &amp;lt;!&lt;code class="cCodeBold"&gt;NOTATION gif&lt;/code&gt; SYSTEM "..URL.."&amp;gt;&lt;a name="wp65667"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65668"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
When the parser sees an unparsed entity or a notation declaration, it
does nothing with the information except to pass it along to the
application using the &lt;code class="cCode"&gt;DTDHandler&lt;/code&gt; interface. That interface defines two methods:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&lt;code class="cCodeBold"&gt;notationDecl&lt;/code&gt;(String name, String publicId, String systemId) &lt;a name="wp65669"&gt; &lt;/a&gt;
&lt;code class="cCodeBold"&gt;unparsedEntityDecl&lt;/code&gt;(String name, String publicId, 
  String systemId, String notationName) &lt;a name="wp65670"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65671"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;notationDecl&lt;/code&gt;
method is passed the name of the notation and either the public or the
system identifier, or both, depending on which is declared in the DTD.
The &lt;code class="cCode"&gt;unparsedEntityDecl&lt;/code&gt; method is passed the name of the entity, the appropriate identifiers, and the name of the notation it uses. 
&lt;/p&gt;
&lt;hr&gt;
&lt;a name="wp65672"&gt; &lt;/a&gt;&lt;p class="pNote"&gt;
Note: The &lt;code class="cCode"&gt;DTDHandler&lt;/code&gt; interface is implemented by the &lt;code class="cCode"&gt;DefaultHandler&lt;/code&gt; class.
&lt;/p&gt;
&lt;hr&gt;&lt;a name="wp65673"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Notations can also be used in attribute declarations. For example, the
following declaration requires notations for the GIF and PNG image-file
formats:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;&amp;lt;!ENTITY image EMPTY&amp;gt;
&amp;lt;!ATTLIST image 
    ...
    type&lt;code class="cCodeBold"&gt;  NOTATION  (gif | png) "gif"
&lt;/code&gt;&amp;gt;&lt;a name="wp65674"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65675"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
Here, the &lt;code class="cCode"&gt;type&lt;/code&gt; is declared as being either &lt;code class="cCode"&gt;gif&lt;/code&gt; or &lt;code class="cCode"&gt;png&lt;/code&gt;. The default, if neither is specified, is &lt;code class="cCode"&gt;gif&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp65676"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;Whether the notation reference
is used to describe an unparsed entity or an attribute, it is up to the
application to do the appropriate processing. The parser knows nothing
at all about the semantics of the notations. It only passes on the
declarations.
&lt;/p&gt;
&lt;a name="wp65678"&gt; &lt;/a&gt;&lt;h3 class="pHeading2"&gt;
The EntityResolver API
&lt;/h3&gt;
&lt;a name="wp65679"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;EntityResolver&lt;/code&gt;
API lets you convert a public ID (URN) into a system ID (URL). Your
application may need to do that, for example, to convert something like
&lt;code class="cCode"&gt;href="urn:/someName"&lt;/code&gt; into &lt;code class="cCode"&gt;"http://someURL"&lt;/code&gt;. 
&lt;/p&gt;
&lt;a name="wp65680"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
The &lt;code class="cCode"&gt;EntityResolver&lt;/code&gt; interface defines a single method:
&lt;/p&gt;
&lt;div class="pPreformattedRelative"&gt;&lt;pre class="pPreformattedRelative"&gt;  &lt;code class="cCodeBold"&gt;resolveEntity&lt;/code&gt;(String publicId, String systemId)&lt;a name="wp65681"&gt; &lt;/a&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;a name="wp65682"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
This method returns an &lt;code class="cCode"&gt;InputSource&lt;/code&gt; object, which can be used to access the entity's contents.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=40885547928&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item><item><title>Further Information</title><link>http://www.softxml.com/LearnTutorial.asp?id=24948599294&amp;f=jaxpsax&amp;fo=tutorials</link><description>&lt;p class="pBody"&gt;
For further information on the SAX standard, see
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp93302"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The SAX standard page: &lt;code class="cCode"&gt;&lt;a href="http://www.saxproject.org/" target="_blank"&gt;http://www.saxproject.org/&lt;/a&gt;&lt;/code&gt;&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp93311"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
For more information on the StAX pull parser, see:
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp98033"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The Java Community Process page:&lt;br&gt;&lt;code class="cCode"&gt;&lt;a href="http://jcp.org/en/jsr/detail?id=173" target="_blank"&gt;http://jcp.org/en/jsr/detail?id=173&lt;/a&gt;&lt;/code&gt;.&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp98066"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;Elliot Rusty Harold's introduction at&lt;br&gt;&lt;code class="cCode"&gt;&lt;a href="http://www.xml.com/pub/a/2003/09/17/stax.html" target="_blank"&gt;http://www.xml.com/pub/a/2003/09/17/stax.html&lt;/a&gt;&lt;/code&gt;.&lt;/li&gt;&lt;/div&gt;
&lt;/ul&gt;&lt;/div&gt;
&lt;a name="wp98032"&gt; &lt;/a&gt;&lt;p class="pBody"&gt;
For more information on schema-based validation mechanisms, see
&lt;/p&gt;
&lt;div class="pSmartList1"&gt;&lt;ul class="pSmartList1"&gt;
&lt;a name="wp93315"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;The W3C standard validation mechanism, XML Schema:&lt;br&gt;&lt;code class="cCode"&gt;&lt;a href="http://www.w3c.org/XML/Schema" target="_blank"&gt;http://www.w3c.org/XML/Schema&lt;/a&gt;&lt;/code&gt;&lt;/li&gt;&lt;/div&gt;
&lt;a name="wp93332"&gt; &lt;/a&gt;&lt;div class="pSmartList1"&gt;&lt;li&gt;RELAX NG's regular-expression-based validation mechanism:&lt;br&gt;&lt;code class="cCode"&gt;&lt;a href="http://www.oasis-open.org/committees/relax-ng/" target="_blank"&gt;http://www.oasis-open.</description><guid>http://www.softxml.com/LearnTutorial.asp?id=24948599294&amp;f=jaxpsax&amp;fo=tutorials</guid><category>jaxpsax</category></item></channel></rss>