1 /* 2 * Copyright (c) 1998, 2015, 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.dtdparser; 27 28 import org.xml.sax.Locator; 29 import org.xml.sax.SAXException; 30 import org.xml.sax.SAXParseException; 31 32 import java.util.EventListener; 33 34 /** 35 * All DTD parsing events are signaled through this interface. 36 */ 37 public interface DTDEventListener extends EventListener { 38 39 public void setDocumentLocator(Locator loc); 40 41 /** 42 * Receive notification of a Processing Instruction. 43 * Processing instructions contain information meaningful 44 * to the application. 45 * 46 * @param target The target of the proceessing instruction 47 * which should have meaning to the application. 48 * @param data The instruction itself which should contain 49 * valid XML characters. 50 * @throws SAXException 51 */ 52 public void processingInstruction(String target, String data) 53 throws SAXException; 54 55 /** 56 * Receive notification of a Notation Declaration. 57 * Notation declarations are used by elements and entities 58 * for identifying embedded non-XML data. 59 * 60 * @param name The notation name, referred to by entities and 61 * elements. 62 * @param publicId The public identifier 63 * @param systemId The system identifier 64 */ 65 public void notationDecl(String name, String publicId, String systemId) 66 throws SAXException; 67 68 /** 69 * Receive notification of an unparsed entity declaration. 70 * Unparsed entities are non-XML data. 71 * 72 * @param name The name of the unparsed entity. 73 * @param publicId The public identifier 74 * @param systemId The system identifier 75 * @param notationName The associated notation 76 */ 77 public void unparsedEntityDecl(String name, String publicId, 78 String systemId, String notationName) 79 throws SAXException; 80 81 /** 82 * Receive notification of a internal general entity declaration event. 83 * 84 * @param name The internal general entity name. 85 * @param value The value of the entity, which may include unexpanded 86 * entity references. Character references will have been 87 * expanded. 88 * @throws SAXException 89 * @see #externalGeneralEntityDecl(String, String, String) 90 */ 91 public void internalGeneralEntityDecl(String name, String value) 92 throws SAXException; 93 94 /** 95 * Receive notification of an external parsed general entity 96 * declaration event. 97 * <p> 98 * <p>If a system identifier is present, and it is a relative URL, the 99 * parser will have resolved it fully before passing it through this 100 * method to a listener.</p> 101 * 102 * @param name The entity name. 103 * @param publicId The entity's public identifier, or null if 104 * none was given. 105 * @param systemId The entity's system identifier. 106 * @throws SAXException 107 * @see #unparsedEntityDecl(String, String, String, String) 108 */ 109 public void externalGeneralEntityDecl(String name, String publicId, 110 String systemId) 111 throws SAXException; 112 113 /** 114 * Receive notification of a internal parameter entity declaration 115 * event. 116 * 117 * @param name The internal parameter entity name. 118 * @param value The value of the entity, which may include unexpanded 119 * entity references. Character references will have been 120 * expanded. 121 * @throws SAXException 122 * @see #externalParameterEntityDecl(String, String, String) 123 */ 124 public void internalParameterEntityDecl(String name, String value) 125 throws SAXException; 126 127 /** 128 * Receive notification of an external parameter entity declaration 129 * event. 130 * <p> 131 * <p>If a system identifier is present, and it is a relative URL, the 132 * parser will have resolved it fully before passing it through this 133 * method to a listener.</p> 134 * 135 * @param name The parameter entity name. 136 * @param publicId The entity's public identifier, or null if 137 * none was given. 138 * @param systemId The entity's system identifier. 139 * @throws SAXException 140 * @see #unparsedEntityDecl(String, String, String, String) 141 */ 142 public void externalParameterEntityDecl(String name, String publicId, 143 String systemId) 144 throws SAXException; 145 146 /** 147 * Receive notification of the beginning of the DTD. 148 * 149 * @param in Current input entity. 150 * @see #endDTD() 151 */ 152 public void startDTD(InputEntity in) 153 throws SAXException; 154 155 /** 156 * Receive notification of the end of a DTD. The parser will invoke 157 * this method only once. 158 * 159 * @throws SAXException 160 * @see #startDTD(InputEntity) 161 */ 162 public void endDTD() 163 throws SAXException; 164 165 /** 166 * Receive notification that a comment has been read. 167 * <p> 168 * <P> Note that processing instructions are the mechanism designed 169 * to hold information for consumption by applications, not comments. 170 * XML systems may rely on applications being able to access information 171 * found in processing instructions; this is not true of comments, which 172 * are typically discarded. 173 * 174 * @param text the text within the comment delimiters. 175 * @throws SAXException 176 */ 177 public void comment(String text) 178 throws SAXException; 179 180 /** 181 * Receive notification of character data. 182 * <p> 183 * <p>The Parser will call this method to report each chunk of 184 * character data. SAX parsers may return all contiguous character 185 * data in a single chunk, or they may split it into several 186 * chunks; however, all of the characters in any single event 187 * must come from the same external entity, so that the Locator 188 * provides useful information.</p> 189 * <p> 190 * <p>The application must not attempt to read from the array 191 * outside of the specified range.</p> 192 * <p> 193 * <p>Note that some parsers will report whitespace using the 194 * ignorableWhitespace() method rather than this one (validating 195 * parsers must do so).</p> 196 * 197 * @param ch The characters from the DTD. 198 * @param start The start position in the array. 199 * @param length The number of characters to read from the array. 200 * @throws SAXException 201 * @see #ignorableWhitespace(char[], int, int) 202 */ 203 public void characters(char ch[], int start, int length) 204 throws SAXException; 205 206 207 /** 208 * Receive notification of ignorable whitespace in element content. 209 * <p> 210 * <p>Validating Parsers must use this method to report each chunk 211 * of ignorable whitespace (see the W3C XML 1.0 recommendation, 212 * section 2.10): non-validating parsers may also use this method 213 * if they are capable of parsing and using content models.</p> 214 * <p> 215 * <p>SAX parsers may return all contiguous whitespace in a single 216 * chunk, or they may split it into several chunks; however, all of 217 * the characters in any single event must come from the same 218 * external entity, so that the Locator provides useful 219 * information.</p> 220 * <p> 221 * <p>The application must not attempt to read from the array 222 * outside of the specified range.</p> 223 * 224 * @param ch The characters from the DTD. 225 * @param start The start position in the array. 226 * @param length The number of characters to read from the array. 227 * @throws SAXException 228 * @see #characters(char[], int, int) 229 */ 230 public void ignorableWhitespace(char ch[], int start, int length) 231 throws SAXException; 232 233 /** 234 * Receive notification that a CDATA section is beginning. Data in a 235 * CDATA section is is reported through the appropriate event, either 236 * <em>characters()</em> or <em>ignorableWhitespace</em>. 237 * 238 * @throws SAXException 239 * @see #endCDATA() 240 */ 241 public void startCDATA() throws SAXException; 242 243 244 /** 245 * Receive notification that the CDATA section finished. 246 * 247 * @throws SAXException 248 * @see #startCDATA() 249 */ 250 public void endCDATA() throws SAXException; 251 252 253 public void fatalError(SAXParseException e) 254 throws SAXException; 255 256 public void error(SAXParseException e) throws SAXException; 257 258 public void warning(SAXParseException err) throws SAXException; 259 260 public final short CONTENT_MODEL_EMPTY = 0; 261 public final short CONTENT_MODEL_ANY = 1; 262 public final short CONTENT_MODEL_MIXED = 2; 263 public final short CONTENT_MODEL_CHILDREN = 3; 264 265 /** 266 * receives notification that parsing of content model is beginning. 267 * 268 * @param elementName name of the element whose content model is going to be defined. 269 * @param contentModelType {@link #CONTENT_MODEL_EMPTY} 270 * this element has EMPTY content model. This notification 271 * will be immediately followed by the corresponding endContentModel. 272 * {@link #CONTENT_MODEL_ANY} 273 * this element has ANY content model. This notification 274 * will be immediately followed by the corresponding endContentModel. 275 * {@link #CONTENT_MODEL_MIXED} 276 * this element has mixed content model. #PCDATA will not be reported. 277 * each child element will be reported by mixedElement method. 278 * {@link #CONTENT_MODEL_CHILDREN} 279 * this elemen has child content model. The actual content model will 280 * be reported by childElement, startModelGroup, endModelGroup, and 281 * connector methods. Possible call sequences are: 282 * <p> 283 * START := MODEL_GROUP 284 * MODEL_GROUP := startModelGroup TOKEN (connector TOKEN)* endModelGroup 285 * TOKEN := childElement 286 * | MODEL_GROUP 287 */ 288 public void startContentModel(String elementName, short contentModelType) throws SAXException; 289 290 /** 291 * receives notification that parsing of content model is finished. 292 */ 293 public void endContentModel(String elementName, short contentModelType) throws SAXException; 294 295 public final short USE_NORMAL = 0; 296 public final short USE_IMPLIED = 1; 297 public final short USE_FIXED = 2; 298 public final short USE_REQUIRED = 3; 299 300 /** 301 * For each entry in an ATTLIST declaration, 302 * this event will be fired. 303 * <p> 304 * <p> 305 * DTD allows the same attributes to be declared more than 306 * once, and in that case the first one wins. I think 307 * this method will be only fired for the first one, 308 * but I need to check. 309 */ 310 public void attributeDecl(String elementName, String attributeName, String attributeType, 311 String[] enumeration, short attributeUse, String defaultValue) throws SAXException; 312 313 public void childElement(String elementName, short occurence) throws SAXException; 314 315 /** 316 * receives notification of child element of mixed content model. 317 * this method is called for each child element. 318 * 319 * @see #startContentModel(String, short) 320 */ 321 public void mixedElement(String elementName) throws SAXException; 322 323 public void startModelGroup() throws SAXException; 324 325 public void endModelGroup(short occurence) throws SAXException; 326 327 public final short CHOICE = 0; 328 public final short SEQUENCE = 1; 329 330 /** 331 * Connectors in one model group is guaranteed to be the same. 332 * <p> 333 * <p> 334 * IOW, you'll never see an event sequence like (a|b,c) 335 */ 336 public void connector(short connectorType) throws SAXException; 337 338 public final short OCCURENCE_ZERO_OR_MORE = 0; 339 public final short OCCURENCE_ONE_OR_MORE = 1; 340 public final short OCCURENCE_ZERO_OR_ONE = 2; 341 public final short OCCURENCE_ONCE = 3; 342 }