001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 2001, 2002 The Apache Software Foundation. All rights
006: * reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Apache Software Foundation (http://www.apache.org/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Xerces" and "Apache Software Foundation" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation and was
052: * originally based on software copyright (c) 1999, International
053: * Business Machines, Inc., http://www.apache.org. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package com.sun.xml.stream.xerces.xni;
059:
060: /**
061: * This handler interface contains methods necessary to receive
062: * information about document elements and content.
063: * <p>
064: * <strong>Note:</strong> Some of these methods overlap methods
065: * found in the XMLDocumentHandler interface.
066: *
067: * @see XMLDocumentHandler
068: *
069: * @author Andy Clark, IBM
070: * @version $Id: XMLDocumentFragmentHandler.java,v 1.2 2006/04/01 06:01:45 jeffsuttor Exp $
071: */
072: public interface XMLDocumentFragmentHandler {
073:
074: //
075: // XMLDocumentFragmentHandler methods
076: //
077:
078: /**
079: * The start of the document fragment.
080: *
081: * @param locator The document locator, or null if the
082: * document location cannot be reported
083: * during the parsing of this fragment.
084: * However, it is <em>strongly</em>
085: * recommended that a locator be supplied
086: * that can at least report the base
087: * system identifier.
088: * @param namespaceContext The namespace context in effect at the
089: * start of this document fragment. This
090: * object only represents the current context.
091: * Implementors of this class are responsible
092: * for copying the namespace bindings from the
093: * the current context (and its parent contexts)
094: * if that information is important.
095: * @param augmentations Additional information that may include infoset
096: * augmentations.
097: *
098: * @throws XNIException Thrown by handler to signal an error.
099: */
100: public void startDocumentFragment(XMLLocator locator,
101: NamespaceContext namespaceContext,
102: Augmentations augmentations) throws XNIException;
103:
104: /**
105: * This method notifies the start of a general entity.
106: * <p>
107: * <strong>Note:</strong> This method is not called for entity references
108: * appearing as part of attribute values.
109: *
110: * @param name The name of the general entity.
111: * @param identifier The resource identifier.
112: * @param encoding The auto-detected IANA encoding name of the entity
113: * stream. This value will be null in those situations
114: * where the entity encoding is not auto-detected (e.g.
115: * internal entities or a document entity that is
116: * parsed from a java.io.Reader).
117: * @param augmentations Additional information that may include infoset
118: * augmentations.
119: *
120: * @throws XNIException Thrown by handler to signal an error.
121: */
122: public void startGeneralEntity(String name,
123: XMLResourceIdentifier identifier, String encoding,
124: Augmentations augmentations) throws XNIException;
125:
126: /**
127: * Notifies of the presence of a TextDecl line in an entity. If present,
128: * this method will be called immediately following the startEntity call.
129: * <p>
130: * <strong>Note:</strong> This method will never be called for the
131: * document entity; it is only called for external general entities
132: * referenced in document content.
133: * <p>
134: * <strong>Note:</strong> This method is not called for entity references
135: * appearing as part of attribute values.
136: *
137: * @param version The XML version, or null if not specified.
138: * @param encoding The IANA encoding name of the entity.
139: * @param augmentations Additional information that may include infoset
140: * augmentations.
141: *
142: * @throws XNIException Thrown by handler to signal an error.
143: */
144: public void textDecl(String version, String encoding,
145: Augmentations augmentations) throws XNIException;
146:
147: /**
148: * This method notifies the end of a general entity.
149: * <p>
150: * <strong>Note:</strong> This method is not called for entity references
151: * appearing as part of attribute values.
152: *
153: * @param name The name of the general entity.
154: * @param augmentations Additional information that may include infoset
155: * augmentations.
156: *
157: * @throws XNIException Thrown by handler to signal an error.
158: */
159: public void endGeneralEntity(String name,
160: Augmentations augmentations) throws XNIException;
161:
162: /**
163: * A comment.
164: *
165: * @param text The text in the comment.
166: * @param augmentations Additional information that may include infoset
167: * augmentations.
168: *
169: * @throws XNIException Thrown by application to signal an error.
170: */
171: public void comment(XMLString text, Augmentations augmentations)
172: throws XNIException;
173:
174: /**
175: * A processing instruction. Processing instructions consist of a
176: * target name and, optionally, text data. The data is only meaningful
177: * to the application.
178: * <p>
179: * Typically, a processing instruction's data will contain a series
180: * of pseudo-attributes. These pseudo-attributes follow the form of
181: * element attributes but are <strong>not</strong> parsed or presented
182: * to the application as anything other than text. The application is
183: * responsible for parsing the data.
184: *
185: * @param target The target.
186: * @param data The data or null if none specified.
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 processingInstruction(String target, XMLString data,
193: Augmentations augmentations) throws XNIException;
194:
195: /**
196: * The start of a namespace prefix mapping. This method will only be
197: * called when namespace processing is enabled.
198: *
199: * @param prefix The namespace prefix.
200: * @param uri The URI bound to the prefix.
201: * @param augmentations Additional information that may include infoset
202: * augmentations.
203: *
204: * @throws XNIException Thrown by handler to signal an error.
205: */
206: public void startPrefixMapping(String prefix, String uri,
207: Augmentations augmentations) throws XNIException;
208:
209: /**
210: * The start of an element.
211: *
212: * @param element The name of the element.
213: * @param attributes The element attributes.
214: * @param augmentations Additional information that may include infoset
215: * augmentations.
216: *
217: * @throws XNIException Thrown by handler to signal an error.
218: */
219: public void startElement(QName element, XMLAttributes attributes,
220: Augmentations augmentations) throws XNIException;
221:
222: /**
223: * An empty element.
224: *
225: * @param element The name of the element.
226: * @param attributes The element attributes.
227: * @param augmentations Additional information that may include infoset
228: * augmentations.
229: *
230: * @throws XNIException Thrown by handler to signal an error.
231: */
232: public void emptyElement(QName element, XMLAttributes attributes,
233: Augmentations augmentations) throws XNIException;
234:
235: /**
236: * Character content.
237: *
238: * @param text The content.
239: * @param augmentations Additional information that may include infoset
240: * augmentations.
241: *
242: * @throws XNIException Thrown by handler to signal an error.
243: */
244: public void characters(XMLString text, Augmentations augmentations)
245: throws XNIException;
246:
247: /**
248: * Ignorable whitespace. For this method to be called, the document
249: * source must have some way of determining that the text containing
250: * only whitespace characters should be considered ignorable. For
251: * example, the validator can determine if a length of whitespace
252: * characters in the document are ignorable based on the element
253: * content model.
254: *
255: * @param text The ignorable whitespace.
256: * @param augmentations Additional information that may include infoset
257: * augmentations.
258: *
259: * @throws XNIException Thrown by handler to signal an error.
260: */
261: public void ignorableWhitespace(XMLString text,
262: Augmentations augmentations) throws XNIException;
263:
264: /**
265: * The end of an element.
266: *
267: * @param element The name of the element.
268: * @param augmentations Additional information that may include infoset
269: * augmentations.
270: *
271: * @throws XNIException Thrown by handler to signal an error.
272: */
273: public void endElement(QName element, Augmentations augmentations)
274: throws XNIException;
275:
276: /**
277: * The end of a namespace prefix mapping. This method will only be
278: * called when namespace processing is enabled.
279: *
280: * @param prefix The namespace prefix.
281: * @param augmentations Additional information that may include infoset
282: * augmentations.
283: *
284: * @throws XNIException Thrown by handler to signal an error.
285: */
286: public void endPrefixMapping(String prefix,
287: Augmentations augmentations) throws XNIException;
288:
289: /**
290: * The start of a CDATA section.
291: *
292: * @param augmentations Additional information that may include infoset
293: * augmentations.
294: *
295: * @throws XNIException Thrown by handler to signal an error.
296: */
297: public void startCDATA(Augmentations augmentations)
298: throws XNIException;
299:
300: /**
301: * The end of a CDATA section.
302: *
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 endCDATA(Augmentations augmentations)
309: throws XNIException;
310:
311: /**
312: * The end of the document fragment.
313: *
314: * @param augmentations Additional information that may include infoset
315: * augmentations.
316: *
317: * @throws XNIException Thrown by handler to signal an error.
318: */
319: public void endDocumentFragment(Augmentations augmentations)
320: throws XNIException;
321:
322: } // interface XMLDocumentFragmentHandler
|