001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 2000-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: import com.sun.xml.stream.xerces.xni.parser.XMLDocumentSource;
061:
062: /**
063: * The document handler interface defines callback methods to report
064: * information items in XML documents. Parser components interested in
065: * document information implement this interface and are registered
066: * as the document handler on the document source.
067: *
068: * @author Andy Clark, IBM
069: *
070: * @version $Id: XMLDocumentHandler.java,v 1.2 2006/04/01 06:01:45 jeffsuttor Exp $
071: */
072: public interface XMLDocumentHandler {
073:
074: //
075: // XMLDocumentHandler methods
076: //
077:
078: /**
079: * The start of the document.
080: *
081: * @param locator The document locator, or null if the document
082: * location cannot be reported during the parsing
083: * of this document. However, it is <em>strongly</em>
084: * recommended that a locator be supplied that can
085: * at least report the system identifier of the
086: * document.
087: * @param encoding The auto-detected IANA encoding name of the entity
088: * stream. This value will be null in those situations
089: * where the entity encoding is not auto-detected (e.g.
090: * internal entities or a document entity that is
091: * parsed from a java.io.Reader).
092: * @param namespaceContext
093: * The namespace context in effect at the
094: * start of this document.
095: * This object represents the current context.
096: * Implementors of this class are responsible
097: * for copying the namespace bindings from the
098: * the current context (and its parent contexts)
099: * 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, Augmentations augs)
107: throws XNIException;
108:
109: /**
110: * Notifies of the presence of an XMLDecl line in the document. If
111: * present, this method will be called immediately following the
112: * startDocument call.
113: *
114: * @param version The XML version.
115: * @param encoding The IANA encoding name of the document, or null if
116: * not specified.
117: * @param standalone The standalone value, or null if not specified.
118: * @param augs Additional information that may include infoset augmentations
119: *
120: * @exception XNIException
121: * Thrown by handler to signal an error.
122: */
123: public void xmlDecl(String version, String encoding,
124: String standalone, Augmentations augs) throws XNIException;
125:
126: /**
127: * Notifies of the presence of the DOCTYPE line in the document.
128: *
129: * @param rootElement
130: * The name of the root element.
131: * @param publicId The public identifier if an external DTD or null
132: * if the external DTD is specified using SYSTEM.
133: * @param systemId The system identifier if an external DTD, null
134: * otherwise.
135: * @param augs Additional information that may include infoset augmentations
136: *
137: * @exception XNIException
138: * Thrown by handler to signal an error.
139: */
140: public void doctypeDecl(String rootElement, String publicId,
141: String systemId, Augmentations augs) throws XNIException;
142:
143: /**
144: * A comment.
145: *
146: * @param text The text in the comment.
147: * @param augs Additional information that may include infoset augmentations
148: *
149: * @exception XNIException
150: * Thrown by application to signal an error.
151: */
152: public void comment(XMLString text, Augmentations augs)
153: 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,
174: Augmentations augs) throws XNIException;
175:
176: /**
177: * The start of a namespace prefix mapping. This method will only be
178: * called when namespace processing is enabled.
179: * @deprecated Use <code>xni.NamespaceContext</code> in <code>startDocument()</code>.
180: * @param prefix The namespace prefix.
181: * @param uri The URI bound to the prefix.
182: * @param augs Additional information that may include infoset augmentations
183: *
184: * @exception XNIException
185: * Thrown by handler to signal an error.
186: */
187: public void startPrefixMapping(String prefix, String uri,
188: Augmentations augs) throws XNIException;
189:
190: /**
191: * The start of an element.
192: *
193: * @param element The name of the element.
194: * @param attributes The element attributes.
195: * @param augs Additional information that may include infoset augmentations
196: *
197: * @exception XNIException
198: * Thrown by handler to signal an error.
199: */
200: public void startElement(QName element, XMLAttributes attributes,
201: Augmentations augs) throws XNIException;
202:
203: /**
204: * An empty element.
205: *
206: * @param element The name of the element.
207: * @param attributes The element attributes.
208: * @param augs Additional information that may include infoset augmentations
209: *
210: * @exception XNIException
211: * Thrown by handler to signal an error.
212: */
213: public void emptyElement(QName element, XMLAttributes attributes,
214: Augmentations augs) throws XNIException;
215:
216: /**
217: * This method notifies the start of a general entity.
218: * <p>
219: * <strong>Note:</strong> This method is not called for entity references
220: * appearing as part of attribute values.
221: *
222: * @param name The name of the general entity.
223: * @param identifier The resource identifier.
224: * @param encoding The auto-detected IANA encoding name of the entity
225: * stream. This value will be null in those situations
226: * where the entity encoding is not auto-detected (e.g.
227: * internal entities or a document entity that is
228: * parsed from a java.io.Reader).
229: * @param augs Additional information that may include infoset augmentations
230: *
231: * @exception XNIException Thrown by handler to signal an error.
232: */
233: public void startGeneralEntity(String name,
234: XMLResourceIdentifier identifier, String encoding,
235: Augmentations augs) throws XNIException;
236:
237: /**
238: * Notifies of the presence of a TextDecl line in an entity. If present,
239: * this method will be called immediately following the startEntity call.
240: * <p>
241: * <strong>Note:</strong> This method will never be called for the
242: * document entity; it is only called for external general entities
243: * referenced in document content.
244: * <p>
245: * <strong>Note:</strong> This method is not called for entity references
246: * appearing as part of attribute values.
247: *
248: * @param version The XML version, or null if not specified.
249: * @param encoding The IANA encoding name of the entity.
250: * @param augs Additional information that may include infoset augmentations
251: *
252: * @exception XNIException
253: * Thrown by handler to signal an error.
254: */
255: public void textDecl(String version, String encoding,
256: Augmentations augs) throws XNIException;
257:
258: /**
259: * This method notifies the end of a general entity.
260: * <p>
261: * <strong>Note:</strong> This method is not called for entity references
262: * appearing as part of attribute values.
263: *
264: * @param name The name of the entity.
265: * @param augs Additional information that may include infoset augmentations
266: *
267: * @exception XNIException
268: * Thrown by handler to signal an error.
269: */
270: public void endGeneralEntity(String name, Augmentations augs)
271: throws XNIException;
272:
273: /**
274: * Character content.
275: *
276: * @param text The content.
277: * @param augs Additional information that may include infoset augmentations
278: *
279: * @exception XNIException
280: * Thrown by handler to signal an error.
281: */
282: public void characters(XMLString text, Augmentations augs)
283: throws XNIException;
284:
285: /**
286: * Ignorable whitespace. For this method to be called, the document
287: * source must have some way of determining that the text containing
288: * only whitespace characters should be considered ignorable. For
289: * example, the validator can determine if a length of whitespace
290: * characters in the document are ignorable based on the element
291: * content model.
292: *
293: * @param text The ignorable whitespace.
294: * @param augs Additional information that may include infoset augmentations
295: *
296: * @exception XNIException
297: * Thrown by handler to signal an error.
298: */
299: public void ignorableWhitespace(XMLString text, Augmentations augs)
300: throws XNIException;
301:
302: /**
303: * The end of an element.
304: *
305: * @param element The name of the element.
306: * @param augs Additional information that may include infoset augmentations
307: *
308: * @exception XNIException
309: * Thrown by handler to signal an error.
310: */
311: public void endElement(QName element, Augmentations augs)
312: throws XNIException;
313:
314: /**
315: * The end of a namespace prefix mapping. This method will only be
316: * called when namespace processing is enabled.
317: *
318: * @param prefix The namespace prefix.
319: * @param augs Additional information that may include infoset augmentations
320: * @deprecated Use <code>xni.NamespaceContext</code> in <code>startDocument()</code>.
321: * @exception XNIException
322: * Thrown by handler to signal an error.
323: */
324: public void endPrefixMapping(String prefix, Augmentations augs)
325: throws XNIException;
326:
327: /**
328: * The start of a CDATA section.
329: *
330: * @param augs Additional information that may include infoset augmentations
331: *
332: * @exception XNIException
333: * Thrown by handler to signal an error.
334: */
335: public void startCDATA(Augmentations augs) throws XNIException;
336:
337: /**
338: * The end of a CDATA section.
339: *
340: * @param augs Additional information that may include infoset augmentations
341: *
342: * @exception XNIException
343: * Thrown by handler to signal an error.
344: */
345: public void endCDATA(Augmentations augs) throws XNIException;
346:
347: /**
348: * The end of the document.
349: *
350: * @param augs Additional information that may include infoset augmentations
351: *
352: * @exception XNIException
353: * Thrown by handler to signal an error.
354: */
355: public void endDocument(Augmentations augs) throws XNIException;
356:
357: /** Sets the document source. */
358: public void setDocumentSource(XMLDocumentSource source);
359:
360: /** Returns the document source. */
361: public XMLDocumentSource getDocumentSource();
362:
363: } // interface XMLDocumentHandler
|