1 /*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5 /*
6 * Copyright 2001, 2002,2004 The Apache Software Foundation.
7 *
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
19 */
20
21 package com.sun.org.apache.xerces.internal.xni;
22
23 /**
24 * This handler interface contains methods necessary to receive
25 * information about document elements and content.
26 * <p>
27 * <strong>Note:</strong> Some of these methods overlap methods
28 * found in the XMLDocumentHandler interface.
29 *
30 * @see XMLDocumentHandler
31 *
32 * @author Andy Clark, IBM
33 */
34 public interface XMLDocumentFragmentHandler {
35
36 //
37 // XMLDocumentFragmentHandler methods
38 //
39
40 /**
41 * The start of the document fragment.
42 *
43 * @param locator The document locator, or null if the
44 * document location cannot be reported
45 * during the parsing of this fragment.
46 * However, it is <em>strongly</em>
47 * recommended that a locator be supplied
48 * that can at least report the base
49 * system identifier.
50 * @param namespaceContext The namespace context in effect at the
51 * start of this document fragment. This
52 * object only represents the current context.
53 * Implementors of this class are responsible
54 * for copying the namespace bindings from the
55 * the current context (and its parent contexts)
56 * if that information is important.
57 * @param augmentations Additional information that may include infoset
58 * augmentations.
59 *
60 * @throws XNIException Thrown by handler to signal an error.
61 */
62 public void startDocumentFragment(XMLLocator locator,
63 NamespaceContext namespaceContext,
64 Augmentations augmentations)
65 throws XNIException;
66
67 /**
68 * This method notifies the start of a general entity.
69 * <p>
70 * <strong>Note:</strong> This method is not called for entity references
71 * appearing as part of attribute values.
72 *
73 * @param name The name of the general entity.
74 * @param identifier The resource identifier.
75 * @param encoding The auto-detected IANA encoding name of the entity
76 * stream. This value will be null in those situations
77 * where the entity encoding is not auto-detected (e.g.
78 * internal entities or a document entity that is
79 * parsed from a java.io.Reader).
80 * @param augmentations Additional information that may include infoset
81 * augmentations.
82 *
83 * @throws XNIException Thrown by handler to signal an error.
84 */
85 public void startGeneralEntity(String name,
86 XMLResourceIdentifier identifier,
87 String encoding,
88 Augmentations augmentations) throws XNIException;
89
90 /**
91 * Notifies of the presence of a TextDecl line in an entity. If present,
92 * this method will be called immediately following the startEntity call.
93 * <p>
94 * <strong>Note:</strong> This method will never be called for the
95 * document entity; it is only called for external general entities
96 * referenced in document content.
97 * <p>
98 * <strong>Note:</strong> This method is not called for entity references
99 * appearing as part of attribute values.
100 *
101 * @param version The XML version, or null if not specified.
102 * @param encoding The IANA encoding name of the entity.
103 * @param augmentations Additional information that may include infoset
104 * augmentations.
105 *
106 * @throws XNIException Thrown by handler to signal an error.
107 */
108 public void textDecl(String version, String encoding,
109 Augmentations augmentations) throws XNIException;
110
111 /**
112 * This method notifies the end of a general entity.
113 * <p>
114 * <strong>Note:</strong> This method is not called for entity references
115 * appearing as part of attribute values.
116 *
117 * @param name The name of the general entity.
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 endGeneralEntity(String name, Augmentations augmentations)
124 throws XNIException;
125
126 /**
127 * A comment.
128 *
129 * @param text The text in the comment.
130 * @param augmentations Additional information that may include infoset
131 * augmentations.
132 *
133 * @throws XNIException Thrown by application to signal an error.
134 */
135 public void comment(XMLString text, Augmentations augmentations)
136 throws XNIException;
137
138 /**
139 * A processing instruction. Processing instructions consist of a
140 * target name and, optionally, text data. The data is only meaningful
141 * to the application.
142 * <p>
143 * Typically, a processing instruction's data will contain a series
144 * of pseudo-attributes. These pseudo-attributes follow the form of
145 * element attributes but are <strong>not</strong> parsed or presented
146 * to the application as anything other than text. The application is
147 * responsible for parsing the data.
148 *
149 * @param target The target.
150 * @param data The data or null if none specified.
151 * @param augmentations Additional information that may include infoset
152 * augmentations.
153 *
154 * @throws XNIException Thrown by handler to signal an error.
155 */
156 public void processingInstruction(String target, XMLString data,
157 Augmentations augmentations)
158 throws XNIException;
159
160 /**
161 * The start of an element.
162 *
163 * @param element The name of the element.
164 * @param attributes The element attributes.
165 * @param augmentations Additional information that may include infoset
166 * augmentations.
167 *
168 * @throws XNIException Thrown by handler to signal an error.
169 */
170 public void startElement(QName element, XMLAttributes attributes,
171 Augmentations augmentations) throws XNIException;
172
173 /**
174 * An empty element.
175 *
176 * @param element The name of the element.
177 * @param attributes The element attributes.
178 * @param augmentations Additional information that may include infoset
179 * augmentations.
180 *
181 * @throws XNIException Thrown by handler to signal an error.
182 */
183 public void emptyElement(QName element, XMLAttributes attributes,
184 Augmentations augmentations) throws XNIException;
185
186 /**
187 * Character content.
188 *
189 * @param text The content.
190 * @param augmentations Additional information that may include infoset
191 * augmentations.
192 *
193 * @throws XNIException Thrown by handler to signal an error.
194 */
195 public void characters(XMLString text, Augmentations augmentations)
196 throws XNIException;
197
198 /**
199 * Ignorable whitespace. For this method to be called, the document
200 * source must have some way of determining that the text containing
201 * only whitespace characters should be considered ignorable. For
202 * example, the validator can determine if a length of whitespace
203 * characters in the document are ignorable based on the element
204 * content model.
205 *
206 * @param text The ignorable whitespace.
207 * @param augmentations Additional information that may include infoset
208 * augmentations.
209 *
210 * @throws XNIException Thrown by handler to signal an error.
211 */
212 public void ignorableWhitespace(XMLString text,
213 Augmentations augmentations)
214 throws XNIException;
215
216 /**
217 * The end of an element.
218 *
219 * @param element The name of the element.
220 * @param augmentations Additional information that may include infoset
221 * augmentations.
222 *
223 * @throws XNIException Thrown by handler to signal an error.
224 */
225 public void endElement(QName element, Augmentations augmentations)
226 throws XNIException;
227
228 /**
229 * The start of a CDATA section.
230 *
231 * @param augmentations Additional information that may include infoset
232 * augmentations.
233 *
234 * @throws XNIException Thrown by handler to signal an error.
235 */
236 public void startCDATA(Augmentations augmentations) throws XNIException;
237
238 /**
239 * The end of a CDATA section.
240 *
241 * @param augmentations Additional information that may include infoset
242 * augmentations.
243 *
244 * @throws XNIException Thrown by handler to signal an error.
245 */
246 public void endCDATA(Augmentations augmentations) throws XNIException;
247
248 /**
249 * The end of the document fragment.
250 *
251 * @param augmentations Additional information that may include infoset
252 * augmentations.
253 *
254 * @throws XNIException Thrown by handler to signal an error.
255 */
256 public void endDocumentFragment(Augmentations augmentations)
257 throws XNIException;
258
259 } // interface XMLDocumentFragmentHandler