001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xerces.xni;
019:
020: import org.apache.xerces.xni.parser.XMLDocumentSource;
021:
022: /**
023: * The document handler interface defines callback methods to report
024: * information items in XML documents. Parser components interested in
025: * document information implement this interface and are registered
026: * as the document handler on the document source.
027: *
028: * @author Andy Clark, IBM
029: *
030: * @version $Id: XMLDocumentHandler.java 447247 2006-09-18 05:23:52Z mrglavas $
031: */
032: public interface XMLDocumentHandler {
033:
034: //
035: // XMLDocumentHandler methods
036: //
037:
038: /**
039: * The start of the document.
040: *
041: * @param locator The document locator, or null if the document
042: * location cannot be reported during the parsing
043: * of this document. However, it is <em>strongly</em>
044: * recommended that a locator be supplied that can
045: * at least report the system identifier of the
046: * document.
047: * @param encoding The auto-detected IANA encoding name of the entity
048: * stream. This value will be null in those situations
049: * where the entity encoding is not auto-detected (e.g.
050: * internal entities or a document entity that is
051: * parsed from a java.io.Reader).
052: * @param namespaceContext
053: * The namespace context in effect at the
054: * start of this document.
055: * This object represents the current context.
056: * Implementors of this class are responsible
057: * for copying the namespace bindings from the
058: * the current context (and its parent contexts)
059: * if that information is important.
060: *
061: * @param augs Additional information that may include infoset augmentations
062: * @exception XNIException
063: * Thrown by handler to signal an error.
064: */
065: public void startDocument(XMLLocator locator, String encoding,
066: NamespaceContext namespaceContext, Augmentations augs)
067: throws XNIException;
068:
069: /**
070: * Notifies of the presence of an XMLDecl line in the document. If
071: * present, this method will be called immediately following the
072: * startDocument call.
073: *
074: * @param version The XML version.
075: * @param encoding The IANA encoding name of the document, or null if
076: * not specified.
077: * @param standalone The standalone value, or null if not specified.
078: * @param augs Additional information that may include infoset augmentations
079: *
080: * @exception XNIException
081: * Thrown by handler to signal an error.
082: */
083: public void xmlDecl(String version, String encoding,
084: String standalone, Augmentations augs) throws XNIException;
085:
086: /**
087: * Notifies of the presence of the DOCTYPE line in the document.
088: *
089: * @param rootElement
090: * The name of the root element.
091: * @param publicId The public identifier if an external DTD or null
092: * if the external DTD is specified using SYSTEM.
093: * @param systemId The system identifier if an external DTD, null
094: * otherwise.
095: * @param augs Additional information that may include infoset augmentations
096: *
097: * @exception XNIException
098: * Thrown by handler to signal an error.
099: */
100: public void doctypeDecl(String rootElement, String publicId,
101: String systemId, Augmentations augs) 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)
113: throws XNIException;
114:
115: /**
116: * A processing instruction. Processing instructions consist of a
117: * target name and, optionally, text data. The data is only meaningful
118: * to the application.
119: * <p>
120: * Typically, a processing instruction's data will contain a series
121: * of pseudo-attributes. These pseudo-attributes follow the form of
122: * element attributes but are <strong>not</strong> parsed or presented
123: * to the application as anything other than text. The application is
124: * responsible for parsing the data.
125: *
126: * @param target The target.
127: * @param data The data or null if none specified.
128: * @param augs Additional information that may include infoset augmentations
129: *
130: * @exception XNIException
131: * Thrown by handler to signal an error.
132: */
133: public void processingInstruction(String target, XMLString data,
134: Augmentations augs) throws XNIException;
135:
136: /**
137: * The start of an element.
138: *
139: * @param element The name of the element.
140: * @param attributes The element attributes.
141: * @param augs Additional information that may include infoset augmentations
142: *
143: * @exception XNIException
144: * Thrown by handler to signal an error.
145: */
146: public void startElement(QName element, XMLAttributes attributes,
147: Augmentations augs) throws XNIException;
148:
149: /**
150: * An empty element.
151: *
152: * @param element The name of the element.
153: * @param attributes The element attributes.
154: * @param augs Additional information that may include infoset augmentations
155: *
156: * @exception XNIException
157: * Thrown by handler to signal an error.
158: */
159: public void emptyElement(QName element, XMLAttributes attributes,
160: Augmentations augs) throws XNIException;
161:
162: /**
163: * This method notifies the start of a general entity.
164: * <p>
165: * <strong>Note:</strong> This method is not called for entity references
166: * appearing as part of attribute values.
167: *
168: * @param name The name of the general entity.
169: * @param identifier The resource identifier.
170: * @param encoding The auto-detected IANA encoding name of the entity
171: * stream. This value will be null in those situations
172: * where the entity encoding is not auto-detected (e.g.
173: * internal entities or a document entity that is
174: * parsed from a java.io.Reader).
175: * @param augs Additional information that may include infoset augmentations
176: *
177: * @exception XNIException Thrown by handler to signal an error.
178: */
179: public void startGeneralEntity(String name,
180: XMLResourceIdentifier identifier, 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,
202: Augmentations augs) throws XNIException;
203:
204: /**
205: * This method notifies the end of a general entity.
206: * <p>
207: * <strong>Note:</strong> This method is not called for entity references
208: * appearing as part of attribute values.
209: *
210: * @param name The name of the entity.
211: * @param augs Additional information that may include infoset augmentations
212: *
213: * @exception XNIException
214: * Thrown by handler to signal an error.
215: */
216: public void endGeneralEntity(String name, Augmentations augs)
217: throws XNIException;
218:
219: /**
220: * Character content.
221: *
222: * @param text The content.
223: * @param augs Additional information that may include infoset augmentations
224: *
225: * @exception XNIException
226: * Thrown by handler to signal an error.
227: */
228: public void characters(XMLString text, Augmentations augs)
229: throws XNIException;
230:
231: /**
232: * Ignorable whitespace. For this method to be called, the document
233: * source must have some way of determining that the text containing
234: * only whitespace characters should be considered ignorable. For
235: * example, the validator can determine if a length of whitespace
236: * characters in the document are ignorable based on the element
237: * content model.
238: *
239: * @param text The ignorable whitespace.
240: * @param augs Additional information that may include infoset augmentations
241: *
242: * @exception XNIException
243: * Thrown by handler to signal an error.
244: */
245: public void ignorableWhitespace(XMLString text, Augmentations augs)
246: throws XNIException;
247:
248: /**
249: * The end of an element.
250: *
251: * @param element The name of the element.
252: * @param augs Additional information that may include infoset augmentations
253: *
254: * @exception XNIException
255: * Thrown by handler to signal an error.
256: */
257: public void endElement(QName element, Augmentations augs)
258: throws XNIException;
259:
260: /**
261: * The start of a CDATA section.
262: *
263: * @param augs Additional information that may include infoset augmentations
264: *
265: * @exception XNIException
266: * Thrown by handler to signal an error.
267: */
268: public void startCDATA(Augmentations augs) throws XNIException;
269:
270: /**
271: * The end of a CDATA section.
272: *
273: * @param augs Additional information that may include infoset augmentations
274: *
275: * @exception XNIException
276: * Thrown by handler to signal an error.
277: */
278: public void endCDATA(Augmentations augs) throws XNIException;
279:
280: /**
281: * The end of the document.
282: *
283: * @param augs Additional information that may include infoset augmentations
284: *
285: * @exception XNIException
286: * Thrown by handler to signal an error.
287: */
288: public void endDocument(Augmentations augs) throws XNIException;
289:
290: /** Sets the document source. */
291: public void setDocumentSource(XMLDocumentSource source);
292:
293: /** Returns the document source. */
294: public XMLDocumentSource getDocumentSource();
295:
296: } // interface XMLDocumentHandler
|