| Frames | No Frames |
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.1 2004/12/23 22:38:42 mark 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