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 22package com.sun.org.apache.xerces.internal.xni; 23 24import com.sun.org.apache.xerces.internal.xni.parser.XMLDTDSource; 25 26/** 27 * The DTD handler interface defines callback methods to report 28 * information items in the DTD of an XML document. Parser components 29 * interested in DTD information implement this interface and are 30 * registered as the DTD handler on the DTD source. 31 * 32 * @see XMLDTDContentModelHandler 33 * 34 * @author Andy Clark, IBM 35 * 36 */ 37public interface XMLDTDHandler { 38 39 // 40 // Constants 41 // 42 43 /** 44 * Conditional section: INCLUDE. 45 * 46 * @see #CONDITIONAL_IGNORE 47 */ 48 public static final short CONDITIONAL_INCLUDE = 0; 49 50 /** 51 * Conditional section: IGNORE. 52 * 53 * @see #CONDITIONAL_INCLUDE 54 */ 55 public static final short CONDITIONAL_IGNORE = 1; 56 57 // 58 // XMLDTDHandler methods 59 // 60 61 /** 62 * The start of the DTD. 63 * 64 * @param locator The document locator, or null if the document 65 * location cannot be reported during the parsing of 66 * the document DTD. However, it is <em>strongly</em> 67 * recommended that a locator be supplied that can 68 * at least report the base system identifier of the 69 * DTD. 70 * @param augmentations Additional information that may include infoset 71 * augmentations. 72 * 73 * @throws XNIException Thrown by handler to signal an error. 74 */ 75 public void startDTD(XMLLocator locator, Augmentations augmentations) 76 throws XNIException; 77 78 /** 79 * This method notifies of the start of a parameter entity. The parameter 80 * entity name start with a '%' character. 81 * 82 * @param name The name of the parameter entity. 83 * @param identifier The resource identifier. 84 * @param encoding The auto-detected IANA encoding name of the entity 85 * stream. This value will be null in those situations 86 * where the entity encoding is not auto-detected (e.g. 87 * internal parameter entities). 88 * @param augmentations Additional information that may include infoset 89 * augmentations. 90 * 91 * @throws XNIException Thrown by handler to signal an error. 92 */ 93 public void startParameterEntity(String name, 94 XMLResourceIdentifier identifier, 95 String encoding, 96 Augmentations augmentations) throws XNIException; 97 98 /** 99 * Notifies of the presence of a TextDecl line in an entity. If present, 100 * this method will be called immediately following the startEntity call. 101 * <p> 102 * <strong>Note:</strong> This method is only called for external 103 * parameter entities referenced in the DTD. 104 * 105 * @param version The XML version, or null if not specified. 106 * @param encoding The IANA encoding name of the entity. 107 * @param augmentations Additional information that may include infoset 108 * augmentations. 109 * 110 * @throws XNIException Thrown by handler to signal an error. 111 */ 112 public void textDecl(String version, String encoding, 113 Augmentations augmentations) throws XNIException; 114 115 /** 116 * This method notifies the end of a parameter entity. Parameter entity 117 * names begin with a '%' character. 118 * 119 * @param name The name of the parameter entity. 120 * @param augmentations Additional information that may include infoset 121 * augmentations. 122 * 123 * @throws XNIException Thrown by handler to signal an error. 124 */ 125 public void endParameterEntity(String name, Augmentations augmentations) 126 throws XNIException; 127 128 /** 129 * The start of the DTD external subset. 130 * 131 * @param identifier The resource identifier. 132 * @param augmentations 133 * Additional information that may include infoset 134 * augmentations. 135 * @exception XNIException 136 * Thrown by handler to signal an error. 137 */ 138 public void startExternalSubset(XMLResourceIdentifier identifier, 139 Augmentations augmentations) 140 throws XNIException; 141 142 /** 143 * The end of the DTD external subset. 144 * 145 * @param augmentations Additional information that may include infoset 146 * augmentations. 147 * 148 * @throws XNIException Thrown by handler to signal an error. 149 */ 150 public void endExternalSubset(Augmentations augmentations) 151 throws XNIException; 152 153 /** 154 * A comment. 155 * 156 * @param text The text in the comment. 157 * @param augmentations Additional information that may include infoset 158 * augmentations. 159 * 160 * @throws XNIException Thrown by application to signal an error. 161 */ 162 public void comment(XMLString text, Augmentations augmentations) 163 throws XNIException; 164 165 /** 166 * A processing instruction. Processing instructions consist of a 167 * target name and, optionally, text data. The data is only meaningful 168 * to the application. 169 * <p> 170 * Typically, a processing instruction's data will contain a series 171 * of pseudo-attributes. These pseudo-attributes follow the form of 172 * element attributes but are <strong>not</strong> parsed or presented 173 * to the application as anything other than text. The application is 174 * responsible for parsing the data. 175 * 176 * @param target The target. 177 * @param data The data or null if none specified. 178 * @param augmentations Additional information that may include infoset 179 * augmentations. 180 * 181 * @throws XNIException Thrown by handler to signal an error. 182 */ 183 public void processingInstruction(String target, XMLString data, 184 Augmentations augmentations) 185 throws XNIException; 186 187 /** 188 * An element declaration. 189 * 190 * @param name The name of the element. 191 * @param contentModel The element content model. 192 * @param augmentations Additional information that may include infoset 193 * augmentations. 194 * 195 * @throws XNIException Thrown by handler to signal an error. 196 */ 197 public void elementDecl(String name, String contentModel, 198 Augmentations augmentations) 199 throws XNIException; 200 201 /** 202 * The start of an attribute list. 203 * 204 * @param elementName The name of the element that this attribute 205 * list is associated with. 206 * @param augmentations Additional information that may include infoset 207 * augmentations. 208 * 209 * @throws XNIException Thrown by handler to signal an error. 210 */ 211 public void startAttlist(String elementName, 212 Augmentations augmentations) throws XNIException; 213 214 /** 215 * An attribute declaration. 216 * 217 * @param elementName The name of the element that this attribute 218 * is associated with. 219 * @param attributeName The name of the attribute. 220 * @param type The attribute type. This value will be one of 221 * the following: "CDATA", "ENTITY", "ENTITIES", 222 * "ENUMERATION", "ID", "IDREF", "IDREFS", 223 * "NMTOKEN", "NMTOKENS", or "NOTATION". 224 * @param enumeration If the type has the value "ENUMERATION" or 225 * "NOTATION", this array holds the allowed attribute 226 * values; otherwise, this array is null. 227 * @param defaultType The attribute default type. This value will be 228 * one of the following: "#FIXED", "#IMPLIED", 229 * "#REQUIRED", or null. 230 * @param defaultValue The attribute default value, or null if no 231 * default value is specified. 232 * @param nonNormalizedDefaultValue The attribute default value with no normalization 233 * performed, or null if no default value is specified. 234 * @param augmentations Additional information that may include infoset 235 * augmentations. 236 * 237 * @throws XNIException Thrown by handler to signal an error. 238 */ 239 public void attributeDecl(String elementName, String attributeName, 240 String type, String[] enumeration, 241 String defaultType, XMLString defaultValue, 242 XMLString nonNormalizedDefaultValue, Augmentations augmentations) 243 throws XNIException; 244 245 /** 246 * The end of an attribute list. 247 * 248 * @param augmentations Additional information that may include infoset 249 * augmentations. 250 * 251 * @throws XNIException Thrown by handler to signal an error. 252 */ 253 public void endAttlist(Augmentations augmentations) throws XNIException; 254 255 /** 256 * An internal entity declaration. 257 * 258 * @param name The name of the entity. Parameter entity names start with 259 * '%', whereas the name of a general entity is just the 260 * entity name. 261 * @param text The value of the entity. 262 * @param nonNormalizedText The non-normalized value of the entity. This 263 * value contains the same sequence of characters that was in 264 * the internal entity declaration, without any entity 265 * references expanded. 266 * @param augmentations Additional information that may include infoset 267 * augmentations. 268 * 269 * @throws XNIException Thrown by handler to signal an error. 270 */ 271 public void internalEntityDecl(String name, XMLString text, 272 XMLString nonNormalizedText, 273 Augmentations augmentations) 274 throws XNIException; 275 276 /** 277 * An external entity declaration. 278 * 279 * @param name The name of the entity. Parameter entity names start 280 * with '%', whereas the name of a general entity is just 281 * the entity name. 282 * @param identifier An object containing all location information 283 * pertinent to this external entity. 284 * @param augmentations Additional information that may include infoset 285 * augmentations. 286 * 287 * @throws XNIException Thrown by handler to signal an error. 288 */ 289 public void externalEntityDecl(String name, 290 XMLResourceIdentifier identifier, 291 Augmentations augmentations) 292 throws XNIException; 293 294 /** 295 * An unparsed entity declaration. 296 * 297 * @param name The name of the entity. 298 * @param identifier An object containing all location information 299 * pertinent to this unparsed entity declaration. 300 * @param notation The name of the notation. 301 * @param augmentations Additional information that may include infoset 302 * augmentations. 303 * 304 * @throws XNIException Thrown by handler to signal an error. 305 */ 306 public void unparsedEntityDecl(String name, 307 XMLResourceIdentifier identifier, 308 String notation, Augmentations augmentations) 309 throws XNIException; 310 311 /** 312 * A notation declaration 313 * 314 * @param name The name of the notation. 315 * @param identifier An object containing all location information 316 * pertinent to this notation. 317 * @param augmentations Additional information that may include infoset 318 * augmentations. 319 * 320 * @throws XNIException Thrown by handler to signal an error. 321 */ 322 public void notationDecl(String name, XMLResourceIdentifier identifier, 323 Augmentations augmentations) throws XNIException; 324 325 /** 326 * The start of a conditional section. 327 * 328 * @param type The type of the conditional section. This value will 329 * either be CONDITIONAL_INCLUDE or CONDITIONAL_IGNORE. 330 * @param augmentations Additional information that may include infoset 331 * augmentations. 332 * 333 * @throws XNIException Thrown by handler to signal an error. 334 * 335 * @see #CONDITIONAL_INCLUDE 336 * @see #CONDITIONAL_IGNORE 337 */ 338 public void startConditional(short type, Augmentations augmentations) 339 throws XNIException; 340 341 /** 342 * Characters within an IGNORE conditional section. 343 * 344 * @param text The ignored text. 345 * @param augmentations Additional information that may include infoset 346 * augmentations. 347 * 348 * @throws XNIException Thrown by handler to signal an error. 349 */ 350 public void ignoredCharacters(XMLString text, Augmentations augmentations) 351 throws XNIException; 352 353 /** 354 * The end of a conditional section. 355 * 356 * @param augmentations Additional information that may include infoset 357 * augmentations. 358 * 359 * @throws XNIException Thrown by handler to signal an error. 360 */ 361 public void endConditional(Augmentations augmentations) throws XNIException; 362 363 /** 364 * The end of the DTD. 365 * 366 * @param augmentations Additional information that may include infoset 367 * augmentations. 368 * 369 * @throws XNIException Thrown by handler to signal an error. 370 */ 371 public void endDTD(Augmentations augmentations) throws XNIException; 372 373 // set the source of this handler 374 public void setDTDSource(XMLDTDSource source); 375 376 // return the source from which this handler derives its events 377 public XMLDTDSource getDTDSource(); 378 379} // interface XMLDTDHandler 380