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 and Inner Type Summary

Modifier and Type	Class and Description
public static interface	XmlVisitor.TextPredictor

Method Summary

Modifier and Type	Method and Description
public void	endDocument()
public void	endElement(TagName tagName)
public void	endPrefixMapping(String prefix) Called after `endElement` event to notify the end of a binding.
public UnmarshallingContext	Returns: always return the same object, so caching the result is recommended. getContext() Returns the `UnmarshallingContext` at the end of the chain.
public XmlVisitor.TextPredictor	getPredictor() Gets the predictor that can be used for the caller to avoid calling `text(CharSequence)` unnecessarily.
public void	startDocument(LocatorEx This live object returns the location information as the parsing progresses. must not be null. locator, NamespaceContext 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.) nsContext) Notifies a start of the document.
public void	startElement(TagName tagName) Notifies a start tag of a new element.
public void	startPrefixMapping(String prefix, String nsUri) Called before `startElement` event to notify a new namespace binding.
public void	text(CharSequence represents character data. This object can be mutable (such as `StringBuilder`); it only needs to be fixed while this method is executing. pcdata) Text events.

Method Detail

endDocument	back to summary
public void endDocument() throws SAXException

endElement	back to summary
public void endElement(TagName tagName) throws SAXException

endPrefixMapping	back to summary
public void endPrefixMapping(String prefix) throws SAXException Called after `endElement` event to notify the end of a binding.

getContext back to summary

getContext	back to summary
public UnmarshallingContext getContext() Returns the `UnmarshallingContext` at the end of the chain. Returns:UnmarshallingContext always return the same object, so caching the result is recommended.

public UnmarshallingContext getContext()

Returns the UnmarshallingContext at the end of the chain.

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

getPredictor	back to summary
public XmlVisitor.TextPredictor getPredictor() Gets the predictor that can be used for the caller to avoid calling `text(CharSequence)` unnecessarily.

startDocument back to summary

startDocument	back to summary
public void startDocument(LocatorEx locator, NamespaceContext nsContext) throws SAXException Notifies a start of the document. Parameters locator:LocatorEx This live object returns the location information as the parsing progresses. must not be null. nsContext:NamespaceContext 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.)

public void startDocument(LocatorEx locator, NamespaceContext nsContext) throws SAXException

Notifies a start of the document.

Parameters

locator:LocatorEx

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

nsContext:NamespaceContext

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.)

startElement	back to summary
public void startElement(TagName tagName) throws SAXException Notifies a start tag of a new element. namespace URIs and local names must be interned.

startPrefixMapping	back to summary
public void startPrefixMapping(String prefix, String nsUri) throws SAXException Called before `startElement` event to notify a new namespace binding.

text back to summary

text	back to summary
public void text(CharSequence pcdata) throws SAXException Text events. The caller should consult `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:CharSequence represents character data. This object can be mutable (such as `StringBuilder`); it only needs to be fixed while this method is executing.

public void text(CharSequence pcdata) throws SAXException

Text events.

The caller should consult 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:CharSequence: represents character data. This object can be mutable (such as StringBuilder); it only needs to be fixed while this method is executing.

org.glassfish.jaxb.runtime.v2.runtime.unmarshaller back to summary

public Interface XmlVisitor.TextPredictor

Known Direct Implementers: org.glassfish.jaxb.runtime.v2.runtime.unmarshaller.UnmarshallingContext, org.glassfish.jaxb.runtime.v2.runtime.unmarshaller.ValidatingUnmarshaller

Method Summary

Modifier and Type	Method and Description
public boolean	expectText() Returns true if the visitor is expecting a text event as the next event.

Method Detail

expectText back to summary

expectText	back to summary
public boolean expectText() Returns true if the visitor is expecting a text event as the next event. This is primarily intended to be used for optimization to avoid buffering characters unnecessarily. If this method returns false and the connector sees whitespace it can safely skip it. If this method returns true, all the whitespaces are considered significant and thus need to be reported as a `XmlVisitor#text` event. Furthermore, if the element has no children (like `<foo/>`), then it has to be reported an empty `XmlVisitor#text` event.

public boolean expectText()

Returns true if the visitor is expecting a text event as the next event.

This is primarily intended to be used for optimization to avoid buffering characters unnecessarily. If this method returns false and the connector sees whitespace it can safely skip it.

If this method returns true, all the whitespaces are considered significant and thus need to be reported as a XmlVisitor#text event. Furthermore, if the element has no children (like <foo/>), then it has to be reported an empty XmlVisitor#text event.