← Back to branch summary

~vcs-imports/xena/trunk

« back to all changes in this revision

Viewing changes to ext/src/xerces-2_9_1/src/org/apache/xerces/xni/XMLDocumentHandler.java

  • Committer: matthewoliver
  • Date: 2009-12-10 03:18:07 UTC
  • Revision ID: vcs-imports@canonical.com-20091210031807-l086qguzdlljtkl9
Merged Xena Testing into Xena Stable for the Xena 5 release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
ext/src/xerces-2_9_1/src/org/apache/xerces/xni/XMLDocumentHandler.java
 
1
/*
 
2
 * Licensed to the Apache Software Foundation (ASF) under one or more
 
3
 * contributor license agreements.  See the NOTICE file distributed with
 
4
 * this work for additional information regarding copyright ownership.
 
5
 * The ASF licenses this file to You under the Apache License, Version 2.0
 
6
 * (the "License"); you may not use this file except in compliance with
 
7
 * the License.  You may obtain a copy of the License at
 
8
 * 
 
9
 *      http://www.apache.org/licenses/LICENSE-2.0
 
10
 * 
 
11
 * Unless required by applicable law or agreed to in writing, software
 
12
 * distributed under the License is distributed on an "AS IS" BASIS,
 
13
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
14
 * See the License for the specific language governing permissions and
 
15
 * limitations under the License.
 
16
 */
 
17
 
 
18
package org.apache.xerces.xni;
 
19
 
 
20
import org.apache.xerces.xni.parser.XMLDocumentSource;
 
21
 
 
22
/**
 
23
 * The document handler interface defines callback methods to report
 
24
 * information items in XML documents. Parser components interested in 
 
25
 * document information implement this interface and are registered
 
26
 * as the document handler on the document source.
 
27
 *
 
28
 * @author Andy Clark, IBM
 
29
 *
 
30
 * @version $Id: XMLDocumentHandler.java,v 1.2 2009/12/10 03:18:46 matthewoliver Exp $
 
31
 */
 
32
public interface XMLDocumentHandler {
 
33
 
 
34
    //
 
35
    // XMLDocumentHandler methods
 
36
    //
 
37
 
 
38
    /**
 
39
     * The start of the document.
 
40
     * 
 
41
     * @param locator  The document locator, or null if the document
 
42
     *                 location cannot be reported during the parsing
 
43
     *                 of this document. However, it is <em>strongly</em>
 
44
     *                 recommended that a locator be supplied that can
 
45
     *                 at least report the system identifier of the
 
46
     *                 document.
 
47
     * @param encoding The auto-detected IANA encoding name of the entity
 
48
     *                 stream. This value will be null in those situations
 
49
     *                 where the entity encoding is not auto-detected (e.g.
 
50
     *                 internal entities or a document entity that is
 
51
     *                 parsed from a java.io.Reader).
 
52
     * @param namespaceContext
 
53
     *                 The namespace context in effect at the
 
54
     *                 start of this document.
 
55
     *                 This object represents the current context.
 
56
     *                 Implementors of this class are responsible
 
57
     *                 for copying the namespace bindings from the
 
58
     *                 the current context (and its parent contexts)
 
59
     *                 if that information is important.
 
60
     *                 
 
61
     * @param augs     Additional information that may include infoset augmentations
 
62
     * @exception XNIException
 
63
     *                   Thrown by handler to signal an error.
 
64
     */
 
65
    public void startDocument(XMLLocator locator, String encoding, 
 
66
                              NamespaceContext namespaceContext,
 
67
                              Augmentations augs) 
 
68
        throws XNIException;
 
69
 
 
70
    /**
 
71
     * Notifies of the presence of an XMLDecl line in the document. If
 
72
     * present, this method will be called immediately following the
 
73
     * startDocument call.
 
74
     * 
 
75
     * @param version    The XML version.
 
76
     * @param encoding   The IANA encoding name of the document, or null if
 
77
     *                   not specified.
 
78
     * @param standalone The standalone value, or null if not specified.
 
79
     * @param augs       Additional information that may include infoset augmentations
 
80
     *                   
 
81
     * @exception XNIException
 
82
     *                   Thrown by handler to signal an error.
 
83
     */
 
84
    public void xmlDecl(String version, String encoding, String standalone, Augmentations augs)
 
85
        throws XNIException;
 
86
 
 
87
    /**
 
88
     * Notifies of the presence of the DOCTYPE line in the document.
 
89
     * 
 
90
     * @param rootElement
 
91
     *                 The name of the root element.
 
92
     * @param publicId The public identifier if an external DTD or null
 
93
     *                 if the external DTD is specified using SYSTEM.
 
94
     * @param systemId The system identifier if an external DTD, null
 
95
     *                 otherwise.
 
96
     * @param augs     Additional information that may include infoset augmentations
 
97
     *                 
 
98
     * @exception XNIException
 
99
     *                   Thrown by handler to signal an error.
 
100
     */
 
101
    public void doctypeDecl(String rootElement, String publicId, String systemId, Augmentations augs)
 
102
        throws XNIException;
 
103
 
 
104
    /**
 
105
     * A comment.
 
106
     * 
 
107
     * @param text   The text in the comment.
 
108
     * @param augs   Additional information that may include infoset augmentations
 
109
     *               
 
110
     * @exception XNIException
 
111
     *                   Thrown by application to signal an error.
 
112
     */
 
113
    public void comment(XMLString text, Augmentations augs) 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, Augmentations augs)
 
