1 /* 2 * reserved comment block 3 * DO NOT REMOVE OR ALTER! 4 */ 5 /* 6 * Licensed to the Apache Software Foundation (ASF) under one or more 7 * contributor license agreements. See the NOTICE file distributed with 8 * this work for additional information regarding copyright ownership. 9 * The ASF licenses this file to You under the Apache License, Version 2.0 10 * (the "License"); you may not use this file except in compliance with 11 * the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, 17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 */ 21 22 package com.sun.org.apache.xerces.internal.xni; 23 24 import com.sun.org.apache.xerces.internal.xni.parser.XMLDocumentSource; 25 26 /** 27 * The document handler interface defines callback methods to report 28 * information items in XML documents. Parser components interested in 29 * document information implement this interface and are registered 30 * as the document handler on the document source. 31 * 32 * @author Andy Clark, IBM 33 * 34 */ 35 public interface XMLDocumentHandler { 36 37 // 38 // XMLDocumentHandler methods 39 // 40 41 /** 42 * The start of the document. 43 * 44 * @param locator The document locator, or null if the document 45 * location cannot be reported during the parsing 46 * of this document. However, it is <em>strongly</em> 47 * recommended that a locator be supplied that can 48 * at least report the system identifier of the 49 * document. 50 * @param encoding The auto-detected IANA encoding name of the entity 51 * stream. This value will be null in those situations 52 * where the entity encoding is not auto-detected (e.g. 53 * internal entities or a document entity that is 54 * parsed from a java.io.Reader). 55 * @param namespaceContext 56 * The namespace context in effect at the 57 * start of this document. 58 * This object represents the current context. 59 * Implementors of this class are responsible 60 * for copying the namespace bindings from the 61 * the current context (and its parent contexts) 62 * if that information is important. 63 * 64 * @param augs Additional information that may include infoset augmentations 65 * @exception XNIException 66 * Thrown by handler to signal an error. 67 */ startDocument(XMLLocator locator, String encoding, NamespaceContext namespaceContext, Augmentations augs)68 public void startDocument(XMLLocator locator, String encoding, 69 NamespaceContext namespaceContext, 70 Augmentations augs) 71 throws XNIException; 72 73 /** 74 * Notifies of the presence of an XMLDecl line in the document. If 75 * present, this method will be called immediately following the 76 * startDocument call. 77 * 78 * @param version The XML version. 79 * @param encoding The IANA encoding name of the document, or null if 80 * not specified. 81 * @param standalone The standalone value, or null if not specified. 82 * @param augs Additional information that may include infoset augmentations 83 * 84 * @exception XNIException 85 * Thrown by handler to signal an error. 86 */ xmlDecl(String version, String encoding, String standalone, Augmentations augs)87 public void xmlDecl(String version, String encoding, String standalone, Augmentations augs) 88 throws XNIException; 89 90 /** 91 * Notifies of the presence of the DOCTYPE line in the document. 92 * 93 * @param rootElement 94 * The name of the root element. 95 * @param publicId The public identifier if an external DTD or null 96 * if the external DTD is specified using SYSTEM. 97 * @param systemId The system identifier if an external DTD, null 98 * otherwise. 99 * @param augs Additional information that may include infoset augmentations 100 * 101 * @exception XNIException 102 * Thrown by handler to signal an error. 103 */ doctypeDecl(String rootElement, String publicId, String systemId, Augmentations augs)104 public void doctypeDecl(String rootElement, String publicId, String systemId, Augmentations augs) 105 throws XNIException; 106 107 /** 108 * A comment. 109 * 110 * @param text The text in the comment. 111 * @param augs Additional information that may include infoset augmentations 112 * 113 * @exception XNIException 114 * Thrown by application to signal an error. 115 */ comment(XMLString text, Augmentations augs)116 public void comment(XMLString text, Augmentations augs) throws XNIException; 117 118 /** 119 * A processing instruction. Processing instructions consist of a 120 * target name and, optionally, text data. The data is only meaningful 121 * to the application. 122 * <p> 123 * Typically, a processing instruction's data will contain a series 124 * of pseudo-attributes. These pseudo-attributes follow the form of 125 * element attributes but are <strong>not</strong> parsed or presented 126 * to the application as anything other than text. The application is 127 * responsible for parsing the data. 128 * 129 * @param target The target. 130 * @param data The data or null if none specified. 131 * @param augs Additional information that may include infoset augmentations 132 * 133 * @exception XNIException 134 * Thrown by handler to signal an error. 135 */ processingInstruction(String target, XMLString data, Augmentations augs)136 public void processingInstruction(String target, XMLString data, Augmentations augs) 137 throws XNIException; 138 139 /** 140 * The start of an element. 141 * 142 * @param element The name of the element. 143 * @param attributes The element attributes. 144 * @param augs Additional information that may include infoset augmentations 145 * 146 * @exception XNIException 147 * Thrown by handler to signal an error. 148 */ startElement(QName element, XMLAttributes attributes, Augmentations augs)149 public void startElement(QName element, XMLAttributes attributes, Augmentations augs) 150 throws XNIException; 151 152 /** 153 * An empty element. 154 * 155 * @param element The name of the element. 156 * @param attributes The element attributes. 157 * @param augs Additional information that may include infoset augmentations 158 * 159 * @exception XNIException 160 * Thrown by handler to signal an error. 161 */ emptyElement(QName element, XMLAttributes attributes, Augmentations augs)162 public void emptyElement(QName element, XMLAttributes attributes, Augmentations augs) 163 throws XNIException; 164 165 /** 166 * This method notifies the start of a general entity. 167 * <p> 168 * <strong>Note:</strong> This method is not called for entity references 169 * appearing as part of attribute values. 170 * 171 * @param name The name of the general entity. 172 * @param identifier The resource identifier. 173 * @param encoding The auto-detected IANA encoding name of the entity 174 * stream. This value will be null in those situations 175 * where the entity encoding is not auto-detected (e.g. 176 * internal entities or a document entity that is 177 * parsed from a java.io.Reader). 178 * @param augs Additional information that may include infoset augmentations 179 * 180 * @exception XNIException Thrown by handler to signal an error. 181 */ startGeneralEntity(String name, XMLResourceIdentifier identifier, String encoding, Augmentations augs)182 public void startGeneralEntity(String name, 183 XMLResourceIdentifier identifier, 184 String encoding, 185 Augmentations augs) throws XNIException; 186 187 /** 188 * Notifies of the presence of a TextDecl line in an entity. If present, 189 * this method will be called immediately following the startEntity call. 190 * <p> 191 * <strong>Note:</strong> This method will never be called for the 192 * document entity; it is only called for external general entities 193 * referenced in document content. 194 * <p> 195 * <strong>Note:</strong> This method is not called for entity references 196 * appearing as part of attribute values. 197 * 198 * @param version The XML version, or null if not specified. 199 * @param encoding The IANA encoding name of the entity. 200 * @param augs Additional information that may include infoset augmentations 201 * 202 * @exception XNIException 203 * Thrown by handler to signal an error. 204 */ textDecl(String version, String encoding, Augmentations augs)205 public void textDecl(String version, String encoding, Augmentations augs) throws XNIException; 206 207 /** 208 * This method notifies the end of a general entity. 209 * <p> 210 * <strong>Note:</strong> This method is not called for entity references 211 * appearing as part of attribute values. 212 * 213 * @param name The name of the entity. 214 * @param augs Additional information that may include infoset augmentations 215 * 216 * @exception XNIException 217 * Thrown by handler to signal an error. 218 */ endGeneralEntity(String name, Augmentations augs)219 public void endGeneralEntity(String name, Augmentations augs) throws XNIException; 220 221 /** 222 * Character content. 223 * 224 * @param text The content. 225 * @param augs Additional information that may include infoset augmentations 226 * 227 * @exception XNIException 228 * Thrown by handler to signal an error. 229 */ characters(XMLString text, Augmentations augs)230 public void characters(XMLString text, Augmentations augs) throws XNIException; 231 232 /** 233 * Ignorable whitespace. For this method to be called, the document 234 * source must have some way of determining that the text containing 235 * only whitespace characters should be considered ignorable. For 236 * example, the validator can determine if a length of whitespace 237 * characters in the document are ignorable based on the element 238 * content model. 239 * 240 * @param text The ignorable whitespace. 241 * @param augs Additional information that may include infoset augmentations 242 * 243 * @exception XNIException 244 * Thrown by handler to signal an error. 245 */ ignorableWhitespace(XMLString text, Augmentations augs)246 public void ignorableWhitespace(XMLString text, Augmentations augs) throws XNIException; 247 248 /** 249 * The end of an element. 250 * 251 * @param element The name of the element. 252 * @param augs Additional information that may include infoset augmentations 253 * 254 * @exception XNIException 255 * Thrown by handler to signal an error. 256 */ endElement(QName element, Augmentations augs)257 public void endElement(QName element, Augmentations augs) throws XNIException; 258 259 /** 260 * The start of a CDATA section. 261 * 262 * @param augs Additional information that may include infoset augmentations 263 * 264 * @exception XNIException 265 * Thrown by handler to signal an error. 266 */ startCDATA(Augmentations augs)267 public void startCDATA(Augmentations augs) throws XNIException; 268 269 /** 270 * The end of a CDATA section. 271 * 272 * @param augs Additional information that may include infoset augmentations 273 * 274 * @exception XNIException 275 * Thrown by handler to signal an error. 276 */ endCDATA(Augmentations augs)277 public void endCDATA(Augmentations augs) throws XNIException; 278 279 /** 280 * The end of the document. 281 * 282 * @param augs Additional information that may include infoset augmentations 283 * 284 * @exception XNIException 285 * Thrown by handler to signal an error. 286 */ endDocument(Augmentations augs)287 public void endDocument(Augmentations augs) throws XNIException; 288 289 290 /** Sets the document source. */ setDocumentSource(XMLDocumentSource source)291 public void setDocumentSource(XMLDocumentSource source); 292 293 294 /** Returns the document source. */ getDocumentSource()295 public XMLDocumentSource getDocumentSource(); 296 297 } // interface XMLDocumentHandler 298