com.google.gdata.wireformats
Class XmlHandler

java.lang.Object
  extended by com.google.gdata.wireformats.XmlHandler

public class XmlHandler
extends java.lang.Object

XML handler that translates XML content from a wire format into an in-memory representation.


Field Summary
protected  Element element
          Element being parsed.
protected  ElementMetadata<?,?> metadata
          Metadata for this element.
protected  Element parentElement
          Parent element, if non-null the element will be added to the parent after it has been fully parsed.
 java.lang.String qName
          This element's QName.
 java.lang.String value
          This element's text() value.
protected  ValidationContext vc
          Validation context, used to accumulate metadata validation errors discovered during parsing.
 java.lang.String xmlBase
          The current state of xml:base.
 java.lang.String xmlLang
          The current state of xml:lang.
 
Constructor Summary
XmlHandler(ValidationContext vc, Element parent, Element element, ElementMetadata<?,?> metadata)
          Construct an xml parser that will add the element to its parent after parsing is completed.
 
Method Summary
protected  Element createChildElement(QName qName, ElementMetadata<?,?> metadata)
          Create a child element for the given name and metadata.
protected  XmlHandler createHandler(QName qName, Element parent, Element child, ElementMetadata<?,?> metadata)
          Hook to allow subclasses to change the type of handler being returned.
protected  ElementMetadata<?,?> findMetadata(QName qName)
          Returns the appropriate metadata to use for the given qualified name.
 java.lang.String getAbsoluteUri(java.lang.String uriValue)
          Utility routine that combines the current state of xml:base with the specified URI to obtain an absolute URI.
 java.lang.Boolean getBooleanAttribute(org.xml.sax.Attributes attrs, java.lang.String attrName)
          Utility method to return the value of an xsd:boolean attribute.
 XmlHandler getChildHandler(QName qName, org.xml.sax.Attributes attrs, java.util.List<XmlNamespace> namespaces)
          Default child handler for xml.
 Element getElement()
           
 void initializeXmlBlob(XmlBlob xmlBlob, boolean mixedContent, boolean fullTextIndex)
          If a derived class wishes to retrieve all unrecognized XML in a blob, it calls this method.
protected  java.lang.Boolean parseBooleanValue(java.lang.String booleanValue)
          Utility method to parse provided xsd:boolean value.
 void processAttribute(QName qn, java.lang.String value)
          Called to process an attribute.
 void processEndElement()
          Called to process this element when the closing tag is encountered.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

vc

protected final ValidationContext vc
Validation context, used to accumulate metadata validation errors discovered during parsing.


parentElement

protected final Element parentElement
Parent element, if non-null the element will be added to the parent after it has been fully parsed.


metadata

protected final ElementMetadata<?,?> metadata
Metadata for this element.


element

protected final Element element
Element being parsed.


qName

public java.lang.String qName
This element's QName. Used for error reporting.


value

public java.lang.String value
This element's text() value.


xmlLang

public java.lang.String xmlLang
The current state of xml:lang. See http://www.w3.org/TR/REC-xml/#sec-lang-tag for more information.


xmlBase

public java.lang.String xmlBase
The current state of xml:base. See http://www.cafeconleche.org/books/xmljava/chapters/ch03s03.html for more information.

Constructor Detail

XmlHandler

public XmlHandler(ValidationContext vc,
                  Element parent,
                  Element element,
                  ElementMetadata<?,?> metadata)
Construct an xml parser that will add the element to its parent after parsing is completed.

Method Detail

getElement

public Element getElement()
Returns:
element that was parsed

processAttribute

public void processAttribute(QName qn,
                             java.lang.String value)
                      throws ParseException
Called to process an attribute. Designed to be overridden by derived classes.

Parameters:
qn - Attribute's qualified name.
value - Attribute value.
Throws:
ParseException - Invalid attribute.

getChildHandler

public XmlHandler getChildHandler(QName qName,
                                  org.xml.sax.Attributes attrs,
                                  java.util.List<XmlNamespace> namespaces)
                           throws ParseException,
                                  java.io.IOException
Default child handler for xml. This will parse into a Element if the element has not been declared, otherwise it will parse into the type defined by the metadata.

Parameters:
qName - Child element's qualified name.
attrs - Child element attributes. These attributes will be communicated to the child element handler through its processAttribute(com.google.gdata.model.QName, java.lang.String) method. They are passed here because sometimes the value of some attribute determines the element's content type, so different element handlers may be needed.
namespaces - List of namespaces in effect for child element.
Returns:
Child element handler, or null if the child is unrecognized.
Throws:
ParseException - if a non-repeating element is repeated, or if the element type requested cannot be created.
java.io.IOException - from overriding code. Not thrown by the default implementation.

createHandler

protected XmlHandler createHandler(QName qName,
                                   Element parent,
                                   Element child,
                                   ElementMetadata<?,?> metadata)
Hook to allow subclasses to change the type of handler being returned.


findMetadata

protected ElementMetadata<?,?> findMetadata(QName qName)
Returns the appropriate metadata to use for the given qualified name.


createChildElement

protected Element createChildElement(QName qName,
                                     ElementMetadata<?,?> metadata)
                              throws ParseException
Create a child element for the given name and metadata.

Throws:
ParseException

processEndElement

public void processEndElement()
                       throws ParseException
Called to process this element when the closing tag is encountered. The default implementation refuses to accept text() content, unless the handler is configured to accept unrecognized XML with mixed content.

Throws:
ParseException

initializeXmlBlob

public void initializeXmlBlob(XmlBlob xmlBlob,
                              boolean mixedContent,
                              boolean fullTextIndex)
                       throws java.io.IOException
If a derived class wishes to retrieve all unrecognized XML in a blob, it calls this method. It must be called in the constructor, in the parent element handler, or in processAttribute(com.google.gdata.model.QName, java.lang.String).

Parameters:
xmlBlob - Supplies the XML blob that stores the resulting XML.
mixedContent - Specifies that the handler accepts mixed content XML.
fullTextIndex - Flag indicating whether unrecognized XML should be processed for full-text indexing. If set, the resulting string ready for indexing is stored in XmlBlob.fullText.
Throws:
java.io.IOException

getAbsoluteUri

public java.lang.String getAbsoluteUri(java.lang.String uriValue)
                                throws ParseException
Utility routine that combines the current state of xml:base with the specified URI to obtain an absolute URI.

See http://www.cafeconleche.org/books/xmljava/chapters/ch03s03.html for more information.

Parameters:
uriValue - URI to be interpreted in the context of xml:base.
Returns:
Corresponding absolute URI.
Throws:
ParseException - Invalid URI.

getBooleanAttribute

public java.lang.Boolean getBooleanAttribute(org.xml.sax.Attributes attrs,
                                             java.lang.String attrName)
                                      throws ParseException
Utility method to return the value of an xsd:boolean attribute.

Parameters:
attrs - Elements attributes to test against.
attrName - Attribute name.
Returns:
the Boolean value if the attribute is present, or null otherwise.
Throws:
ParseException - if attribute value is not valid xsd:boolean.

parseBooleanValue

protected java.lang.Boolean parseBooleanValue(java.lang.String booleanValue)
                                       throws ParseException
Utility method to parse provided xsd:boolean value.

Parameters:
booleanValue - xsd:boolean value to parse
Returns:
the Boolean value or null
Throws:
ParseException - if value is not valid xsd:boolean.