XMLDocumentHandler


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