lib/classpath/external/sax/org/xml/sax/package.html

   1 <html><head>
   2 <!-- $Id: package.html,v 1.1 2004/12/23 22:38:42 mark 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 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 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>
 216 properties is required.
 217 Support for any other feature flags is entirely optional.
 218 </p>
 219
 220 <p> For default values not specified by SAX2,
 221 each XMLReader implementation specifies its default,
 222 or may choose not to expose the feature flag.
 223 Unless otherwise specified here,
 224 implementations may support changing current values
 225 of 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
 231 as objects, a separate namespace is defined.  The
 232 objects in this namespace are again identified by URI, and
 233 the 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;
 294 XMLReader implementations need not support them.
 295 </p>
 296
 297 </body></html>