com.google.gdata.wireformats

Class XmlHandler

java.lang.Object

com.google.gdata.wireformats.XmlHandler

public class XmlHandler
extends Object

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

Field Summary

Fields

Modifier and Type	Field and Description
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.
String	qName This element's QName.
String	value This element's text() value.
protected ValidationContext	vc Validation context, used to accumulate metadata validation errors discovered during parsing.
String	xmlBase The current state of xml:base.
String	xmlLang The current state of xml:lang.

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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.
String	getAbsoluteUri(String uriValue) Utility routine that combines the current state of xml:base with the specified URI to obtain an absolute URI.
Boolean	getBooleanAttribute(Attributes attrs, String attrName) Utility method to return the value of an xsd:boolean attribute.
XmlHandler	getChildHandler(QName qName, Attributes attrs, 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 Boolean	parseBooleanValue(String booleanValue) Utility method to parse provided xsd:boolean value.
void	processAttribute(QName qn, 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 String qName

This element's QName. Used for error reporting.

value

public String value

This element's text() value.

xmlLang

public String xmlLang

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

xmlBase

public 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,
                    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,
                         Attributes attrs,
                         List<XmlNamespace> namespaces)
                           throws ParseException,
                                  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.

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 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:

IOException

getAbsoluteUri

public String getAbsoluteUri(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 Boolean getBooleanAttribute(Attributes attrs,
                          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 Boolean parseBooleanValue(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.