1 /* 2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.xml.internal.bind.v2.runtime.unmarshaller; 27 28 import javax.xml.namespace.NamespaceContext; 29 30 import org.xml.sax.SAXException; 31 32 /** 33 * Walks the XML document structure. 34 * 35 * Implemented by the unmarshaller and called by the API-specific connectors. 36 * 37 * <h2>Event Call Sequence</h2> 38 * 39 * The {@link XmlVisitor} expects the event callbacks in the following order: 40 * <pre> 41 * CALL SEQUENCE := startDocument ELEMENT endDocument 42 * ELEMENT := startPrefixMapping ELEMENT endPrefixMapping 43 * | startElement BODY endElement 44 * BODY := text? (ELEMENT text?)* 45 * </pre> 46 * Note in particular that text events may not be called in a row; 47 * consecutive characters (even those separated by PIs and comments) 48 * must be reported as one event, unlike SAX. 49 * 50 * <p> 51 * All namespace URIs, local names, and prefixes of element and attribute 52 * names must be interned. qnames need not be interned. 53 * 54 * 55 * <h2>Typed PCDATA</h2> 56 * For efficiency, JAXB RI defines a few {@link CharSequence} implementations 57 * that can be used as a parameter to the {@link #text(CharSequence)} method. 58 * For example, see {@link Base64Data}. 59 * 60 * <h2>Error Handling</h2> 61 * The visitor may throw {@link SAXException} to abort the unmarshalling process 62 * in the middle. 63 * 64 * @author Kohsuke Kawaguchi 65 */ 66 public interface XmlVisitor { 67 /** 68 * Notifies a start of the document. 69 * 70 * @param locator 71 * This live object returns the location information as the parsing progresses. 72 * must not be null. 73 * @param nsContext 74 * Some broken XML APIs can't iterate all the in-scope namespace bindings, 75 * which makes it impossible to emulate {@link #startPrefixMapping(String, String)} correctly 76 * when unmarshalling a subtree. Connectors that use such an API can 77 * pass in additional {@link NamespaceContext} object that knows about the 78 * in-scope namespace bindings. Otherwise (and normally) it is null. 79 * 80 * <p> 81 * Ideally this object should be immutable and only represent the namespace URI bindings 82 * in the context (those done above the element that JAXB started unmarshalling), 83 * but it can also work even if it changes as the parsing progress (to include 84 * namespaces declared on the current element being parsed.) 85 */ 86 void startDocument(LocatorEx locator, NamespaceContext nsContext) throws SAXException; 87 void endDocument() throws SAXException; 88 89 /** 90 * Notifies a start tag of a new element. 91 * 92 * namespace URIs and local names must be interned. 93 */ 94 void startElement(TagName tagName) throws SAXException; 95 void endElement(TagName tagName) throws SAXException; 96 97 /** 98 * Called before {@link #startElement} event to notify a new namespace binding. 99 */ 100 void startPrefixMapping( String prefix, String nsUri ) throws SAXException; 101 /** 102 * Called after {@link #endElement} event to notify the end of a binding. 103 */ 104 void endPrefixMapping( String prefix ) throws SAXException; 105 106 /** 107 * Text events. 108 * 109 * <p> 110 * The caller should consult {@link TextPredictor} to see 111 * if the unmarshaller is expecting any PCDATA. If the above is returning 112 * false, the caller is OK to skip any text in XML. The net effect is 113 * that we can ignore whitespaces quickly. 114 * 115 * @param pcdata 116 * represents character data. This object can be mutable 117 * (such as {@link StringBuilder}); it only needs to be fixed 118 * while this method is executing. 119 */ 120 void text( CharSequence pcdata ) throws SAXException; 121 122 /** 123 * Returns the {@link UnmarshallingContext} at the end of the chain. 124 * 125 * @return 126 * always return the same object, so caching the result is recommended. 127 */ 128 UnmarshallingContext getContext(); 129 130 /** 131 * Gets the predictor that can be used for the caller to avoid 132 * calling {@link #text(CharSequence)} unnecessarily. 133 */ 134 TextPredictor getPredictor(); 135 136 interface TextPredictor { 137 /** 138 * Returns true if the visitor is expecting a text event as the next event. 139 * 140 * <p> 141 * This is primarily intended to be used for optimization to avoid buffering 142 * characters unnecessarily. If this method returns false and the connector 143 * sees whitespace it can safely skip it. 144 * 145 * <p> 146 * If this method returns true, all the whitespaces are considered significant 147 * and thus need to be reported as a {@link XmlVisitor#text} event. Furthermore, 148 * if the element has no children (like <foo/>), then it has to be reported 149 * an empty {@link XmlVisitor#text} event. 150 */ 151 boolean expectText(); 152 } 153 }