001// DeclHandler.java - Optional handler for DTD declaration events.
002// http://www.saxproject.org
003// Public Domain: no warranty.
004// $Id: DeclHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006package org.xml.sax.ext;
007
008import org.xml.sax.SAXException;
009
010
011/**
012 * SAX2 extension handler for DTD declaration events.
013 *
014 * <blockquote>
015 * <em>This module, both source code and documentation, is in the
016 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
017 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
018 * for further information.
019 * </blockquote>
020 *
021 * <p>This is an optional extension handler for SAX2 to provide more
022 * complete information about DTD declarations in an XML document.
023 * XML readers are not required to recognize this handler, and it
024 * is not part of core-only SAX2 distributions.</p>
025 *
026 * <p>Note that data-related DTD declarations (unparsed entities and
027 * notations) are already reported through the {@link
028 * org.xml.sax.DTDHandler DTDHandler} interface.</p>
029 *
030 * <p>If you are using the declaration handler together with a lexical
031 * handler, all of the events will occur between the
032 * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
033 * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
034 *
035 * <p>To set the DeclHandler for an XML reader, use the
036 * {@link org.xml.sax.XMLReader#setProperty setProperty} method
037 * with the property name
038 * <code>http://xml.org/sax/properties/declaration-handler</code>
039 * and an object implementing this interface (or null) as the value.
040 * If the reader does not report declaration events, it will throw a
041 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
042 * when you attempt to register the handler.</p>
043 *
044 * @since SAX 2.0 (extensions 1.0)
045 * @author David Megginson
046 * @version 2.0.1 (sax2r2)
047 */
048public interface DeclHandler
049{
050
051    /**
052     * Report an element type declaration.
053     *
054     * <p>The content model will consist of the string "EMPTY", the
055     * string "ANY", or a parenthesised group, optionally followed
056     * by an occurrence indicator.  The model will be normalized so
057     * that all parameter entities are fully resolved and all whitespace 
058     * is removed,and will include the enclosing parentheses.  Other
059     * normalization (such as removing redundant parentheses or 
060     * simplifying occurrence indicators) is at the discretion of the
061     * parser.</p>
062     *
063     * @param name The element type name.
064     * @param model The content model as a normalized string.
065     * @exception SAXException The application may raise an exception.
066     */
067    public abstract void elementDecl (String name, String model)
068        throws SAXException;
069
070
071    /**
072     * Report an attribute type declaration.
073     *
074     * <p>Only the effective (first) declaration for an attribute will
075     * be reported.  The type will be one of the strings "CDATA",
076     * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
077     * "ENTITIES", a parenthesized token group with 
078     * the separator "|" and all whitespace removed, or the word
079     * "NOTATION" followed by a space followed by a parenthesized
080     * token group with all whitespace removed.</p>
081     *
082     * <p>The value will be the value as reported to applications,
083     * appropriately normalized and with entity and character
084     * references expanded.  </p>
085     *
086     * @param eName The name of the associated element.
087     * @param aName The name of the attribute.
088     * @param type A string representing the attribute type.
089     * @param mode A string representing the attribute defaulting mode
090     *        ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
091     *        none of these applies.
092     * @param value A string representing the attribute's default value,
093     *        or null if there is none.
094     * @exception SAXException The application may raise an exception.
095     */
096    public abstract void attributeDecl (String eName,
097                                        String aName,
098                                        String type,
099                                        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