XMLDocumentHandler


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.XMLDocumentSource;
61  
62  /**
63   * The document handler interface defines callback methods to report
64   * information items in XML documents. Parser components interested in 
65   * document information implement this interface and are registered
66   * as the document handler on the document source.
67   *
68   * @author Andy Clark, IBM
69   *
70   * @version $Id: XMLDocumentHandler.java,v 1.10 2002/12/16 01:26:21 elena Exp $
71   */
72  public interface XMLDocumentHandler {
73  
74      //
75      // XMLDocumentHandler methods
76      //
77  
78      /**
79       * The start of the document.
80       * 
81       * @param locator  The document locator, or null if the document
82       *                 location cannot be reported during the parsing
83       *                 of this document. However, it is <em>strongly</em>
84       *                 recommended that a locator be supplied that can
85       *                 at least report the system identifier of the
86       *                 document.
87       * @param encoding The auto-detected IANA encoding name of the entity
88       *                 stream. This value will be null in those situations
89       *                 where the entity encoding is not auto-detected (e.g.
90       *                 internal entities or a document entity that is
91       *                 parsed from a java.io.Reader).
92       * @param namespaceContext
93       *                 The namespace context in effect at the
94       *                 start of this document.
95       *                 This object represents the current context.
96       *                 Implementors of this class are responsible
97       *                 for copying the namespace bindings from the
98       *                 the current context (and its parent contexts)
99       *                 if that information is important.
100      *                 
101      * @param augs     Additional information that may include infoset augmentations
102      * @exception XNIException
103      *                   Thrown by handler to signal an error.
104      */
105     public void startDocument(XMLLocator locator, String   encoding, 
106                               NamespaceContext namespaceContext,
107                               Augmentations augs) 
108         throws XNIException;
109 
110     /**
111      * Notifies of the presence of an XMLDecl line in the document. If
112      * present, this method will be called immediately following the
113      * startDocument call.
114      * 
115      * @param version    The XML version.
116      * @param encoding   The IANA encoding name of the document, or null if
117      *                   not specified.
118      * @param standalone The standalone value, or null if not specified.
119      * @param augs       Additional information that may include infoset augmentations
120      *                   
121      * @exception XNIException
122      *                   Thrown by handler to signal an error.
123      */
124     public void xmlDecl(String   version, String   encoding, String   standalone, Augmentations augs)
125         throws XNIException;
126 
127     /**
128      * Notifies of the presence of the DOCTYPE line in the document.
129      * 
130      * @param rootElement
131      *                 The name of the root element.
132      * @param publicId The public identifier if an external DTD or null
133      *                 if the external DTD is specified using SYSTEM.
134      * @param systemId The system identifier if an external DTD, null
135      *                 otherwise.
136      * @param augs     Additional information that may include infoset augmentations
137      *                 
138      * @exception XNIException
139      *                   Thrown by handler to signal an error.
140      */
141     public void doctypeDecl(String   rootElement, String   publicId, String   systemId, Augmentations augs)
142         throws XNIException;
143 
144     /**
145      * A comment.
146      * 
147      * @param text   The text in the comment.
148      * @param augs   Additional information that may include infoset augmentations
149      *               
150      * @exception XNIException
151      *                   Thrown by application to signal an error.
152      */
153     public void comment(XMLString text, Augmentations augs) throws XNIException;
154 
155     /**
156      * A processing instruction. Processing instructions consist of a
157      * target name and, optionally, text data. The data is only meaningful
158      * to the application.
159      * <p>
160      * Typically, a processing instruction's data will contain a series
161      * of pseudo-attributes. These pseudo-attributes follow the form of
162      * element attributes but are <strong>not</strong> parsed or presented
163      * to the application as anything other than text. The application is
164      * responsible for parsing the data.
165      * 
166      * @param target The target.
167      * @param data   The data or null if none specified.
168      * @param augs   Additional information that may include infoset augmentations
169      *               
170      * @exception XNIException
171      *                   Thrown by handler to signal an error.
172      */
173     public void processingInstruction(String   target, XMLString data, Augmentations augs)
174         throws XNIException;
175 
176     /**
177      * The start of an element.
178      * 
179      * @param element    The name of the element.
180      * @param attributes The element attributes.
181      * @param augs       Additional information that may include infoset augmentations
182      *                   
183      * @exception XNIException
184      *                   Thrown by handler to signal an error.
185      */
186     public void startElement(QName element, XMLAttributes attributes, Augmentations augs)
187         throws XNIException;
188 
189     /**
190      * An empty element.
191      * 
192      * @param element    The name of the element.
193      * @param attributes The element attributes.
194      * @param augs       Additional information that may include infoset augmentations
195      *                   
196      * @exception XNIException
197      *                   Thrown by handler to signal an error.
198      */
199     public void emptyElement(QName element, XMLAttributes attributes, Augmentations augs)
200         throws XNIException;
201 
202     /**
203      * This method notifies the start of a general entity.
204      * <p>
205      * <strong>Note:</strong> This method is not called for entity references
206      * appearing as part of attribute values.
207      * 
208      * @param name     The name of the general entity.
209      * @param identifier The resource identifier.
210      * @param encoding The auto-detected IANA encoding name of the entity
211      *                 stream. This value will be null in those situations
212      *                 where the entity encoding is not auto-detected (e.g.
213      *                 internal entities or a document entity that is
214      *                 parsed from a java.io.Reader).
215      * @param augs     Additional information that may include infoset augmentations
216      *                 
217      * @exception XNIException Thrown by handler to signal an error.
218      */
219     public void startGeneralEntity(String   name, 
220                                    XMLResourceIdentifier identifier,
221                                    String   encoding,
222                                    Augmentations augs) throws XNIException;
223 
224     /**
225      * Notifies of the presence of a TextDecl line in an entity. If present,
226      * this method will be called immediately following the startEntity call.
227      * <p>
228      * <strong>Note:</strong> This method will never be called for the
229      * document entity; it is only called for external general entities
230      * referenced in document content.
231      * <p>
232      * <strong>Note:</strong> This method is not called for entity references
233      * appearing as part of attribute values.
234      * 
235      * @param version  The XML version, or null if not specified.
236      * @param encoding The IANA encoding name of the entity.
237      * @param augs     Additional information that may include infoset augmentations
238      *                 
239      * @exception XNIException
240      *                   Thrown by handler to signal an error.
241      */
242     public void textDecl(String   version, String   encoding, Augmentations augs) throws XNIException;
243 
244     /**
245      * This method notifies the end of a general entity.
246      * <p>
247      * <strong>Note:</strong> This method is not called for entity references
248      * appearing as part of attribute values.
249      * 
250      * @param name   The name of the entity.
251      * @param augs   Additional information that may include infoset augmentations
252      *               
253      * @exception XNIException
254      *                   Thrown by handler to signal an error.
255      */
256     public void endGeneralEntity(String   name, Augmentations augs) throws XNIException;
257 
258     /**
259      * Character content.
260      * 
261      * @param text   The content.
262      * @param augs   Additional information that may include infoset augmentations
263      *               
264      * @exception XNIException
265      *                   Thrown by handler to signal an error.
266      */
267     public void characters(XMLString text, Augmentations augs) throws XNIException;
268 
269     /**
270      * Ignorable whitespace. For this method to be called, the document
271      * source must have some way of determining that the text containing
272      * only whitespace characters should be considered ignorable. For
273      * example, the validator can determine if a length of whitespace
274      * characters in the document are ignorable based on the element
275      * content model.
276      * 
277      * @param text   The ignorable whitespace.
278      * @param augs   Additional information that may include infoset augmentations
279      *               
280      * @exception XNIException
281      *                   Thrown by handler to signal an error.
282      */
283     public void ignorableWhitespace(XMLString text, Augmentations augs) throws XNIException;
284 
285     /**
286      * The end of an element.
287      * 
288      * @param element The name of the element.
289      * @param augs    Additional information that may include infoset augmentations
290      *                
291      * @exception XNIException
292      *                   Thrown by handler to signal an error.
293      */
294     public void endElement(QName element, Augmentations augs) throws XNIException;
295 
296     /**
297      * The start of a CDATA section.
298      * 
299      * @param augs   Additional information that may include infoset augmentations
300      *               
301      * @exception XNIException
302      *                   Thrown by handler to signal an error.
303      */
304     public void startCDATA(Augmentations augs) throws XNIException;
305 
306     /**
307      * The end of a CDATA section.
308      * 
309      * @param augs   Additional information that may include infoset augmentations
310      *               
311      * @exception XNIException
312      *                   Thrown by handler to signal an error.
313      */
314     public void endCDATA(Augmentations augs) throws XNIException;
315 
316     /**
317      * The end of the document.
318      * 
319      * @param augs   Additional information that may include infoset augmentations
320      *               
321      * @exception XNIException
322      *                   Thrown by handler to signal an error.
323      */
324     public void endDocument(Augmentations augs) throws XNIException;
325 
326 
327     /** Sets the document source. */
328     public void setDocumentSource(XMLDocumentSource source);
329 
330 
331     /** Returns the document source. */
332     public XMLDocumentSource getDocumentSource();
333 
334 } // interface XMLDocumentHandler
335
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags