1 // DeclHandler.java - Optional handler for DTD declaration events. 2 // http://www.saxproject.org 3 // Public Domain: no warranty. 4 // $Id: DeclHandler.java,v 1.6 2004/04/22 13:28:49 dmegginson Exp $ 5 6 package org.xml.sax.ext; 7 8 import org.xml.sax.SAXException; 9 10 11 /** 12 * SAX2 extension handler for DTD declaration events. 13 * 14 * <blockquote> 15 * <em>This module, both source code and documentation, is in the 16 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 17 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 18 * for further information. 19 * </blockquote> 20 * 21 * <p>This is an optional extension handler for SAX2 to provide more 22 * complete information about DTD declarations in an XML document. 23 * XML readers are not required to recognize this handler, and it 24 * is not part of core-only SAX2 distributions.</p> 25 * 26 * <p>Note that data-related DTD declarations (unparsed entities and 27 * notations) are already reported through the {@link 28 * org.xml.sax.DTDHandler DTDHandler} interface.</p> 29 * 30 * <p>If you are using the declaration handler together with a lexical 31 * handler, all of the events will occur between the 32 * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the 33 * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p> 34 * 35 * <p>To set the DeclHandler for an XML reader, use the 36 * {@link org.xml.sax.XMLReader#setProperty setProperty} method 37 * with the property name 38 * <code>http://xml.org/sax/properties/declaration-handler</code> 39 * and an object implementing this interface (or null) as the value. 40 * If the reader does not report declaration events, it will throw a 41 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException} 42 * when you attempt to register the handler.</p> 43 * 44 * @since SAX 2.0 (extensions 1.0) 45 * @author David Megginson 46 * @version 2.0.1 (sax2r2) 47 */ 48 public interface DeclHandler 49 { 50 51 /** 52 * Report an element type declaration. 53 * 54 * <p>The content model will consist of the string "EMPTY", the 55 * string "ANY", or a parenthesised group, optionally followed 56 * by an occurrence indicator. The model will be normalized so 57 * that all parameter entities are fully resolved and all whitespace 58 * is removed,and will include the enclosing parentheses. Other 59 * normalization (such as removing redundant parentheses or 60 * simplifying occurrence indicators) is at the discretion of the 61 * parser.</p> 62 * 63 * @param name The element type name. 64 * @param model The content model as a normalized string. 65 * @exception SAXException The application may raise an exception. 66 */ elementDecl(String name, String model)67 public abstract void elementDecl (String name, String model) 68 throws SAXException; 69 70 71 /** 72 * Report an attribute type declaration. 73 * 74 * <p>Only the effective (first) declaration for an attribute will 75 * be reported. The type will be one of the strings "CDATA", 76 * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", 77 * "ENTITIES", a parenthesized token group with 78 * the separator "|" and all whitespace removed, or the word 79 * "NOTATION" followed by a space followed by a parenthesized 80 * token group with all whitespace removed.</p> 81 * 82 * <p>The value will be the value as reported to applications, 83 * appropriately normalized and with entity and character 84 * references expanded. </p> 85 * 86 * @param eName The name of the associated element. 87 * @param aName The name of the attribute. 88 * @param type A string representing the attribute type. 89 * @param mode A string representing the attribute defaulting mode 90 * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if 91 * none of these applies. 92 * @param value A string representing the attribute's default value, 93 * or null if there is none. 94 * @exception SAXException The application may raise an exception. 95 */ attributeDecl(String eName, String aName, String type, String mode, String value)96 public abstract void attributeDecl (String eName, 97 String aName, 98 String type, 99 String mode, 100 String value) 101 throws SAXException; 102 103 104 /** 105 * Report an internal entity declaration. 106 * 107 * <p>Only the effective (first) declaration for each entity 108 * will be reported. All parameter entities in the value 109 * will be expanded, but general entities will not.</p> 110 * 111 * @param name The name of the entity. If it is a parameter 112 * entity, the name will begin with '%'. 113 * @param value The replacement text of the entity. 114 * @exception SAXException The application may raise an exception. 115 * @see #externalEntityDecl 116 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 117 */ internalEntityDecl(String name, String value)118 public abstract void internalEntityDecl (String name, String value) 119 throws SAXException; 120 121 122 /** 123 * Report a parsed external entity declaration. 124 * 125 * <p>Only the effective (first) declaration for each entity 126 * will be reported.</p> 127 * 128 * <p>If the system identifier is a URL, the parser must resolve it 129 * fully before passing it to the application.</p> 130 * 131 * @param name The name of the entity. If it is a parameter 132 * entity, the name will begin with '%'. 133 * @param publicId The entity's public identifier, or null if none 134 * was given. 135 * @param systemId The entity's system identifier. 136 * @exception SAXException The application may raise an exception. 137 * @see #internalEntityDecl 138 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 139 */ externalEntityDecl(String name, String publicId, String systemId)140 public abstract void externalEntityDecl (String name, String publicId, 141 String systemId) 142 throws SAXException; 143 144 } 145 146 // end of DeclHandler.java 147