com.google.gdata.wireformats
Class XmlParser

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by com.google.gdata.wireformats.XmlParser
All Implemented Interfaces:
WireFormatParser, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class XmlParser
extends org.xml.sax.helpers.DefaultHandler
implements WireFormatParser

XML parser, branched from XmlParser.

The plan is to integrate it tighter with the WireFormatParser interface, remove unnecessary interfaces and parameters (in our new data model, there is only one XmlParser.ElementHandler), and move it away from the util package.

Existing data classes continue to use the old XML parser until they've been migrated to the new data model, at which point they will start to use the new XML parser.

This is a thin layer on top of a SAX parser. The key concept necessary to understand this parser is Element Handler. Element handlers are type-specific parsers. Each handler instance contains an instance of the Java type corresponding to the XML type it parses. At any given time, one handler is active, and zero or more handlers are kept on the stack. This corresponds directly to the set of currently opened XML tags.

To use this parser, one must define an XmlParser.ElementHandler type (usually one per XML schema type), specify the root element handler, and pass a reader to the parse(Element) method.

See Also:
XmlParser.ElementHandler

Field Summary
protected  java.util.Map<java.lang.String,java.util.Stack<com.google.gdata.wireformats.XmlParser.NamespaceDecl>> namespaceMap
          Set of all namespace declarations valid at the current location.
protected  StreamProperties props
          Input properties for parsing
protected  java.lang.String rootElementName
          Root element name.
protected  com.google.gdata.wireformats.XmlParser.ElementHandler rootHandler
          Root element handler.
protected  java.lang.String rootNamespace
          Root element namespace URI.
 
Constructor Summary
XmlParser(StreamProperties props, java.io.Reader r, java.nio.charset.Charset cs)
          Construct XML parser for given reader.
XmlParser(StreamProperties props, XmlEventSource eventSource)
          Construct XML parser for a given event source.
 
Method Summary
 void characters(char[] text, int start, int len)
          SAX callback.
protected  XmlHandler createRootHandler(ValidationContext vc, Element element, ElementMetadata<?,?> metadata)
          Create the xml handler for the root element.
 void endElement(java.lang.String namespace, java.lang.String localName, java.lang.String qName)
          SAX callback.
 void endPrefixMapping(java.lang.String alias)
          SAX callback.
 void ignorableWhitespace(char[] text, int start, int len)
          SAX callback.
 Element parse(Element element)
          Parse content from a source provided to the parser at construction time.
 void setDocumentLocator(org.xml.sax.Locator newLocator)
          SAX callback.
 void startElement(java.lang.String namespace, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs)
          SAX callback.
 void startPrefixMapping(java.lang.String alias, java.lang.String uri)
          SAX callback.
protected  void throwParseException(ParseException e)
          Throws a parse exception with line/column information.
 
Methods inherited from class org.xml.sax.helpers.DefaultHandler
endDocument, error, fatalError, notationDecl, processingInstruction, resolveEntity, skippedEntity, startDocument, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

props

protected final StreamProperties props
Input properties for parsing


rootHandler

protected com.google.gdata.wireformats.XmlParser.ElementHandler rootHandler
Root element handler.


rootNamespace

protected java.lang.String rootNamespace
Root element namespace URI.


rootElementName

protected java.lang.String rootElementName
Root element name.


namespaceMap

protected java.util.Map<java.lang.String,java.util.Stack<com.google.gdata.wireformats.XmlParser.NamespaceDecl>> namespaceMap
Set of all namespace declarations valid at the current location. Includes namespace declarations from all ancestor elements.

Constructor Detail

XmlParser

public XmlParser(StreamProperties props,
                 java.io.Reader r,
                 java.nio.charset.Charset cs)
Construct XML parser for given reader.

Parameters:
props - stream properties for parsing
r - reader where input is retrieved from
cs - character set used to encode input

XmlParser

public XmlParser(StreamProperties props,
                 XmlEventSource eventSource)
Construct XML parser for a given event source.

Parameters:
props - stream properties for parsing
eventSource - event source
Method Detail

parse

public Element parse(Element element)
              throws java.io.IOException,
                     ParseException,
                     ContentValidationException
Description copied from interface: WireFormatParser
Parse content from a source provided to the parser at construction time.

Specified by:
parse in interface WireFormatParser
Parameters:
element - root of parsed element tree
Returns:
root of parsed element tree
Throws:
java.io.IOException - if content cannot be accessed
ParseException - if content cannot be parsed invalid
ContentValidationException - if content fails metadata validation

createRootHandler

protected XmlHandler createRootHandler(ValidationContext vc,
                                       Element element,
                                       ElementMetadata<?,?> metadata)
Create the xml handler for the root element. Subclasses can supply their own parse handlers.


throwParseException

protected void throwParseException(ParseException e)
                            throws ParseException
Throws a parse exception with line/column information.

Throws:
ParseException

startElement

public void startElement(java.lang.String namespace,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attrs)
                  throws org.xml.sax.SAXException
SAX callback.

Specified by:
startElement in interface org.xml.sax.ContentHandler
Overrides:
startElement in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

endElement

public void endElement(java.lang.String namespace,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException
SAX callback.

Specified by:
endElement in interface org.xml.sax.ContentHandler
Overrides:
endElement in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

characters

public void characters(char[] text,
                       int start,
                       int len)
                throws org.xml.sax.SAXException
SAX callback.

Specified by:
characters in interface org.xml.sax.ContentHandler
Overrides:
characters in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] text,
                                int start,
                                int len)
                         throws org.xml.sax.SAXException
SAX callback.

Specified by:
ignorableWhitespace in interface org.xml.sax.ContentHandler
Overrides:
ignorableWhitespace in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator newLocator)
SAX callback.

Specified by:
setDocumentLocator in interface org.xml.sax.ContentHandler
Overrides:
setDocumentLocator in class org.xml.sax.helpers.DefaultHandler

startPrefixMapping

public void startPrefixMapping(java.lang.String alias,
                               java.lang.String uri)
SAX callback.

Specified by:
startPrefixMapping in interface org.xml.sax.ContentHandler
Overrides:
startPrefixMapping in class org.xml.sax.helpers.DefaultHandler

endPrefixMapping

public void endPrefixMapping(java.lang.String alias)
SAX callback.

Specified by:
endPrefixMapping in interface org.xml.sax.ContentHandler
Overrides:
endPrefixMapping in class org.xml.sax.helpers.DefaultHandler