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