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