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    
006    package org.xml.sax.ext;
007    
008    import 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     */
048    public 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