1 <html><head>
2 <!-- $Id: package.html,v 1.3 2007/10/02 19:32:24 ndw Exp $ -->
3 </head><body>
4
5 <p> This package provides the core SAX APIs.
6 Some SAX1 APIs are deprecated to encourage integration of
7 namespace-awareness into designs of new applications
8 and into maintenance of existing infrastructure. </p>
9
10 <p>See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a>
11 for more information about SAX.</p>
12
13
14 <h2> SAX2 Standard Feature Flags </h2>
15
16 <p> One of the essential characteristics of SAX2 is that it added
17 feature flags which can be used to examine and perhaps modify
18 parser modes, in particular modes such as validation.
19 Since features are identified by (absolute) URIs, anyone
20 can define such features.
21 Currently defined standard feature URIs have the prefix
22 <code>http://xml.org/sax/features/</code> before an identifier such as
23 <code>validation</code>. Turn features on or off using
24 <em>setFeature</em>. Those standard identifiers are: </p>
25
26
27 <table class="striped">
28 <caption>SAX2 Standard Features </caption>
29 <thead>
30 <tr>
31 <th>Feature ID</th>
32 <th>Access</th>
33 <th>Default</th>
34 <th>Description</th>
35 </tr>
36 </thead>
37
38 <tbody>
39 <tr>
40 <td>external-general-entities</td>
41 <td><em>read/write</em></td>
42 <td><em>unspecified</em></td>
43 <td> Reports whether this parser processes external
44 general entities; always true if validating.
45 </td>
46 </tr>
47
48 <tr>
49 <td>external-parameter-entities</td>
50 <td><em>read/write</em></td>
51 <td><em>unspecified</em></td>
52 <td> Reports whether this parser processes external
53 parameter entities; always true if validating.
54 </td>
55 </tr>
56
57 <tr>
58 <td>is-standalone</td>
59 <td>(parsing) <em>read-only</em>, (not parsing) <em>none</em></td>
60 <td>not applicable</td>
61 <td> May be examined only during a parse, after the
62 <em>startDocument()</em> callback has been completed; read-only.
63 The value is true if the document specified standalone="yes" in
64 its XML declaration, and otherwise is false.
65 </td>
66 </tr>
67
68 <tr>
69 <td>lexical-handler/parameter-entities</td>
70 <td><em>read/write</em></td>
71 <td><em>unspecified</em></td>
72 <td> A value of "true" indicates that the LexicalHandler will report
73 the beginning and end of parameter entities.
74 </td>
75 </tr>
76
77 <tr>
78 <td>namespaces</td>
79 <td><em>read/write</em></td>
80 <td>true</td>
81 <td> A value of "true" indicates namespace URIs and unprefixed local names
82 for element and attribute names will be available.
83 </td>
84 </tr>
85
86 <tr>
87 <td>namespace-prefixes</td>
88 <td><em>read/write</em></td>
89 <td>false</td>
90 <td> A value of "true" indicates that XML qualified names (with prefixes) and
91 attributes (including <em>xmlns*</em> attributes) will be available.
92 </td>
93 </tr>
94
95 <tr>
96 <td>resolve-dtd-uris</td>
97 <td><em>read/write</em></td>
98 <td><em>true</em></td>
99 <td> A value of "true" indicates that system IDs in declarations will
100 be absolutized (relative to their base URIs) before reporting.
101 (That is the default behavior for all SAX2 XML parsers.)
102 A value of "false" indicates those IDs will not be absolutized;
103 parsers will provide the base URI from
104 <em>Locator.getSystemId()</em>.
105 This applies to system IDs passed in <ul>
106 <li><em>DTDHandler.notationDecl()</em>,
107 <li><em>DTDHandler.unparsedEntityDecl()</em>, and
108 <li><em>DeclHandler.externalEntityDecl()</em>.
109 </ul>
110 It does not apply to <em>EntityResolver.resolveEntity()</em>,
111 which is not used to report declarations, or to
112 <em>LexicalHandler.startDTD()</em>, which already provides
113 the non-absolutized URI.
114 </td>
115 </tr>
116
117 <tr>
118 <td>string-interning</td>
119 <td><em>read/write</em></td>
120 <td><em>unspecified</em></td>
121 <td> Has a value of "true" if all XML names (for elements, prefixes,
122 attributes, entities, notations, and local names),
123 as well as Namespace URIs, will have been interned
124 using <em>java.lang.String.intern</em>. This supports fast
125 testing of equality/inequality against string constants,
126 rather than forcing slower calls to <em>String.equals()</em>.
127 </td>
128 </tr>
129
130 <tr>
131 <td>unicode-normalization-checking</td>
132 <td><em>read/write</em></td>
133 <td><em>false</em></td>
134 <td> Controls whether the parser reports Unicode normalization
135 errors as described in section 2.13 and Appendix B of the
136 XML 1.1 Recommendation. If true, Unicode normalization
137 errors are reported using the ErrorHandler.error() callback.
138 Such errors are not fatal in themselves (though, obviously,
139 other Unicode-related encoding errors may be).
140 </td>
141 </tr>
142
143 <tr>
144 <td>use-attributes2</td>
145 <td><em>read-only</em></td>
146 <td>not applicable</td>
147 <td> Returns "true" if the <em>Attributes</em> objects passed by
148 this parser in <em>ContentHandler.startElement()</em>
149 implement the <a href="ext/Attributes2.html"
150 ><em>org.xml.sax.ext.Attributes2</em></a> interface.
151 That interface exposes additional DTD-related information,
152 such as whether the attribute was specified in the
153 source text rather than defaulted.
154 </td>
155 </tr>
156
157 <tr>
158 <td>use-locator2</td>
159 <td><em>read-only</em></td>
160 <td>not applicable</td>
161 <td> Returns "true" if the <em>Locator</em> objects passed by
162 this parser in <em>ContentHandler.setDocumentLocator()</em>
163 implement the <a href="ext/Locator2.html"
164 ><em>org.xml.sax.ext.Locator2</em></a> interface.
165 That interface exposes additional entity information,
166 such as the character encoding and XML version used.
167 </td>
168 </tr>
169
170 <tr>
171 <td>use-entity-resolver2</td>
172 <td><em>read/write</em></td>
173 <td><em>true</em></td>
174 <td> Returns "true" if, when <em>setEntityResolver</em> is given
175 an object implementing the <a href="ext/EntityResolver2.html"
176 ><em>org.xml.sax.ext.EntityResolver2</em></a> interface,
177 those new methods will be used.
178 Returns "false" to indicate that those methods will not be used.
179 </td>
180 </tr>
181
182 <tr>
183 <td>validation</td>
184 <td><em>read/write</em></td>
185 <td><em>unspecified</em></td>
186 <td> Controls whether the parser is reporting all validity
187 errors; if true, all external entities will be read.
188 </td>
189 </tr>
190
191 <tr>
192 <td>xmlns-uris</td>
193 <td><em>read/write</em></td>
194 <td><em>false</em></td>
195 <td> Controls whether, when the <em>namespace-prefixes</em> feature
196 is set, the parser treats namespace declaration attributes as
197 being in the <em>http://www.w3.org/2000/xmlns/</em> namespace.
198 By default, SAX2 conforms to the original "Namespaces in XML"
199 Recommendation, which explicitly states that such attributes are
200 not in any namespace.
201 Setting this optional flag to "true" makes the SAX2 events conform to
202 a later backwards-incompatible revision of that recommendation,
203 placing those attributes in a namespace.
204 </td>
205 </tr>
206
207 <tr>
208 <td>xml-1.1</td>
209 <td><em>read-only</em></td>
210 <td>not applicable</td>
211 <td> Returns "true" if the parser supports both XML 1.1 and XML 1.0.
212 Returns "false" if the parser supports only XML 1.0.
213 </td>
214 </tr>
215 </tbody>
216 </table>
217
218 <p> Support for the default values of the
219 <em>namespaces</em> and <em>namespace-prefixes</em>
220 properties is required.
221 Support for any other feature flags is entirely optional.
222 </p>
223
224 <p> For default values not specified by SAX2,
225 each XMLReader implementation specifies its default,
226 or may choose not to expose the feature flag.
227 Unless otherwise specified here,
228 implementations may support changing current values
229 of these standard feature flags, but not while parsing.
230 </p>
231
232 <h2> SAX2 Standard Handler and Property IDs </h2>
233
234 <p> For parser interface characteristics that are described
235 as objects, a separate namespace is defined. The
236 objects in this namespace are again identified by URI, and
237 the standard property URIs have the prefix
238 <code>http://xml.org/sax/properties/</code> before an identifier such as
239 <code>lexical-handler</code> or
240 <code>dom-node</code>. Manage those properties using
241 <em>setProperty()</em>. Those identifiers are: </p>
242
243 <table class="striped">
244 <caption>SAX2 Standard Properties </caption>
245 <thead>
246 <tr>
247 <th>Property ID</th>
248 <th>Description</th>
249 </tr>
250 </thead>
251 <tbody>
252
253 <tr>
254 <td>declaration-handler</td>
255 <td> Used to see most DTD declarations except those treated
256 as lexical ("document element name is ...") or which are
257 mandatory for all SAX parsers (<em>DTDHandler</em>).
258 The Object must implement <a href="ext/DeclHandler.html"
259 ><em>org.xml.sax.ext.DeclHandler</em></a>.
260 </td>
261 </tr>
262
263 <tr>
264 <td>document-xml-version</td>
265 <td> May be examined only during a parse, after the startDocument()
266 callback has been completed; read-only. This property is a
267 literal string describing the actual XML version of the document,
268 such as "1.0" or "1.1".
269 </td>
270 </tr>
271
272 <tr>
273 <td>dom-node</td>
274 <td> For "DOM Walker" style parsers, which ignore their
275 <em>parser.parse()</em> parameters, this is used to
276 specify the DOM (sub)tree being walked by the parser.
277 The Object must implement the
278 <em>org.w3c.dom.Node</em> interface.
279 </td>
280 </tr>
281
282 <tr>
283 <td>lexical-handler</td>
284 <td> Used to see some syntax events that are essential in some
285 applications: comments, CDATA delimiters, selected general
286 entity inclusions, and the start and end of the DTD
287 (and declaration of document element name).
288 The Object must implement <a href="ext/LexicalHandler.html"
289 ><em>org.xml.sax.ext.LexicalHandler</em></a>.
290 </td>
291 </tr>
292
293 <tr>
294 <td>xml-string</td>
295 <td> Readable only during a parser callback, this exposes a <b>TBS</b>
296 chunk of characters responsible for the current event. </td>
297 </tr>
298 </tbody>
299 </table>
300
301 <p> All of these standard properties are optional;
302 XMLReader implementations need not support them.
303 </p>
304
305 </body></html>