XMLDTDHandler


1   /*
2    * The Apache Software License, Version 1.1
3    *
4    *
5    * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights 
6    * reserved.
7    *
8    * Redistribution and use in source and binary forms, with or without
9    * modification, are permitted provided that the following conditions
10   * are met:
11   *
12   * 1. Redistributions of source code must retain the above copyright
13   *    notice, this list of conditions and the following disclaimer. 
14   *
15   * 2. Redistributions in binary form must reproduce the above copyright
16   *    notice, this list of conditions and the following disclaimer in
17   *    the documentation and/or other materials provided with the
18   *    distribution.
19   *
20   * 3. The end-user documentation included with the redistribution,
21   *    if any, must include the following acknowledgment:  
22   *       "This product includes software developed by the
23   *        Apache Software Foundation (http://www.apache.org/)."
24   *    Alternately, this acknowledgment may appear in the software itself,
25   *    if and wherever such third-party acknowledgments normally appear.
26   *
27   * 4. The names "Xerces" and "Apache Software Foundation" must
28   *    not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written 
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation and was
52   * originally based on software copyright (c) 1999, International
53   * Business Machines, Inc., http://www.apache.org.  For more
54   * information on the Apache Software Foundation, please see
55   * <http://www.apache.org/>.
56   */
57  
58  package com.sun.org.apache.xerces.internal.xni;
59  
60  import com.sun.org.apache.xerces.internal.xni.parser.XMLDTDSource;
61  
62  /**
63   * The DTD handler interface defines callback methods to report
64   * information items in the DTD of an XML document. Parser components
65   * interested in DTD information implement this interface and are
66   * registered as the DTD handler on the DTD source.
67   *
68   * @see XMLDTDContentModelHandler
69   *
70   * @author Andy Clark, IBM
71   *
72   * @version $Id: XMLDTDHandler.java,v 1.11 2002/12/07 00:07:51 neilg Exp $
73   */
74  public interface XMLDTDHandler {
75  
76      //
77      // Constants
78      //
79  
80      /**
81       * Conditional section: INCLUDE. 
82       *
83       * @see #CONDITIONAL_IGNORE
84       */
85      public static final short CONDITIONAL_INCLUDE = 0;
86  
87      /** 
88       * Conditional section: IGNORE.
89       *
90       * @see #CONDITIONAL_INCLUDE
91       */
92      public static final short CONDITIONAL_IGNORE = 1;
93  
94      //
95      // XMLDTDHandler methods
96      //
97  
98      /**
99       * The start of the DTD.
100      *
101      * @param locator  The document locator, or null if the document
102      *                 location cannot be reported during the parsing of 
103      *                 the document DTD. However, it is <em>strongly</em>
104      *                 recommended that a locator be supplied that can 
105      *                 at least report the base system identifier of the
106      *                 DTD.
107      * @param augmentations Additional information that may include infoset
108      *                      augmentations.
109      *
110      * @throws XNIException Thrown by handler to signal an error.
111      */
112     public void startDTD(XMLLocator locator, Augmentations augmentations) 
113         throws XNIException;
114 
115     /**
116      * This method notifies of the start of a parameter entity. The parameter
117      * entity name start with a '%' character.
118      * 
119      * @param name     The name of the parameter entity.
120      * @param identifier The resource identifier.
121      * @param encoding The auto-detected IANA encoding name of the entity
122      *                 stream. This value will be null in those situations
123      *                 where the entity encoding is not auto-detected (e.g.
124      *                 internal parameter entities).
125      * @param augmentations Additional information that may include infoset
126      *                      augmentations.
127      *
128      * @throws XNIException Thrown by handler to signal an error.
129      */
130     public void startParameterEntity(String   name, 
131                                      XMLResourceIdentifier identifier,
132                                      String   encoding,
133                                      Augmentations augmentations) throws XNIException;
134 
135     /**
136      * Notifies of the presence of a TextDecl line in an entity. If present,
137      * this method will be called immediately following the startEntity call.
138      * <p>
139      * <strong>Note:</strong> This method is only called for external
140      * parameter entities referenced in the DTD.
141      * 
142      * @param version  The XML version, or null if not specified.
143      * @param encoding The IANA encoding name of the entity.
144      * @param augmentations Additional information that may include infoset
145      *                      augmentations.
146      *
147      * @throws XNIException Thrown by handler to signal an error.
148      */
149     public void textDecl(String   version, String   encoding,
150                          Augmentations augmentations) throws XNIException;
151 
152     /**
153      * This method notifies the end of a parameter entity. Parameter entity
154      * names begin with a '%' character.
155      * 
156      * @param name The name of the parameter entity.
157      * @param augmentations Additional information that may include infoset
158      *                      augmentations.
159      *
160      * @throws XNIException Thrown by handler to signal an error.
161      */
162     public void endParameterEntity(String   name, Augmentations augmentations) 
163         throws XNIException;
164 
165     /**
166      * The start of the DTD external subset.
167      * 
168      * @param identifier The resource identifier.
169      * @param augmentations
170      *                   Additional information that may include infoset
171      *                   augmentations.
172      * @exception XNIException
173      *                   Thrown by handler to signal an error.
174      */
175     public void startExternalSubset(XMLResourceIdentifier identifier, 
176                                     Augmentations augmentations) 
177         throws XNIException;
178 
179     /**
180      * The end of the DTD external subset.
181      *
182      * @param augmentations Additional information that may include infoset
183      *                      augmentations.
184      *
185      * @throws XNIException Thrown by handler to signal an error.
186      */
187     public void endExternalSubset(Augmentations augmentations) 
188         throws XNIException;
189 
190     /**
191      * A comment.
192      * 
193      * @param text The text in the comment.
194      * @param augmentations Additional information that may include infoset
195      *                      augmentations.
196      *
197      * @throws XNIException Thrown by application to signal an error.
198      */
199     public void comment(XMLString text, Augmentations augmentations) 
200         throws XNIException;
201 
202     /**
203      * A processing instruction. Processing instructions consist of a
204      * target name and, optionally, text data. The data is only meaningful
205      * to the application.
206      * <p>
207      * Typically, a processing instruction's data will contain a series
208      * of pseudo-attributes. These pseudo-attributes follow the form of
209      * element attributes but are <strong>not</strong> parsed or presented
210      * to the application as anything other than text. The application is
211      * responsible for parsing the data.
212      * 
213      * @param target The target.
214      * @param data   The data or null if none specified.
215      * @param augmentations Additional information that may include infoset
216      *                      augmentations.
217      *
218      * @throws XNIException Thrown by handler to signal an error.
219      */
220     public void processingInstruction(String   target, XMLString data,
221                                       Augmentations augmentations)
222         throws XNIException;
223 
224     /**
225      * An element declaration.
226      * 
227      * @param name         The name of the element.
228      * @param contentModel The element content model.
229      * @param augmentations Additional information that may include infoset
230      *                      augmentations.
231      *
232      * @throws XNIException Thrown by handler to signal an error.
233      */
234     public void elementDecl(String   name, String   contentModel,
235                             Augmentations augmentations)
236         throws XNIException;
237 
238     /**
239      * The start of an attribute list.
240      * 
241      * @param elementName The name of the element that this attribute
242      *                    list is associated with.
243      * @param augmentations Additional information that may include infoset
244      *                      augmentations.
245      *
246      * @throws XNIException Thrown by handler to signal an error.
247      */
248     public void startAttlist(String   elementName,
249                              Augmentations augmentations) throws XNIException;
250 
251     /**
252      * An attribute declaration.
253      * 
254      * @param elementName   The name of the element that this attribute
255      *                      is associated with.
256      * @param attributeName The name of the attribute.
257      * @param type          The attribute type. This value will be one of
258      *                      the following: "CDATA", "ENTITY", "ENTITIES",
259      *                      "ENUMERATION", "ID", "IDREF", "IDREFS", 
260      *                      "NMTOKEN", "NMTOKENS", or "NOTATION".
261      * @param enumeration   If the type has the value "ENUMERATION" or
262      *                      "NOTATION", this array holds the allowed attribute
263      *                      values; otherwise, this array is null.
264      * @param defaultType   The attribute default type. This value will be
265      *                      one of the following: "#FIXED", "#IMPLIED",
266      *                      "#REQUIRED", or null.
267      * @param defaultValue  The attribute default value, or null if no
268      *                      default value is specified.
269      * @param nonNormalizedDefaultValue  The attribute default value with no normalization 
270      *                      performed, or null if no default value is specified.
271      * @param augmentations Additional information that may include infoset
272      *                      augmentations.
273      *
274      * @throws XNIException Thrown by handler to signal an error.
275      */
276     public void attributeDecl(String   elementName, String   attributeName, 
277                               String   type, String  [] enumeration, 
278                               String   defaultType, XMLString defaultValue,
279                               XMLString nonNormalizedDefaultValue, Augmentations augmentations)
280         throws XNIException;
281 
282     /**
283      * The end of an attribute list.
284      *
285      * @param augmentations Additional information that may include infoset
286      *                      augmentations.
287      *
288      * @throws XNIException Thrown by handler to signal an error.
289      */
290     public void endAttlist(Augmentations augmentations) throws XNIException;
291 
292     /**
293      * An internal entity declaration.
294      * 
295      * @param name The name of the entity. Parameter entity names start with
296      *             '%', whereas the name of a general entity is just the 
297      *             entity name.
298      * @param text The value of the entity.
299      * @param nonNormalizedText The non-normalized value of the entity. This
300      *             value contains the same sequence of characters that was in 
301      *             the internal entity declaration, without any entity
302      *             references expanded.
303      * @param augmentations Additional information that may include infoset
304      *                      augmentations.
305      *
306      * @throws XNIException Thrown by handler to signal an error.
307      */
308     public void internalEntityDecl(String   name, XMLString text, 
309                                    XMLString nonNormalizedText,
310                                    Augmentations augmentations) 
311         throws XNIException;
312 
313     /**
314      * An external entity declaration.
315      * 
316      * @param name     The name of the entity. Parameter entity names start
317      *                 with '%', whereas the name of a general entity is just
318      *                 the entity name.
319      * @param identifier    An object containing all location information 
320      *                      pertinent to this external entity.
321      * @param augmentations Additional information that may include infoset
322      *                      augmentations.
323      *
324      * @throws XNIException Thrown by handler to signal an error.
325      */
326     public void externalEntityDecl(String   name, 
327                                    XMLResourceIdentifier identifier,
328                                    Augmentations augmentations) 
329         throws XNIException;
330 
331     /**
332      * An unparsed entity declaration.
333      * 
334      * @param name     The name of the entity.
335      * @param identifier    An object containing all location information 
336      *                      pertinent to this unparsed entity declaration.
337      * @param notation The name of the notation.
338      * @param augmentations Additional information that may include infoset
339      *                      augmentations.
340      *
341      * @throws XNIException Thrown by handler to signal an error.
342      */
343     public void unparsedEntityDecl(String   name, 
344                                    XMLResourceIdentifier identifier, 
345                                    String   notation, Augmentations augmentations) 
346         throws XNIException;
347 
348     /**
349      * A notation declaration
350      * 
351      * @param name     The name of the notation.
352      * @param identifier    An object containing all location information 
353      *                      pertinent to this notation.
354      * @param augmentations Additional information that may include infoset
355      *                      augmentations.
356      *
357      * @throws XNIException Thrown by handler to signal an error.
358      */
359     public void notationDecl(String   name, XMLResourceIdentifier identifier,
360                              Augmentations augmentations) throws XNIException;
361 
362     /**
363      * The start of a conditional section.
364      * 
365      * @param type The type of the conditional section. This value will
366      *             either be CONDITIONAL_INCLUDE or CONDITIONAL_IGNORE.
367      * @param augmentations Additional information that may include infoset
368      *                      augmentations.
369      *
370      * @throws XNIException Thrown by handler to signal an error.
371      *
372      * @see #CONDITIONAL_INCLUDE
373      * @see #CONDITIONAL_IGNORE
374      */
375     public void startConditional(short type, Augmentations augmentations) 
376         throws XNIException;
377 
378     /**
379      * Characters within an IGNORE conditional section.
380      *
381      * @param text The ignored text.
382      * @param augmentations Additional information that may include infoset
383      *                      augmentations.
384      *
385      * @throws XNIException Thrown by handler to signal an error.
386      */
387     public void ignoredCharacters(XMLString text, Augmentations augmentations) 
388         throws XNIException;
389 
390     /**
391      * The end of a conditional section.
392      *
393      * @param augmentations Additional information that may include infoset
394      *                      augmentations.
395      *
396      * @throws XNIException Thrown by handler to signal an error.
397      */
398     public void endConditional(Augmentations augmentations) throws XNIException;
399 
400     /**
401      * The end of the DTD.
402      *
403      * @param augmentations Additional information that may include infoset
404      *                      augmentations.
405      *
406      * @throws XNIException Thrown by handler to signal an error.
407      */
408     public void endDTD(Augmentations augmentations) throws XNIException;
409 
410     // set the source of this handler
411     public void setDTDSource(XMLDTDSource source);
412 
413     // return the source from which this handler derives its events
414     public XMLDTDSource getDTDSource();
415 
416 } // interface XMLDTDHandler
417
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags