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> |
|