aoqi@0: * CALL SEQUENCE := startDocument ELEMENT endDocument aoqi@0: * ELEMENT := startPrefixMapping ELEMENT endPrefixMapping aoqi@0: * | startElement BODY endElement aoqi@0: * BODY := text? (ELEMENT text?)* aoqi@0: *aoqi@0: * Note in particular that text events may not be called in a row; aoqi@0: * consecutive characters (even those separated by PIs and comments) aoqi@0: * must be reported as one event, unlike SAX. aoqi@0: * aoqi@0: *
aoqi@0: * All namespace URIs, local names, and prefixes of element and attribute aoqi@0: * names must be interned. qnames need not be interned. aoqi@0: * aoqi@0: * aoqi@0: *
aoqi@0: * Ideally this object should be immutable and only represent the namespace URI bindings aoqi@0: * in the context (those done above the element that JAXB started unmarshalling), aoqi@0: * but it can also work even if it changes as the parsing progress (to include aoqi@0: * namespaces declared on the current element being parsed.) aoqi@0: */ aoqi@0: void startDocument(LocatorEx locator, NamespaceContext nsContext) throws SAXException; aoqi@0: void endDocument() throws SAXException; aoqi@0: aoqi@0: /** aoqi@0: * Notifies a start tag of a new element. aoqi@0: * aoqi@0: * namespace URIs and local names must be interned. aoqi@0: */ aoqi@0: void startElement(TagName tagName) throws SAXException; aoqi@0: void endElement(TagName tagName) throws SAXException; aoqi@0: aoqi@0: /** aoqi@0: * Called before {@link #startElement} event to notify a new namespace binding. aoqi@0: */ aoqi@0: void startPrefixMapping( String prefix, String nsUri ) throws SAXException; aoqi@0: /** aoqi@0: * Called after {@link #endElement} event to notify the end of a binding. aoqi@0: */ aoqi@0: void endPrefixMapping( String prefix ) throws SAXException; aoqi@0: aoqi@0: /** aoqi@0: * Text events. aoqi@0: * aoqi@0: *
aoqi@0: * The caller should consult {@link TextPredictor} to see aoqi@0: * if the unmarshaller is expecting any PCDATA. If the above is returning aoqi@0: * false, the caller is OK to skip any text in XML. The net effect is aoqi@0: * that we can ignore whitespaces quickly. aoqi@0: * aoqi@0: * @param pcdata aoqi@0: * represents character data. This object can be mutable aoqi@0: * (such as {@link StringBuilder}); it only needs to be fixed aoqi@0: * while this method is executing. aoqi@0: */ aoqi@0: void text( CharSequence pcdata ) throws SAXException; aoqi@0: aoqi@0: /** aoqi@0: * Returns the {@link UnmarshallingContext} at the end of the chain. aoqi@0: * aoqi@0: * @return aoqi@0: * always return the same object, so caching the result is recommended. aoqi@0: */ aoqi@0: UnmarshallingContext getContext(); aoqi@0: aoqi@0: /** aoqi@0: * Gets the predictor that can be used for the caller to avoid aoqi@0: * calling {@link #text(CharSequence)} unnecessarily. aoqi@0: */ aoqi@0: TextPredictor getPredictor(); aoqi@0: aoqi@0: interface TextPredictor { aoqi@0: /** aoqi@0: * Returns true if the visitor is expecting a text event as the next event. aoqi@0: * aoqi@0: *
aoqi@0: * This is primarily intended to be used for optimization to avoid buffering aoqi@0: * characters unnecessarily. If this method returns false and the connector aoqi@0: * sees whitespace it can safely skip it. aoqi@0: * aoqi@0: *
aoqi@0: * If this method returns true, all the whitespaces are considered significant aoqi@0: * and thus need to be reported as a {@link XmlVisitor#text} event. Furthermore, aoqi@0: * if the element has no children (like <foo/>), then it has to be reported aoqi@0: * an empty {@link XmlVisitor#text} event. aoqi@0: */ aoqi@0: boolean expectText(); aoqi@0: } aoqi@0: }