XMLDocumentFragmentHandler


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