XMLDocumentFragmentHandler


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