001// DeclHandler.java - Optional handler for DTD declaration events. 002// Public Domain: no warranty. 003// $Id: DeclHandler.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $ 004 005package org.xml.sax.ext; 006 007import org.xml.sax.SAXException; 008 009 010/** 011 * SAX2 extension handler for DTD declaration events. 012 * 013 * <blockquote> 014 * <em>This module, both source code and documentation, is in the 015 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 016 * </blockquote> 017 * 018 * <p>This is an optional extension handler for SAX2 to provide 019 * information about DTD declarations in an XML document. XML 020 * readers are not required to support this handler, and this 021 * handler is not included in the core SAX2 distribution.</p> 022 * 023 * <p>Note that data-related DTD declarations (unparsed entities and 024 * notations) are already reported through the {@link 025 * org.xml.sax.DTDHandler DTDHandler} interface.</p> 026 * 027 * <p>If you are using the declaration handler together with a lexical 028 * handler, all of the events will occur between the 029 * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the 030 * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p> 031 * 032 * <p>To set the DeclHandler for an XML reader, use the 033 * {@link org.xml.sax.XMLReader#setProperty setProperty} method 034 * with the propertyId "http://xml.org/sax/properties/declaration-handler". 035 * If the reader does not support declaration events, it will throw a 036 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException} 037 * or a 038 * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException} 039 * when you attempt to register the handler.</p> 040 * 041 * @since 1.0 042 * @author David Megginson, 043 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 044 * @version 1.0beta 045 * @see org.xml.sax.XMLReader 046 */ 047public interface DeclHandler 048{ 049 050 /** 051 * Report an element type declaration. 052 * 053 * <p>The content model will consist of the string "EMPTY", the 054 * string "ANY", or a parenthesised group, optionally followed 055 * by an occurrence indicator. The model will be normalized so 056 * that all parameter entities are fully resolved and all whitespace 057 * is removed,and will include the enclosing parentheses. Other 058 * normalization (such as removing redundant parentheses or 059 * simplifying occurrence indicators) is at the discretion of the 060 * parser.</p> 061 * 062 * @param name The element type name. 063 * @param model The content model as a normalized string. 064 * @exception SAXException The application may raise an exception. 065 */ 066 public abstract void elementDecl (String name, String model) 067 throws SAXException; 068 069 070 /** 071 * Report an attribute type declaration. 072 * 073 * <p>Only the effective (first) declaration for an attribute will 074 * be reported. The type will be one of the strings "CDATA", 075 * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", 076 * "ENTITIES", a parenthesized token group with 077 * the separator "|" and all whitespace removed, or the word 078 * "NOTATION" followed by a space followed by a parenthesized 079 * token group with all whitespace removed.</p> 080 * 081 * <p>Any parameter entities in the attribute value will be 082 * expanded, but general entities will not.</p> 083 * 084 * @param eName The name of the associated element. 085 * @param aName The name of the attribute. 086 * @param type A string representing the attribute type. 087 * @param valueDefault A string representing the attribute default 088 * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if 089 * none of these applies. 090 * @param value A string representing the attribute's default value, 091 * or null if there is none. 092 * @exception SAXException The application may raise an exception. 093 */ 094 public abstract void attributeDecl (String eName, 095 String aName, 096 String type, 097 String valueDefault, 098 String value) 099 throws SAXException; 100 101 102 /** 103 * Report an internal entity declaration. 104 * 105 * <p>Only the effective (first) declaration for each entity 106 * will be reported. All parameter entities in the value 107 * will be expanded, but general entities will not.</p> 108 * 109 * @param name The name of the entity. If it is a parameter 110 * entity, the name will begin with '%'. 111 * @param value The replacement text of the entity. 112 * @exception SAXException The application may raise an exception. 113 * @see #externalEntityDecl 114 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 115 */ 116 public abstract void internalEntityDecl (String name, String value) 117 throws SAXException; 118 119 120 /** 121 * Report a parsed external entity declaration. 122 * 123 * <p>Only the effective (first) declaration for each entity 124 * will be reported.</p> 125 * 126 * @param name The name of the entity. If it is a parameter 127 * entity, the name will begin with '%'. 128 * @param publicId The declared public identifier of the entity, or 129 * null if none was declared. 130 * @param systemId The declared system identifier of the entity. 131 * @exception SAXException The application may raise an exception. 132 * @see #internalEntityDecl 133 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 134 */ 135 public abstract void externalEntityDecl (String name, String publicId, 136 String systemId) 137 throws SAXException; 138 139} 140 141// end of DeclHandler.java