KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xerces > xni > XMLDTDHandler


1 /*
2  * Copyright 2000-2002,2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 package org.apache.xerces.xni;
18
19 import org.apache.xerces.xni.parser.XMLDTDSource;
20
21 /**
22  * The DTD handler interface defines callback methods to report
23  * information items in the DTD of an XML document. Parser components
24  * interested in DTD information implement this interface and are
25  * registered as the DTD handler on the DTD source.
26  *
27  * @see XMLDTDContentModelHandler
28  *
29  * @author Andy Clark, IBM
30  *
31  * @version $Id: XMLDTDHandler.java,v 1.12 2004/02/24 23:15:54 mrglavas Exp $
32  */

33 public interface XMLDTDHandler {
34
35     //
36
// Constants
37
//
38

39     /**
40      * Conditional section: INCLUDE.
41      *
42      * @see #CONDITIONAL_IGNORE
43      */

44     public static final short CONDITIONAL_INCLUDE = 0;
45
46     /**
47      * Conditional section: IGNORE.
48      *
49      * @see #CONDITIONAL_INCLUDE
50      */

51     public static final short CONDITIONAL_IGNORE = 1;
52
53     //
54
// XMLDTDHandler methods
55
//
56

57     /**
58      * The start of the DTD.
59      *
60      * @param locator The document locator, or null if the document
61      * location cannot be reported during the parsing of
62      * the document DTD. However, it is <em>strongly</em>
63      * recommended that a locator be supplied that can
64      * at least report the base system identifier of the
65      * DTD.
66      * @param augmentations Additional information that may include infoset
67      * augmentations.
68      *
69      * @throws XNIException Thrown by handler to signal an error.
70      */

71     public void startDTD(XMLLocator locator, Augmentations augmentations)
72         throws XNIException;
73
74     /**
75      * This method notifies of the start of a parameter entity. The parameter
76      * entity name start with a '%' character.
77      *
78      * @param name The name of the parameter entity.
79      * @param identifier The resource identifier.
80      * @param encoding The auto-detected IANA encoding name of the entity
81      * stream. This value will be null in those situations
82      * where the entity encoding is not auto-detected (e.g.
83      * internal parameter entities).
84      * @param augmentations Additional information that may include infoset
85      * augmentations.
86      *
87      * @throws XNIException Thrown by handler to signal an error.
88      */

89     public void startParameterEntity(String JavaDoc name,
90                                      XMLResourceIdentifier identifier,
91                                      String JavaDoc encoding,
92                                      Augmentations augmentations) throws XNIException;
93
94     /**
95      * Notifies of the presence of a TextDecl line in an entity. If present,
96      * this method will be called immediately following the startEntity call.
97      * <p>
98      * <strong>Note:</strong> This method is only called for external
99      * parameter entities referenced in the DTD.
100      *
101      * @param version The XML version, or null if not specified.
102      * @param encoding The IANA encoding name of the entity.
103      * @param augmentations Additional information that may include infoset
104      * augmentations.
105      *
106      * @throws XNIException Thrown by handler to signal an error.
107      */

108     public void textDecl(String JavaDoc version, String JavaDoc encoding,
109                          Augmentations augmentations) throws XNIException;
110
111     /**
112      * This method notifies the end of a parameter entity. Parameter entity
113      * names begin with a '%' character.
114      *
115      * @param name The name of the parameter entity.
116      * @param augmentations Additional information that may include infoset
117      * augmentations.
118      *
119      * @throws XNIException Thrown by handler to signal an error.
120      */

121     public void endParameterEntity(String JavaDoc name, Augmentations augmentations)
122         throws XNIException;
123
124     /**
125      * The start of the DTD external subset.
126      *
127      * @param identifier The resource identifier.
128      * @param augmentations
129      * Additional information that may include infoset
130      * augmentations.
131      * @exception XNIException
132      * Thrown by handler to signal an error.
133      */

134     public void startExternalSubset(XMLResourceIdentifier identifier,
135                                     Augmentations augmentations)
136         throws XNIException;
137
138     /**
139      * The end of the DTD external subset.
140      *
141      * @param augmentations Additional information that may include infoset
142      * augmentations.
143      *
144      * @throws XNIException Thrown by handler to signal an error.
145      */

146     public void endExternalSubset(Augmentations augmentations)
147         throws XNIException;
148
149     /**
150      * A comment.
151      *
152      * @param text The text in the comment.
153      * @param augmentations Additional information that may include infoset
154      * augmentations.
155      *
156      * @throws XNIException Thrown by application to signal an error.
157      */

158     public void comment(XMLString text, Augmentations augmentations)
159         throws XNIException;
160
161     /**
162      * A processing instruction. Processing instructions consist of a
163      * target name and, optionally, text data. The data is only meaningful
164      * to the application.
165      * <p>
166      * Typically, a processing instruction's data will contain a series
167      * of pseudo-attributes. These pseudo-attributes follow the form of
168      * element attributes but are <strong>not</strong> parsed or presented
169      * to the application as anything other than text. The application is
170      * responsible for parsing the data.
171      *
172      * @param target The target.
173      * @param data The data or null if none specified.
174      * @param augmentations Additional information that may include infoset
175      * augmentations.
176      *
177      * @throws XNIException Thrown by handler to signal an error.
178      */

179     public void processingInstruction(String JavaDoc target, XMLString data,
180                                       Augmentations augmentations)
181         throws XNIException;
182
183     /**
184      * An element declaration.
185      *
186      * @param name The name of the element.
187      * @param contentModel The element content model.
188      * @param augmentations Additional information that may include infoset
189      * augmentations.
190      *
191      * @throws XNIException Thrown by handler to signal an error.
192      */

193     public void elementDecl(String JavaDoc name, String JavaDoc contentModel,
194                             Augmentations augmentations)
195         throws XNIException;
196
197     /**
198      * The start of an attribute list.
199      *
200      * @param elementName The name of the element that this attribute
201      * list is associated with.
202      * @param augmentations Additional information that may include infoset
203      * augmentations.
204      *
205      * @throws XNIException Thrown by handler to signal an error.
206      */

207     public void startAttlist(String JavaDoc elementName,
208                              Augmentations augmentations) throws XNIException;
209
210     /**
211      * An attribute declaration.
212      *
213      * @param elementName The name of the element that this attribute
214      * is associated with.
215      * @param attributeName The name of the attribute.
216      * @param type The attribute type. This value will be one of
217      * the following: "CDATA", "ENTITY", "ENTITIES",
218      * "ENUMERATION", "ID", "IDREF", "IDREFS",
219      * "NMTOKEN", "NMTOKENS", or "NOTATION".
220      * @param enumeration If the type has the value "ENUMERATION" or
221      * "NOTATION", this array holds the allowed attribute
222      * values; otherwise, this array is null.
223      * @param defaultType The attribute default type. This value will be
224      * one of the following: "#FIXED", "#IMPLIED",
225      * "#REQUIRED", or null.
226      * @param defaultValue The attribute default value, or null if no
227      * default value is specified.
228      * @param nonNormalizedDefaultValue The attribute default value with no normalization
229      * performed, or null if no default value is specified.
230      * @param augmentations Additional information that may include infoset
231      * augmentations.
232      *
233      * @throws XNIException Thrown by handler to signal an error.
234      */

235     public void attributeDecl(String JavaDoc elementName, String JavaDoc attributeName,
236                               String JavaDoc type, String JavaDoc[] enumeration,
237                               String JavaDoc defaultType, XMLString defaultValue,
238                               XMLString nonNormalizedDefaultValue, Augmentations augmentations)
239         throws XNIException;
240
241     /**
242      * The end of an attribute list.
243      *
244      * @param augmentations Additional information that may include infoset
245      * augmentations.
246      *
247      * @throws XNIException Thrown by handler to signal an error.
248      */

249     public void endAttlist(Augmentations augmentations) throws XNIException;
250
251     /**
252      * An internal entity declaration.
253      *
254      * @param name The name of the entity. Parameter entity names start with
255      * '%', whereas the name of a general entity is just the
256      * entity name.
257      * @param text The value of the entity.
258      * @param nonNormalizedText The non-normalized value of the entity. This
259      * value contains the same sequence of characters that was in
260      * the internal entity declaration, without any entity
261      * references expanded.
262      * @param augmentations Additional information that may include infoset
263      * augmentations.
264      *
265      * @throws XNIException Thrown by handler to signal an error.
266      */

267     public void internalEntityDecl(String JavaDoc name, XMLString text,
268                                    XMLString nonNormalizedText,
269                                    Augmentations augmentations)
270         throws XNIException;
271
272     /**
273      * An external entity declaration.
274      *
275      * @param name The name of the entity. Parameter entity names start
276      * with '%', whereas the name of a general entity is just
277      * the entity name.
278      * @param identifier An object containing all location information
279      * pertinent to this external entity.
280      * @param augmentations Additional information that may include infoset
281      * augmentations.
282      *
283      * @throws XNIException Thrown by handler to signal an error.
284      */

285     public void externalEntityDecl(String JavaDoc name,
286                                    XMLResourceIdentifier identifier,
287                                    Augmentations augmentations)
288         throws XNIException;
289
290     /**
291      * An unparsed entity declaration.
292      *
293      * @param name The name of the entity.
294      * @param identifier An object containing all location information
295      * pertinent to this unparsed entity declaration.
296      * @param notation The name of the notation.
297      * @param augmentations Additional information that may include infoset
298      * augmentations.
299      *
300      * @throws XNIException Thrown by handler to signal an error.
301      */

302     public void unparsedEntityDecl(String JavaDoc name,
303                                    XMLResourceIdentifier identifier,
304                                    String JavaDoc notation, Augmentations augmentations)
305         throws XNIException;
306
307     /**
308      * A notation declaration
309      *
310      * @param name The name of the notation.
311      * @param identifier An object containing all location information
312      * pertinent to this notation.
313      * @param augmentations Additional information that may include infoset
314      * augmentations.
315      *
316      * @throws XNIException Thrown by handler to signal an error.
317      */

318     public void notationDecl(String JavaDoc name, XMLResourceIdentifier identifier,
319                              Augmentations augmentations) throws XNIException;
320
321     /**
322      * The start of a conditional section.
323      *
324      * @param type The type of the conditional section. This value will
325      * either be CONDITIONAL_INCLUDE or CONDITIONAL_IGNORE.
326      * @param augmentations Additional information that may include infoset
327      * augmentations.
328      *
329      * @throws XNIException Thrown by handler to signal an error.
330      *
331      * @see #CONDITIONAL_INCLUDE
332      * @see #CONDITIONAL_IGNORE
333      */

334     public void startConditional(short type, Augmentations augmentations)
335         throws XNIException;
336
337     /**
338      * Characters within an IGNORE conditional section.
339      *
340      * @param text The ignored text.
341      * @param augmentations Additional information that may include infoset
342      * augmentations.
343      *
344      * @throws XNIException Thrown by handler to signal an error.
345      */

346     public void ignoredCharacters(XMLString text, Augmentations augmentations)
347         throws XNIException;
348
349     /**
350      * The end of a conditional section.
351      *
352      * @param augmentations Additional information that may include infoset
353      * augmentations.
354      *
355      * @throws XNIException Thrown by handler to signal an error.
356      */

357     public void endConditional(Augmentations augmentations) throws XNIException;
358
359     /**
360      * The end of the DTD.
361      *
362      * @param augmentations Additional information that may include infoset
363      * augmentations.
364      *
365      * @throws XNIException Thrown by handler to signal an error.
366      */

367     public void endDTD(Augmentations augmentations) throws XNIException;
368
369     // set the source of this handler
370
public void setDTDSource(XMLDTDSource source);
371
372     // return the source from which this handler derives its events
373
public XMLDTDSource getDTDSource();
374
375 } // interface XMLDTDHandler
376
Popular Tags