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