com.sun.xml.bind.v2.runtime.unmarshaller
Interface XmlVisitor

All Known Implementing Classes:

InterningXmlVisitor, MTOMDecorator, UnmarshallingContext, ValidatingUnmarshaller

public interface XmlVisitor

Walks the XML document structure. Implemented by the unmarshaller and called by the API-specific connectors.

Event Call Sequence

The XmlVisitor expects the event callbacks in the following order:

 CALL SEQUENCE := startDocument ELEMENT endDocument
 ELEMENT       := startPrefixMapping ELEMENT endPrefixMapping
               |  startElement BODY endElement
 BODY          := text? (ELEMENT text?)*
 

Note in particular that text events may not be called in a row; consecutive characters (even those separated by PIs and comments) must be reported as one event, unlike SAX.

All namespace URIs, local names, and prefixes of element and attribute names must be interned. qnames need not be interned.

Typed PCDATA

For efficiency, JAXB RI defines a few CharSequence implementations that can be used as a parameter to the text(CharSequence) method. For example, see Base64Data.

Error Handling

The visitor may throw SAXException to abort the unmarshalling process in the middle.

Nested Class Summary

static interface

XmlVisitor.TextPredictor

Method Summary

void	endDocument()
void	endElement(TagName tagName)
void	endPrefixMapping(java.lang.String prefix) Called after endElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify the end of a binding.
UnmarshallingContext	getContext() Returns the UnmarshallingContext at the end of the chain.
XmlVisitor.TextPredictor	getPredictor() Gets the predictor that can be used for the caller to avoid calling text(CharSequence) unnecessarily.
void	startDocument(LocatorEx locator, javax.xml.namespace.NamespaceContext nsContext) Notifies a start of the document.
void	startElement(TagName tagName) Notifies a start tag of a new element.
void	startPrefixMapping(java.lang.String prefix, java.lang.String nsUri) Called before startElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify a new namespace binding.
void	text(java.lang.CharSequence pcdata) Text events.

Method Detail

startDocument

void startDocument(LocatorEx locator,
                   javax.xml.namespace.NamespaceContext nsContext)
                   throws org.xml.sax.SAXException

Notifies a start of the document.

Parameters:

locator - This live object returns the location information as the parsing progresses. must not be null.

nsContext - Some broken XML APIs can't iterate all the in-scope namespace bindings, which makes it impossible to emulate startPrefixMapping(String, String) correctly when unmarshalling a subtree. Connectors that use such an API can pass in additional NamespaceContext object that knows about the in-scope namespace bindings. Otherwise (and normally) it is null.

Ideally this object should be immutable and only represent the namespace URI bindings in the context (those done above the element that JAXB started unmarshalling), but it can also work even if it changes as the parsing progress (to include namespaces declared on the current element being parsed.)

Throws:

org.xml.sax.SAXException

endDocument

void endDocument()
                 throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

startElement

void startElement(TagName tagName)
                  throws org.xml.sax.SAXException

Notifies a start tag of a new element. namespace URIs and local names must be interned.

Throws:

org.xml.sax.SAXException

endElement

void endElement(TagName tagName)
                throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

startPrefixMapping

void startPrefixMapping(java.lang.String prefix,
                        java.lang.String nsUri)
                        throws org.xml.sax.SAXException

Called before startElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify a new namespace binding.

Throws:

org.xml.sax.SAXException

endPrefixMapping

void endPrefixMapping(java.lang.String prefix)
                      throws org.xml.sax.SAXException

Called after endElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify the end of a binding.

Throws:

org.xml.sax.SAXException

text

void text(java.lang.CharSequence pcdata)
          throws org.xml.sax.SAXException

Text events.

The caller should consult XmlVisitor.TextPredictor to see if the unmarshaller is expecting any PCDATA. If the above is returning false, the caller is OK to skip any text in XML. The net effect is that we can ignore whitespaces quickly.

Parameters:

pcdata - represents character data. This object can be mutable (such as StringBuilder); it only needs to be fixed while this method is executing.

Throws:

org.xml.sax.SAXException

getContext

UnmarshallingContext getContext()

Returns the UnmarshallingContext at the end of the chain.

Returns:

always return the same object, so caching the result is recommended.

getPredictor

XmlVisitor.TextPredictor getPredictor()

Gets the predictor that can be used for the caller to avoid calling text(CharSequence) unnecessarily.