1 /*
2 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package org.xml.sax.ext;
27
28 import org.xml.sax.SAXException;
29
30 /**
31 * SAX2 extension handler for lexical events.
32 *
33 * <p>This is an optional extension handler for SAX2 to provide
34 * lexical information about an XML document, such as comments
35 * and CDATA section boundaries.
36 * XML readers are not required to recognize this handler, and it
37 * is not part of core-only SAX2 distributions.</p>
38 *
39 * <p>The events in the lexical handler apply to the entire document,
40 * not just to the document element, and all lexical handler events
41 * must appear between the content handler's startDocument and
42 * endDocument events.</p>
43 *
44 * <p>To set the LexicalHandler for an XML reader, use the
45 * {@link org.xml.sax.XMLReader#setProperty setProperty} method
46 * with the property name
47 * <code>http://xml.org/sax/properties/lexical-handler</code>
48 * and an object implementing this interface (or null) as the value.
49 * If the reader does not report lexical events, it will throw a
50 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
51 * when you attempt to register the handler.</p>
52 *
53 * @since 1.4, SAX 2.0 (extensions 1.0)
54 * @author David Megginson
55 */
56 public interface LexicalHandler
57 {
58
59 /**
60 * Report the start of DTD declarations, if any.
61 *
62 * <p>This method is intended to report the beginning of the
63 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
64 * this method will not be invoked.</p>
65 *
66 * <p>All declarations reported through
67 * {@link org.xml.sax.DTDHandler DTDHandler} or
68 * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear
69 * between the startDTD and {@link #endDTD endDTD} events.
70 * Declarations are assumed to belong to the internal DTD subset
71 * unless they appear between {@link #startEntity startEntity}
72 * and {@link #endEntity endEntity} events. Comments and
73 * processing instructions from the DTD should also be reported
74 * between the startDTD and endDTD events, in their original
75 * order of (logical) occurrence; they are not required to
76 * appear in their correct locations relative to DTDHandler
77 * or DeclHandler events, however.</p>
78 *
79 * <p>Note that the start/endDTD events will appear within
80 * the start/endDocument events from ContentHandler and
81 * before the first
82 * {@link org.xml.sax.ContentHandler#startElement startElement}
83 * event.</p>
84 *
85 * @param name The document type name.
86 * @param publicId The declared public identifier for the
87 * external DTD subset, or null if none was declared.
88 * @param systemId The declared system identifier for the
89 * external DTD subset, or null if none was declared.
90 * (Note that this is not resolved against the document
91 * base URI.)
92 * @exception SAXException The application may raise an
93 * exception.
94 * @see #endDTD
95 * @see #startEntity
96 */
97 public abstract void startDTD (String name, String publicId,
98 String systemId)
99 throws SAXException;
100
101
102 /**
103 * Report the end of DTD declarations.
104 *
105 * <p>This method is intended to report the end of the
106 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
107 * this method will not be invoked.</p>
108 *
109 * @exception SAXException The application may raise an exception.
110 * @see #startDTD
111 */
112 public abstract void endDTD ()
113 throws SAXException;
114
115
116 /**
117 * Report the beginning of some internal and external XML entities.
118 *
119 * <p>The reporting of parameter entities (including
120 * the external DTD subset) is optional, and SAX2 drivers that
121 * report LexicalHandler events may not implement it; you can use the
122 * <code
123 * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
124 * feature to query or control the reporting of parameter entities.</p>
125 *
126 * <p>General entities are reported with their regular names,
127 * parameter entities have '%' prepended to their names, and
128 * the external DTD subset has the pseudo-entity name "[dtd]".</p>
129 *
130 * <p>When a SAX2 driver is providing these events, all other
131 * events must be properly nested within start/end entity
132 * events. There is no additional requirement that events from
133 * {@link org.xml.sax.ext.DeclHandler DeclHandler} or
134 * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>
135 *
136 * <p>Note that skipped entities will be reported through the
137 * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}
138 * event, which is part of the ContentHandler interface.</p>
139 *
140 * <p>Because of the streaming event model that SAX uses, some
141 * entity boundaries cannot be reported under any
142 * circumstances:</p>
143 *
144 * <ul>
145 * <li>general entities within attribute values</li>
146 * <li>parameter entities within declarations</li>
147 * </ul>
148 *
149 * <p>These will be silently expanded, with no indication of where
150 * the original entity boundaries were.</p>
151 *
152 * <p>Note also that the boundaries of character references (which
153 * are not really entities anyway) are not reported.</p>
154 *
155 * <p>All start/endEntity events must be properly nested.
156 *
157 * @param name The name of the entity. If it is a parameter
158 * entity, the name will begin with '%', and if it is the
159 * external DTD subset, it will be "[dtd]".
160 * @exception SAXException The application may raise an exception.
161 * @see #endEntity
162 * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
163 * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
164 */
165 public abstract void startEntity (String name)
166 throws SAXException;
167
168
169 /**
170 * Report the end of an entity.
171 *
172 * @param name The name of the entity that is ending.
173 * @exception SAXException The application may raise an exception.
174 * @see #startEntity
175 */
176 public abstract void endEntity (String name)
177 throws SAXException;
178
179
180 /**
181 * Report the start of a CDATA section.
182 *
183 * <p>The contents of the CDATA section will be reported through
184 * the regular {@link org.xml.sax.ContentHandler#characters
185 * characters} event; this event is intended only to report
186 * the boundary.</p>
187 *
188 * @exception SAXException The application may raise an exception.
189 * @see #endCDATA
190 */
191 public abstract void startCDATA ()
192 throws SAXException;
193
194
195 /**
196 * Report the end of a CDATA section.
197 *
198 * @exception SAXException The application may raise an exception.
199 * @see #startCDATA
200 */
201 public abstract void endCDATA ()
202 throws SAXException;
203
204
205 /**
206 * Report an XML comment anywhere in the document.
207 *
208 * <p>This callback will be used for comments inside or outside the
209 * document element, including comments in the external DTD
210 * subset (if read). Comments in the DTD must be properly
211 * nested inside start/endDTD and start/endEntity events (if
212 * used).</p>
213 *
214 * @param ch An array holding the characters in the comment.
215 * @param start The starting position in the array.
216 * @param length The number of characters to use from the array.
217 * @exception SAXException The application may raise an exception.
218 */
219 public abstract void comment (char ch[], int start, int length)
220 throws SAXException;
221
222 }
223
224 // end of LexicalHandler.java