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 */ 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 */ 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 */ 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 */ 140 public abstract void externalEntityDecl (String name, String publicId, 141 String systemId) 142 throws SAXException; 143 144 } 145 146 // end of DeclHandler.java 147
