001    // LexicalHandler.java - optional handler for lexical parse events.
002    // http://www.saxproject.org
003    // Public Domain: no warranty.
004    // $Id: LexicalHandler.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     * SAX2 extension handler for lexical 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     * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
017     * for further information.
018     * </blockquote>
019     *
020     * <p>This is an optional extension handler for SAX2 to provide
021     * lexical information about an XML document, such as comments
022     * and CDATA section boundaries.
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>The events in the lexical handler apply to the entire document,
027     * not just to the document element, and all lexical handler events
028     * must appear between the content handler's startDocument and
029     * endDocument events.</p>
030     *
031     * <p>To set the LexicalHandler for an XML reader, use the
032     * {@link org.xml.sax.XMLReader#setProperty setProperty} method
033     * with the property name
034     * <code>http://xml.org/sax/properties/lexical-handler</code>
035     * and an object implementing this interface (or null) as the value.
036     * If the reader does not report lexical events, it will throw a
037     * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
038     * when you attempt to register the handler.</p>
039     *
040     * @since SAX 2.0 (extensions 1.0)
041     * @author David Megginson
042     * @version 2.0.1 (sax2r2)
043     */
044    public interface LexicalHandler
045    {
046    
047        /**
048         * Report the start of DTD declarations, if any.
049         *
050         * <p>This method is intended to report the beginning of the
051         * DOCTYPE declaration; if the document has no DOCTYPE declaration,
052         * this method will not be invoked.</p>
053         *
054         * <p>All declarations reported through
055         * {@link org.xml.sax.DTDHandler DTDHandler} or
056         * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear
057         * between the startDTD and {@link #endDTD endDTD} events.
058         * Declarations are assumed to belong to the internal DTD subset
059         * unless they appear between {@link #startEntity startEntity}
060         * and {@link #endEntity endEntity} events.  Comments and
061         * processing instructions from the DTD should also be reported
062         * between the startDTD and endDTD events, in their original
063         * order of (logical) occurrence; they are not required to
064         * appear in their correct locations relative to DTDHandler
065         * or DeclHandler events, however.</p>
066         *
067         * <p>Note that the start/endDTD events will appear within
068         * the start/endDocument events from ContentHandler and
069         * before the first
070         * {@link org.xml.sax.ContentHandler#startElement startElement}
071         * event.</p>
072         *
073         * @param name The document type name.
074         * @param publicId The declared public identifier for the
075         *        external DTD subset, or null if none was declared.
076         * @param systemId The declared system identifier for the
077         *        external DTD subset, or null if none was declared.
078         *        (Note that this is not resolved against the document
079         *        base URI.)
080         * @exception SAXException The application may raise an
081         *            exception.
082         * @see #endDTD
083         * @see #startEntity
084         */
085        public abstract void startDTD (String name, String publicId,
086                                       String systemId)
087            throws SAXException;
088    
089    
090        /**
091         * Report the end of DTD declarations.
092         *
093         * <p>This method is intended to report the end of the
094         * DOCTYPE declaration; if the document has no DOCTYPE declaration,
095         * this method will not be invoked.</p>
096         *
097         * @exception SAXException The application may raise an exception.
098         * @see #startDTD
099         */
100        public abstract void endDTD ()
101            throws SAXException;
102    
103    
104        /**
105         * Report the beginning of some internal and external XML entities.
106         *
107         * <p>The reporting of parameter entities (including
108         * the external DTD subset) is optional, and SAX2 drivers that
109         * report LexicalHandler events may not implement it; you can use the
110         * <code
111         * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
112         * feature to query or control the reporting of parameter entities.</p>
113         *
114         * <p>General entities are reported with their regular names,
115         * parameter entities have '%' prepended to their names, and
116         * the external DTD subset has the pseudo-entity name "[dtd]".</p>
117         *
118         * <p>When a SAX2 driver is providing these events, all other
119         * events must be properly nested within start/end entity
120         * events.  There is no additional requirement that events from
121         * {@link org.xml.sax.ext.DeclHandler DeclHandler} or
122         * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>
123         *
124         * <p>Note that skipped entities will be reported through the
125         * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}
126         * event, which is part of the ContentHandler interface.</p>
127         *
128         * <p>Because of the streaming event model that SAX uses, some
129         * entity boundaries cannot be reported under any
130         * circumstances:</p>
131         *
132         * <ul>
133         * <li>general entities within attribute values</li>
134         * <li>parameter entities within declarations</li>
135         * </ul>
136         *
137         * <p>These will be silently expanded, with no indication of where
138         * the original entity boundaries were.</p>
139         *
140         * <p>Note also that the boundaries of character references (which
141         * are not really entities anyway) are not reported.</p>
142         *
143         * <p>All start/endEntity events must be properly nested.
144         *
145         * @param name The name of the entity.  If it is a parameter
146         *        entity, the name will begin with '%', and if it is the
147         *        external DTD subset, it will be "[dtd]".
148         * @exception SAXException The application may raise an exception.
149         * @see #endEntity
150         * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
151         * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
152         */
153        public abstract void startEntity (String name)
154            throws SAXException;
155    
156    
157        /**
158         * Report the end of an entity.
159         *
160         * @param name The name of the entity that is ending.
161         * @exception SAXException The application may raise an exception.
162         * @see #startEntity
163         */
164        public abstract void endEntity (String name)
165            throws SAXException;
166    
167    
168        /**
169         * Report the start of a CDATA section.
170         *
171         * <p>The contents of the CDATA section will be reported through
172         * the regular {@link org.xml.sax.ContentHandler#characters
173         * characters} event; this event is intended only to report
174         * the boundary.</p>
175         *
176         * @exception SAXException The application may raise an exception.
177         * @see #endCDATA
178         */
179        public abstract void startCDATA ()
180            throws SAXException;
181    
182    
183        /**
184         * Report the end of a CDATA section.
185         *
186         * @exception SAXException The application may raise an exception.
187         * @see #startCDATA
188         */
189        public abstract void endCDATA ()
190            throws SAXException;
191    
192    
193        /**
194         * Report an XML comment anywhere in the document.
195         *
196         * <p>This callback will be used for comments inside or outside the
197         * document element, including comments in the external DTD
198         * subset (if read).  Comments in the DTD must be properly
199         * nested inside start/endDTD and start/endEntity events (if
200         * used).</p>
201         *
202         * @param ch An array holding the characters in the comment.
203         * @param start The starting position in the array.
204         * @param length The number of characters to use from the array.
205         * @exception SAXException The application may raise an exception.
206         */
207        public abstract void comment (char ch[], int start, int length)
208            throws SAXException;
209    
210    }
211    
212    // end of LexicalHandler.java