Accessing Web Services - Beginning Java ME Platform - page 347

buffer = null;

}

public void endDocument() {
}

}

The handler for parsing Location objects in XML form uses a Location instance and a
few private variables during the parsing operation to keep track of the object's state,
building up the resulting Location object in the member variable location . Key to this is
the StringBuffer buffer, which the handler uses to build up string representations of any
character data, such as the current temperature or forecast.
As the SAX parser works through the XML—I show you how to set up and start that
process in Listing 13-9—the first event the handler receives is startDocument . The method
handling this event simply sets the internal state of the handler, creating a new Location
to save the parse results if the client used the handler's default constructor, providing no
Location object.
The SAX parser invokes the startElement every time it encounters the beginning of
a new element, such as <weather> or <temperature> . The method receives both the full
name of the element (in qName ) and the name (in localName ) in the namespace URL (in
uri ); typically you'll want to examine qName , unless you're parsing XML with multiple
namespaces. Listing 13-8 does just this, setting up the handler's state to accept the data
for the tag that the handler's just encountered. In some cases, such as when parsing the
<weather> tag, the handler can do all of its work right away by working with individual
attributes; you can obtain the value of an attribute using its getValue method, or its
type using the getType method. In other cases, the code uses the value of an attribute to
provide some runtime checking on the incoming data—for example, by rejecting
weather data in units other than English units.
Once the SAX parser invokes startElement , it invokes either characters or endElement
next, depending on whether the element it's parsing has character data. The characters
element takes a byte array containing the characters the parser has read; it may be
invoked multiple times for a single entity, so it's up to you to buffer the results.

■

Caution Don't ignore the start and length arguments of characters ! It's up to the SAX parser to
determine how it wants to manage its internal array of characters, and what you get in the incoming charac-
ter array may be garbage outside the bounds that start and length together specify.

If startElement is where your handler prepares to handle an incoming element, then
endElement is the obvious place where it should store aside the datum the element repre-
sents. This endElement does just this, using the indicated element type to decide where the