-
- All Known Implementing Classes:
InterningXmlVisitor
,UnmarshallingContext
public interface XmlVisitor
Walks the XML document structure. Implemented by the unmarshaller and called by the API-specific connectors.Event Call Sequence
TheXmlVisitor
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 fewCharSequence
implementations that can be used as a parameter to thetext(CharSequence)
method. For example, seeBase64Data
.Error Handling
The visitor may throwSAXException
to abort the unmarshalling process in the middle.- Author:
- Kohsuke Kawaguchi
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
XmlVisitor.TextPredictor
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
endDocument()
void
endElement(TagName tagName)
void
endPrefixMapping(String prefix)
Called afterendElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName)
event to notify the end of a binding.UnmarshallingContext
getContext()
Returns theUnmarshallingContext
at the end of the chain.XmlVisitor.TextPredictor
getPredictor()
Gets the predictor that can be used for the caller to avoid callingtext(CharSequence)
unnecessarily.void
startDocument(LocatorEx locator, NamespaceContext nsContext)
Notifies a start of the document.void
startElement(TagName tagName)
Notifies a start tag of a new element.void
startPrefixMapping(String prefix, String nsUri)
Called beforestartElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName)
event to notify a new namespace binding.void
text(CharSequence pcdata)
Text events.
-
-
-
Method Detail
-
startDocument
void startDocument(LocatorEx locator, NamespaceContext nsContext) throws 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 emulatestartPrefixMapping(String, String)
correctly when unmarshalling a subtree. Connectors that use such an API can pass in additionalNamespaceContext
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:
SAXException
-
endDocument
void endDocument() throws SAXException
- Throws:
SAXException
-
startElement
void startElement(TagName tagName) throws SAXException
Notifies a start tag of a new element. namespace URIs and local names must be interned.- Throws:
SAXException
-
endElement
void endElement(TagName tagName) throws SAXException
- Throws:
SAXException
-
startPrefixMapping
void startPrefixMapping(String prefix, String nsUri) throws SAXException
Called beforestartElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName)
event to notify a new namespace binding.- Throws:
SAXException
-
endPrefixMapping
void endPrefixMapping(String prefix) throws SAXException
Called afterendElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName)
event to notify the end of a binding.- Throws:
SAXException
-
text
void text(CharSequence pcdata) throws 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 asStringBuilder
); it only needs to be fixed while this method is executing.- Throws:
SAXException
-
getContext
UnmarshallingContext getContext()
Returns theUnmarshallingContext
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 callingtext(CharSequence)
unnecessarily.
-
-