134
        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, Augmentations augs)
 
147
        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, Augmentations augs)
 
160
        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,
 
181
                                   String encoding,
 
182
                                   Augmentations augs) throws XNIException;
 
183
 
 
184
    /**
 
185
     * Notifies of the presence of a TextDecl line in an entity. If present,
 
186
     * this method will be called immediately following the startEntity call.
 
187
     * <p>
 
188
     * <strong>Note:</strong> This method will never be called for the
 
189
     * document entity; it is only called for external general entities
 
190
     * referenced in document content.
 
191
     * <p>
 
192
     * <strong>Note:</strong> This method is not called for entity references
 
193
     * appearing as part of attribute values.
 
194
     * 
 
195
     * @param version  The XML version, or null if not specified.
 
196
     * @param encoding The IANA encoding name of the entity.
 
197
     * @param augs     Additional information that may include infoset augmentations
 
198
     *                 
 
199
     * @exception XNIException
 
200
     *                   Thrown by handler to signal an error.
 
201
     */
 
202
    public void textDecl(String version, String encoding, 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) throws XNIException;
 
217
 
 
218
    /**
 
219
     * Character content.
 
220
     * 
 
221
     * @param text   The content.
 
222
     * @param augs   Additional information that may include infoset augmentations
 
223
     *               
 
224
     * @exception XNIException
 
225
     *                   Thrown by handler to signal an error.
 
226
     */
 
227
    public void characters(XMLString text, Augmentations augs) throws XNIException;
 
228
 
 
229
    /**
 
230
     * Ignorable whitespace. For this method to be called, the document
 
231
     * source must have some way of determining that the text containing
 
232
     * only whitespace characters should be considered ignorable. For
 
233
     * example, the validator can determine if a length of whitespace
 
234
     * characters in the document are ignorable based on the element
 
235
     * content model.
 
236
     * 
 
237
     * @param text   The ignorable whitespace.
 
238
     * @param augs   Additional information that may include infoset augmentations
 
239
     *               
 
240
     * @exception XNIException
 
241
     *                   Thrown by handler to signal an error.
 
242
     */
 
243
    public void ignorableWhitespace(XMLString text, Augmentations augs) throws XNIException;
 
244
 
 
245
    /**
 
246
     * The end of an element.
 
247
     * 
 
248
     * @param element The name of the element.
 
249
     * @param augs    Additional information that may include infoset augmentations
 
250
     *                
 
251
     * @exception XNIException
 
252
     *                   Thrown by handler to signal an error.
 
253
     */
 
254
    public void endElement(QName element, Augmentations augs) throws XNIException;
 
255
 
 
256
    /**
 
257
     * The start of a CDATA section.
 
258
     * 
 
259
     * @param augs   Additional information that may include infoset augmentations
 
260
     *               
 
261
     * @exception XNIException
 
262
     *                   Thrown by handler to signal an error.
 
263
     */
 
264
    public void startCDATA(Augmentations augs) throws XNIException;
 
265
 
 
266
    /**
 
267
     * The end of a CDATA section.
 
268
     * 
 
269
     * @param augs   Additional information that may include infoset augmentations
 
270
     *               
 
271
     * @exception XNIException
 
272
     *                   Thrown by handler to signal an error.
 
273
     */
 
274
    public void endCDATA(Augmentations augs) throws XNIException;
 
275
 
 
276
    /**
 
277
     * The end of the document.
 
278
     * 
 
279
     * @param augs   Additional information that may include infoset augmentations
 
280
     *               
 
281
     * @exception XNIException
 
282
     *                   Thrown by handler to signal an error.
 
283
     */
 
284
    public void endDocument(Augmentations augs) throws XNIException;
 
285
 
 
286
 
 
287
    /** Sets the document source. */
 
288
    public void setDocumentSource(XMLDocumentSource source);
 
289
 
 
290
 
 
291
    /** Returns the document source. */
 
292
    public XMLDocumentSource getDocumentSource();
 
293
 
 
294
} // interface XMLDocumentHandler