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: /**
021: * This handler interface contains methods necessary to receive
022: * information about document elements and content.
023: * <p>
024: * <strong>Note:</strong> Some of these methods overlap methods
025: * found in the XMLDocumentHandler interface.
026: *
027: * @see XMLDocumentHandler
028: *
029: * @author Andy Clark, IBM
030: * @version $Id: XMLDocumentFragmentHandler.java 447247 2006-09-18 05:23:52Z mrglavas $
031: */
032: public interface XMLDocumentFragmentHandler {
033:
034: //
035: // XMLDocumentFragmentHandler methods
036: //
037:
038: /**
039: * The start of the document fragment.
040: *
041: * @param locator The document locator, or null if the
042: * document location cannot be reported
043: * during the parsing of this fragment.
044: * However, it is <em>strongly</em>
045: * recommended that a locator be supplied
046: * that can at least report the base
047: * system identifier.
048: * @param namespaceContext The namespace context in effect at the
049: * start of this document fragment. This
050: * object only represents the current context.
051: * Implementors of this class are responsible
052: * for copying the namespace bindings from the
053: * the current context (and its parent contexts)
054: * if that information is important.
055: * @param augmentations Additional information that may include infoset
056: * augmentations.
057: *
058: * @throws XNIException Thrown by handler to signal an error.
059: */
060: public void startDocumentFragment(XMLLocator locator,
061: NamespaceContext namespaceContext,
062: Augmentations augmentations) throws XNIException;
063:
064: /**
065: * This method notifies the start of a general entity.
066: * <p>
067: * <strong>Note:</strong> This method is not called for entity references
068: * appearing as part of attribute values.
069: *
070: * @param name The name of the general entity.
071: * @param identifier The resource identifier.
072: * @param encoding The auto-detected IANA encoding name of the entity
073: * stream. This value will be null in those situations
074: * where the entity encoding is not auto-detected (e.g.
075: * internal entities or a document entity that is
076: * parsed from a java.io.Reader).
077: * @param augmentations Additional information that may include infoset
078: * augmentations.
079: *
080: * @throws XNIException Thrown by handler to signal an error.
081: */
082: public void startGeneralEntity(String name,
083: XMLResourceIdentifier identifier, String encoding,
084: Augmentations augmentations) throws XNIException;
085:
086: /**
087: * Notifies of the presence of a TextDecl line in an entity. If present,
088: * this method will be called immediately following the startEntity call.
089: * <p>
090: * <strong>Note:</strong> This method will never be called for the
091: * document entity; it is only called for external general entities
092: * referenced in document content.
093: * <p>
094: * <strong>Note:</strong> This method is not called for entity references
095: * appearing as part of attribute values.
096: *
097: * @param version The XML version, or null if not specified.
098: * @param encoding The IANA encoding name of the entity.
099: * @param augmentations Additional information that may include infoset
100: * augmentations.
101: *
102: * @throws XNIException Thrown by handler to signal an error.
103: */
104: public void textDecl(String version, String encoding,
105: Augmentations augmentations) throws XNIException;
106:
107: /**
108: * This method notifies the end of a general entity.
109: * <p>
110: * <strong>Note:</strong> This method is not called for entity references
111: * appearing as part of attribute values.
112: *
113: * @param name The name of the general entity.
114: * @param augmentations Additional information that may include infoset
115: * augmentations.
116: *
117: * @throws XNIException Thrown by handler to signal an error.
118: */
119: public void endGeneralEntity(String name,
120: Augmentations augmentations) throws XNIException;
121:
122: /**
123: * A comment.
124: *
125: * @param text The text in the comment.
126: * @param augmentations Additional information that may include infoset
127: * augmentations.
128: *
129: * @throws XNIException Thrown by application to signal an error.
130: */
131: public void comment(XMLString text, Augmentations augmentations)
132: throws XNIException;
133:
134: /**
135: * A processing instruction. Processing instructions consist of a
136: * target name and, optionally, text data. The data is only meaningful
137: * to the application.
138: * <p>
139: * Typically, a processing instruction's data will contain a series
140: * of pseudo-attributes. These pseudo-attributes follow the form of
141: * element attributes but are <strong>not</strong> parsed or presented
142: * to the application as anything other than text. The application is
143: * responsible for parsing the data.
144: *
145: * @param target The target.
146: * @param data The data or null if none specified.
147: * @param augmentations Additional information that may include infoset
148: * augmentations.
149: *
150: * @throws XNIException Thrown by handler to signal an error.
151: */
152: public void processingInstruction(String target, XMLString data,
153: Augmentations augmentations) throws XNIException;
154:
155: /**
156: * The start of an element.
157: *
158: * @param element The name of the element.
159: * @param attributes The element attributes.
160: * @param augmentations Additional information that may include infoset
161: * augmentations.
162: *
163: * @throws XNIException Thrown by handler to signal an error.
164: */
165: public void startElement(QName element, XMLAttributes attributes,
166: Augmentations augmentations) throws XNIException;
167:
168: /**
169: * An empty element.
170: *
171: * @param element The name of the element.
172: * @param attributes The element attributes.
173: * @param augmentations Additional information that may include infoset
174: * augmentations.
175: *
176: * @throws XNIException Thrown by handler to signal an error.
177: */
178: public void emptyElement(QName element, XMLAttributes attributes,
179: Augmentations augmentations) throws XNIException;
180:
181: /**
182: * Character content.
183: *
184: * @param text The content.
185: * @param augmentations Additional information that may include infoset
186: * augmentations.
187: *
188: * @throws XNIException Thrown by handler to signal an error.
189: */
190: public void characters(XMLString text, Augmentations augmentations)
191: throws XNIException;
192:
193: /**
194: * Ignorable whitespace. For this method to be called, the document
195: * source must have some way of determining that the text containing
196: * only whitespace characters should be considered ignorable. For
197: * example, the validator can determine if a length of whitespace
198: * characters in the document are ignorable based on the element
199: * content model.
200: *
201: * @param text The ignorable whitespace.
202: * @param augmentations Additional information that may include infoset
203: * augmentations.
204: *
205: * @throws XNIException Thrown by handler to signal an error.
206: */
207: public void ignorableWhitespace(XMLString text,
208: Augmentations augmentations) throws XNIException;
209:
210: /**
211: * The end of an element.
212: *
213: * @param element The name of the element.
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 endElement(QName element, Augmentations augmentations)
220: throws XNIException;
221:
222: /**
223: * The start of a CDATA section.
224: *
225: * @param augmentations Additional information that may include infoset
226: * augmentations.
227: *
228: * @throws XNIException Thrown by handler to signal an error.
229: */
230: public void startCDATA(Augmentations augmentations)
231: throws XNIException;
232:
233: /**
234: * The end of a CDATA section.
235: *
236: * @param augmentations Additional information that may include infoset
237: * augmentations.
238: *
239: * @throws XNIException Thrown by handler to signal an error.
240: */
241: public void endCDATA(Augmentations augmentations)
242: throws XNIException;
243:
244: /**
245: * The end of the document fragment.
246: *
247: * @param augmentations Additional information that may include infoset
248: * augmentations.
249: *
250: * @throws XNIException Thrown by handler to signal an error.
251: */
252: public void endDocumentFragment(Augmentations augmentations)
253: throws XNIException;
254:
255: } // interface XMLDocumentFragmentHandler
|