1 /*
2 * Copyright (c) 1998, 2015, 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 com.sun.xml.internal.dtdparser;
27
28 import org.xml.sax.Locator;
29 import org.xml.sax.SAXException;
30 import org.xml.sax.SAXParseException;
31
32 import java.util.EventListener;
33
34 /**
35 * All DTD parsing events are signaled through this interface.
36 */
37 public interface DTDEventListener extends EventListener {
38
39 public void setDocumentLocator(Locator loc);
40
41 /**
42 * Receive notification of a Processing Instruction.
43 * Processing instructions contain information meaningful
44 * to the application.
45 *
46 * @param target The target of the proceessing instruction
47 * which should have meaning to the application.
48 * @param data The instruction itself which should contain
49 * valid XML characters.
50 * @throws SAXException
51 */
52 public void processingInstruction(String target, String data)
53 throws SAXException;
54
55 /**
56 * Receive notification of a Notation Declaration.
57 * Notation declarations are used by elements and entities
58 * for identifying embedded non-XML data.
59 *
60 * @param name The notation name, referred to by entities and
61 * elements.
62 * @param publicId The public identifier
63 * @param systemId The system identifier
64 */
65 public void notationDecl(String name, String publicId, String systemId)
66 throws SAXException;
67
68 /**
69 * Receive notification of an unparsed entity declaration.
70 * Unparsed entities are non-XML data.
71 *
72 * @param name The name of the unparsed entity.
73 * @param publicId The public identifier
74 * @param systemId The system identifier
75 * @param notationName The associated notation
76 */
77 public void unparsedEntityDecl(String name, String publicId,
78 String systemId, String notationName)
79 throws SAXException;
80
81 /**
82 * Receive notification of a internal general entity declaration event.
83 *
84 * @param name The internal general entity name.
85 * @param value The value of the entity, which may include unexpanded
86 * entity references. Character references will have been
87 * expanded.
88 * @throws SAXException
89 * @see #externalGeneralEntityDecl(String, String, String)
90 */
91 public void internalGeneralEntityDecl(String name, String value)
92 throws SAXException;
93
94 /**
95 * Receive notification of an external parsed general entity
96 * declaration event.
97 * <p>
98 * <p>If a system identifier is present, and it is a relative URL, the
99 * parser will have resolved it fully before passing it through this
100 * method to a listener.</p>
101 *
102 * @param name The entity name.
103 * @param publicId The entity's public identifier, or null if
104 * none was given.
105 * @param systemId The entity's system identifier.
106 * @throws SAXException
107 * @see #unparsedEntityDecl(String, String, String, String)
108 */
109 public void externalGeneralEntityDecl(String name, String publicId,
110 String systemId)
111 throws SAXException;
112
113 /**
114 * Receive notification of a internal parameter entity declaration
115 * event.
116 *
117 * @param name The internal parameter entity name.
118 * @param value The value of the entity, which may include unexpanded
119 * entity references. Character references will have been
120 * expanded.
121 * @throws SAXException
122 * @see #externalParameterEntityDecl(String, String, String)
123 */
124 public void internalParameterEntityDecl(String name, String value)
125 throws SAXException;
126
127 /**
128 * Receive notification of an external parameter entity declaration
129 * event.
130 * <p>
131 * <p>If a system identifier is present, and it is a relative URL, the
132 * parser will have resolved it fully before passing it through this
133 * method to a listener.</p>
134 *
135 * @param name The parameter entity name.
136 * @param publicId The entity's public identifier, or null if
137 * none was given.
138 * @param systemId The entity's system identifier.
139 * @throws SAXException
140 * @see #unparsedEntityDecl(String, String, String, String)
141 */
142 public void externalParameterEntityDecl(String name, String publicId,
143 String systemId)
144 throws SAXException;
145
146 /**
147 * Receive notification of the beginning of the DTD.
148 *
149 * @param in Current input entity.
150 * @see #endDTD()
151 */
152 public void startDTD(InputEntity in)
153 throws SAXException;
154
155 /**
156 * Receive notification of the end of a DTD. The parser will invoke
157 * this method only once.
158 *
159 * @throws SAXException
160 * @see #startDTD(InputEntity)
161 */
162 public void endDTD()
163 throws SAXException;
164
165 /**
166 * Receive notification that a comment has been read.
167 * <p>
168 * <P> Note that processing instructions are the mechanism designed
169 * to hold information for consumption by applications, not comments.
170 * XML systems may rely on applications being able to access information
171 * found in processing instructions; this is not true of comments, which
172 * are typically discarded.
173 *
174 * @param text the text within the comment delimiters.
175 * @throws SAXException
176 */
177 public void comment(String text)
178 throws SAXException;
179
180 /**
181 * Receive notification of character data.
182 * <p>
183 * <p>The Parser will call this method to report each chunk of
184 * character data. SAX parsers may return all contiguous character
185 * data in a single chunk, or they may split it into several
186 * chunks; however, all of the characters in any single event
187 * must come from the same external entity, so that the Locator
188 * provides useful information.</p>
189 * <p>
190 * <p>The application must not attempt to read from the array
191 * outside of the specified range.</p>
192 * <p>
193 * <p>Note that some parsers will report whitespace using the
194 * ignorableWhitespace() method rather than this one (validating
195 * parsers must do so).</p>
196 *
197 * @param ch The characters from the DTD.
198 * @param start The start position in the array.
199 * @param length The number of characters to read from the array.
200 * @throws SAXException
201 * @see #ignorableWhitespace(char[], int, int)
202 */
203 public void characters(char ch[], int start, int length)
204 throws SAXException;
205
206
207 /**
208 * Receive notification of ignorable whitespace in element content.
209 * <p>
210 * <p>Validating Parsers must use this method to report each chunk
211 * of ignorable whitespace (see the W3C XML 1.0 recommendation,
212 * section 2.10): non-validating parsers may also use this method
213 * if they are capable of parsing and using content models.</p>
214 * <p>
215 * <p>SAX parsers may return all contiguous whitespace in a single
216 * chunk, or they may split it into several chunks; however, all of
217 * the characters in any single event must come from the same
218 * external entity, so that the Locator provides useful
219 * information.</p>
220 * <p>
221 * <p>The application must not attempt to read from the array
222 * outside of the specified range.</p>
223 *
224 * @param ch The characters from the DTD.
225 * @param start The start position in the array.
226 * @param length The number of characters to read from the array.
227 * @throws SAXException
228 * @see #characters(char[], int, int)
229 */
230 public void ignorableWhitespace(char ch[], int start, int length)
231 throws SAXException;
232
233 /**
234 * Receive notification that a CDATA section is beginning. Data in a
235 * CDATA section is is reported through the appropriate event, either
236 * <em>characters()</em> or <em>ignorableWhitespace</em>.
237 *
238 * @throws SAXException
239 * @see #endCDATA()
240 */
241 public void startCDATA() throws SAXException;
242
243
244 /**
245 * Receive notification that the CDATA section finished.
246 *
247 * @throws SAXException
248 * @see #startCDATA()
249 */
250 public void endCDATA() throws SAXException;
251
252
253 public void fatalError(SAXParseException e)
254 throws SAXException;
255
256 public void error(SAXParseException e) throws SAXException;
257
258 public void warning(SAXParseException err) throws SAXException;
259
260 public final short CONTENT_MODEL_EMPTY = 0;
261 public final short CONTENT_MODEL_ANY = 1;
262 public final short CONTENT_MODEL_MIXED = 2;
263 public final short CONTENT_MODEL_CHILDREN = 3;
264
265 /**
266 * receives notification that parsing of content model is beginning.
267 *
268 * @param elementName name of the element whose content model is going to be defined.
269 * @param contentModelType {@link #CONTENT_MODEL_EMPTY}
270 * this element has EMPTY content model. This notification
271 * will be immediately followed by the corresponding endContentModel.
272 * {@link #CONTENT_MODEL_ANY}
273 * this element has ANY content model. This notification
274 * will be immediately followed by the corresponding endContentModel.
275 * {@link #CONTENT_MODEL_MIXED}
276 * this element has mixed content model. #PCDATA will not be reported.
277 * each child element will be reported by mixedElement method.
278 * {@link #CONTENT_MODEL_CHILDREN}
279 * this elemen has child content model. The actual content model will
280 * be reported by childElement, startModelGroup, endModelGroup, and
281 * connector methods. Possible call sequences are:
282 * <p>
283 * START := MODEL_GROUP
284 * MODEL_GROUP := startModelGroup TOKEN (connector TOKEN)* endModelGroup
285 * TOKEN := childElement
286 * | MODEL_GROUP
287 */
288 public void startContentModel(String elementName, short contentModelType) throws SAXException;
289
290 /**
291 * receives notification that parsing of content model is finished.
292 */
293 public void endContentModel(String elementName, short contentModelType) throws SAXException;
294
295 public final short USE_NORMAL = 0;
296 public final short USE_IMPLIED = 1;
297 public final short USE_FIXED = 2;
298 public final short USE_REQUIRED = 3;
299
300 /**
301 * For each entry in an ATTLIST declaration,
302 * this event will be fired.
303 * <p>
304 * <p>
305 * DTD allows the same attributes to be declared more than
306 * once, and in that case the first one wins. I think
307 * this method will be only fired for the first one,
308 * but I need to check.
309 */
310 public void attributeDecl(String elementName, String attributeName, String attributeType,
311 String[] enumeration, short attributeUse, String defaultValue) throws SAXException;
312
313 public void childElement(String elementName, short occurence) throws SAXException;
314
315 /**
316 * receives notification of child element of mixed content model.
317 * this method is called for each child element.
318 *
319 * @see #startContentModel(String, short)
320 */
321 public void mixedElement(String elementName) throws SAXException;
322
323 public void startModelGroup() throws SAXException;
324
325 public void endModelGroup(short occurence) throws SAXException;
326
327 public final short CHOICE = 0;
328 public final short SEQUENCE = 1;
329
330 /**
331 * Connectors in one model group is guaranteed to be the same.
332 * <p>
333 * <p>
334 * IOW, you'll never see an event sequence like (a|b,c)
335 */
336 public void connector(short connectorType) throws SAXException;
337
338 public final short OCCURENCE_ZERO_OR_MORE = 0;
339 public final short OCCURENCE_ONE_OR_MORE = 1;
340 public final short OCCURENCE_ZERO_OR_ONE = 2;
341 public final short OCCURENCE_ONCE = 3;
342 }