001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // LexicalHandler.java - optional handler for lexical parse events.
027 // http://www.saxproject.org
028 // Public Domain: no warranty.
029 // $Id: LexicalHandler.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $
030 package org.xml.sax.ext;
031
032 import org.xml.sax.SAXException;
033
034 /**
035 * SAX2 extension handler for lexical events.
036 *
037 * <blockquote>
038 * <em>This module, both source code and documentation, is in the
039 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
040 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
041 * for further information.
042 * </blockquote>
043 *
044 * <p>This is an optional extension handler for SAX2 to provide
045 * lexical information about an XML document, such as comments
046 * and CDATA section boundaries.
047 * XML readers are not required to recognize this handler, and it
048 * is not part of core-only SAX2 distributions.</p>
049 *
050 * <p>The events in the lexical handler apply to the entire document,
051 * not just to the document element, and all lexical handler events
052 * must appear between the content handler's startDocument and
053 * endDocument events.</p>
054 *
055 * <p>To set the LexicalHandler for an XML reader, use the
056 * {@link org.xml.sax.XMLReader#setProperty setProperty} method
057 * with the property name
058 * <code>http://xml.org/sax/properties/lexical-handler</code>
059 * and an object implementing this interface (or null) as the value.
060 * If the reader does not report lexical events, it will throw a
061 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
062 * when you attempt to register the handler.</p>
063 *
064 * @since SAX 2.0 (extensions 1.0)
065 * @author David Megginson
066 * @version 2.0.1 (sax2r2)
067 */
068 public interface LexicalHandler {
069
070 /**
071 * Report the start of DTD declarations, if any.
072 *
073 * <p>This method is intended to report the beginning of the
074 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
075 * this method will not be invoked.</p>
076 *
077 * <p>All declarations reported through
078 * {@link org.xml.sax.DTDHandler DTDHandler} or
079 * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear
080 * between the startDTD and {@link #endDTD endDTD} events.
081 * Declarations are assumed to belong to the internal DTD subset
082 * unless they appear between {@link #startEntity startEntity}
083 * and {@link #endEntity endEntity} events. Comments and
084 * processing instructions from the DTD should also be reported
085 * between the startDTD and endDTD events, in their original
086 * order of (logical) occurrence; they are not required to
087 * appear in their correct locations relative to DTDHandler
088 * or DeclHandler events, however.</p>
089 *
090 * <p>Note that the start/endDTD events will appear within
091 * the start/endDocument events from ContentHandler and
092 * before the first
093 * {@link org.xml.sax.ContentHandler#startElement startElement}
094 * event.</p>
095 *
096 * @param name The document type name.
097 * @param publicId The declared public identifier for the
098 * external DTD subset, or null if none was declared.
099 * @param systemId The declared system identifier for the
100 * external DTD subset, or null if none was declared.
101 * (Note that this is not resolved against the document
102 * base URI.)
103 * @exception SAXException The application may raise an
104 * exception.
105 * @see #endDTD
106 * @see #startEntity
107 */
108 public abstract void startDTD(String name, String publicId,
109 String systemId) throws SAXException;
110
111 /**
112 * Report the end of DTD declarations.
113 *
114 * <p>This method is intended to report the end of the
115 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
116 * this method will not be invoked.</p>
117 *
118 * @exception SAXException The application may raise an exception.
119 * @see #startDTD
120 */
121 public abstract void endDTD() throws SAXException;
122
123 /**
124 * Report the beginning of some internal and external XML entities.
125 *
126 * <p>The reporting of parameter entities (including
127 * the external DTD subset) is optional, and SAX2 drivers that
128 * report LexicalHandler events may not implement it; you can use the
129 * <code
130 * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
131 * feature to query or control the reporting of parameter entities.</p>
132 *
133 * <p>General entities are reported with their regular names,
134 * parameter entities have '%' prepended to their names, and
135 * the external DTD subset has the pseudo-entity name "[dtd]".</p>
136 *
137 * <p>When a SAX2 driver is providing these events, all other
138 * events must be properly nested within start/end entity
139 * events. There is no additional requirement that events from
140 * {@link org.xml.sax.ext.DeclHandler DeclHandler} or
141 * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>
142 *
143 * <p>Note that skipped entities will be reported through the
144 * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}
145 * event, which is part of the ContentHandler interface.</p>
146 *
147 * <p>Because of the streaming event model that SAX uses, some
148 * entity boundaries cannot be reported under any
149 * circumstances:</p>
150 *
151 * <ul>
152 * <li>general entities within attribute values</li>
153 * <li>parameter entities within declarations</li>
154 * </ul>
155 *
156 * <p>These will be silently expanded, with no indication of where
157 * the original entity boundaries were.</p>
158 *
159 * <p>Note also that the boundaries of character references (which
160 * are not really entities anyway) are not reported.</p>
161 *
162 * <p>All start/endEntity events must be properly nested.
163 *
164 * @param name The name of the entity. If it is a parameter
165 * entity, the name will begin with '%', and if it is the
166 * external DTD subset, it will be "[dtd]".
167 * @exception SAXException The application may raise an exception.
168 * @see #endEntity
169 * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
170 * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
171 */
172 public abstract void startEntity(String name) throws SAXException;
173
174 /**
175 * Report the end of an entity.
176 *
177 * @param name The name of the entity that is ending.
178 * @exception SAXException The application may raise an exception.
179 * @see #startEntity
180 */
181 public abstract void endEntity(String name) throws SAXException;
182
183 /**
184 * Report the start of a CDATA section.
185 *
186 * <p>The contents of the CDATA section will be reported through
187 * the regular {@link org.xml.sax.ContentHandler#characters
188 * characters} event; this event is intended only to report
189 * the boundary.</p>
190 *
191 * @exception SAXException The application may raise an exception.
192 * @see #endCDATA
193 */
194 public abstract void startCDATA() throws SAXException;
195
196 /**
197 * Report the end of a CDATA section.
198 *
199 * @exception SAXException The application may raise an exception.
200 * @see #startCDATA
201 */
202 public abstract void endCDATA() throws SAXException;
203
204 /**
205 * Report an XML comment anywhere in the document.
206 *
207 * <p>This callback will be used for comments inside or outside the
208 * document element, including comments in the external DTD
209 * subset (if read). Comments in the DTD must be properly
210 * nested inside start/endDTD and start/endEntity events (if
211 * used).</p>
212 *
213 * @param ch An array holding the characters in the comment.
214 * @param start The starting position in the array.
215 * @param length The number of characters to use from the array.
216 * @exception SAXException The application may raise an exception.
217 */
218 public abstract void comment(char ch[], int start, int length)
219 throws SAXException;
220
221 }
222
223 // end of LexicalHandler.java
|