Thread: [Sax-devel] Re: SAX feature documentation in docs/features.html
Brought to you by:
dmegginson
From: Michael G. <mrg...@ca...> - 2004-03-19 00:12:31
Attachments:
package.html.cvs.1.14.diff
package.html
|
<html><head>=0A<!-- $Id: package.html,v 1.14 2004/03/08 13:01:00 dmegginson= Exp $ -->=0A</head><body>=0A=0A<p> This package provides the core SAX APIs= .=0ASome SAX1 APIs are deprecated to encourage integration of=0Anamespace-a= wareness into designs of new applications=0Aand into maintenance of existin= g infrastructure. </p>=0A=0A<p>See <a href=3D'http://www.saxproject.org'>ht= tp://www.saxproject.org</a>=0Afor more information about SAX.</p>=0A=0A=0A<= h2> SAX2 Standard Feature Flags </h2>=0A=0A<p> One of the essential charact= eristics of SAX2 is that it added=0Afeature flags which can be used to exam= ine and perhaps modify=0Aparser modes, in particular modes such as validati= on.=0ASince features are identified by (absolute) URIs, anyone=0Acan define= such features. =0ACurrently defined standard feature URIs have the prefi= x=0A<code>http://xml.org/sax/features/</code> before an identifier such as= =0A<code>validation</code>. Turn features on or off using=0A<em>setFeature= </em>. Those standard identifiers are: </p>=0A=0A=0A<table border=3D"1" ce= llpadding=3D"3" cellspacing=3D"0" width=3D"100%">=0A <tr align=3D"center= " bgcolor=3D"#ccccff">=0A <th>Feature ID</th>=0A <th>Default</th>=0A <th>De= scription</th>=0A </tr>=0A=0A <tr>=0A <td>external-general-entities</td>= =0A <td><em>unspecified</em></td>=0A <td> Reports whether this parser proce= sses external=0A general entities; always true if validating</td>=0A </= tr>=0A=0A <tr>=0A <td>external-parameter-entities</td>=0A <td><em>unspec= ified</em></td>=0A <td> Reports whether this parser processes external=0A = parameter entities; always true if validating</td>=0A </tr>=0A=0A <tr= >=0A <td>is-standalone</td>=0A <td><em>none</em></td>=0A <td> May be examin= ed only during a parse, after the=0A <em>startDocument()</em> callback = has been completed; read-only.=0A The value is true if the document spe= cified the=0A "standalone" flag in its XML declaration,=0A and othe= rwise is false. </td>=0A </tr>=0A=0A <tr>=0A <td>lexical-handler/paramet= er-entities</td>=0A <td><em>unspecified</em></td>=0A <td> true indicates th= at the LexicalHandler will report the=0A beginning and end of parameter= entities=0A </td>=0A </tr>=0A=0A <tr>=0A <td>namespaces</td>=0A <td= >true</td>=0A <td> true indicates namespace URIs and unprefixed local names= =0A for element and attribute names will be available </td>=0A </tr>=0A= =0A <tr>=0A <td>namespace-prefixes</td> <td>false</td> <td> true indicat= es=0A XML qualified names (with prefixes) and attributes (including=0A <em>= xmlns*</em> attributes) will be available </td>=0A </tr>=0A=0A <tr>=0A <= td>resolve-dtd-uris</td>=0A <td><em>true</em></td>=0A <td> A value of "true= " indicates that system IDs in declarations will=0A be absolutized (rel= ative to their base URIs) before reporting.=0A (That is the default beh= avior for all SAX2 XML parsers.)=0A A value of "false" indicates those = IDs will not be absolutized;=0A parsers will provide the base URI from= =0A <em>Locator.getSystemId()</em>.=0A This applies to system IDs p= assed in <ul>=0A <li><em>DTDHandler.notationDecl()</em>,=0A <li><em>DTDHa= ndler.unparsedEntityDecl()</em>, and=0A <li><em>DeclHandler.externalEntity= Decl()</em>.=0A </ul>=0A It does not apply to <em>EntityResolver.re= solveEntity()</em>,=0A which is not used to report declarations, or to= =0A <em>LexicalHandler.startDTD()</em>, which already provides=0A t= he non-absolutized URI.=0A </td>=0A </tr>=0A=0A <tr>=0A <td>string-i= nterning</td>=0A <td><em>unspecified</em></td>=0A <td> true if all XML name= s (for elements, prefixes, attributes,=0A entities, notations, and loca= l names),=0A as well as Namespace URIs, will have been interned=0A = using <em>java.lang.String.intern</em>. This supports fast=0A testing o= f equality/inequality against string constants,=0A rather than forcing = slower calls to <em>String.equals()</em>.=0A </td>=0A </tr>=0A=0A <t= r>=0A <td>unicode-normalization-checking</td>=0A <td><em>fals= e</em></td>=0A <td> Controls whether the parser reports Unicode norm= alization =0A errors as described in section 2.13 and Appendix B= of the =0A XML 1.1 Recommendation. If true, Unicode normalizati= on=0A errors are reported using the ErrorHandler.error() callbac= k.=0A Such errors are not fatal in themselves (though, obviously= ,=0A other Unicode-related encoding errors may be).=0A = </td>=0A </tr>=0A =0A <tr>=0A <td>use-attributes2</td>=0A <t= d><em>unspecified</em></td>=0A <td> Returns true if the <em>Attributes</em>= objects passed by=0A this parser in <em>ContentHandler.startElement()<= /em>=0A implement the <a href=3D"ext/Attributes2.html"=0A ><em>org.= xml.sax.ext.Attributes2</em></a> interface.=0A That interface exposes a= dditional DTD-related information,=0A such as whether the attribute was= specified in the=0A source text rather than defaulted.=0A </td>=0A= </tr>=0A=0A <tr>=0A <td>use-locator2</td>=0A <td><em>unspecified</em></= td>=0A <td> Returns true if the <em>Locator</em> objects passed by=0A t= his parser in <em>ContentHandler.setDocumentLocator()</em>=0A implement= the <a href=3D"ext/Locator2.html"=0A ><em>org.xml.sax.ext.Locator2</em= ></a> interface.=0A That interface exposes additional entity informatio= n,=0A such as the character encoding and XML version used.=0A </td>= =0A </tr>=0A=0A <tr>=0A <td>use-entity-resolver2</td>=0A <td><em>true</e= m> (when recognized)</td>=0A <td> Returns true if, when <em>setEntityResolv= er</em> is given=0A an object implementing the <a href=3D"ext/EntityRes= olver2.html"=0A ><em>org.xml.sax.ext.EntityResolver2</em></a> interface= ,=0A those new methods will be used.=0A Returns false to indicate t= hat those methods will not be used.=0A </td>=0A </tr>=0A=0A <tr>=0A = <td>validation</td>=0A <td><em>unspecified</em></td>=0A <td> Controls wheth= er the parser is reporting all validity=0A errors; if true, all externa= l entities will be read. </td>=0A </tr>=0A=0A <tr>=0A <td>xmlns-uris</t= d>=0A <td><em>false</em></td>=0A <td> Controls whether, when the <em>namesp= ace-prefixes</em> feature=0A is set, the parser treats namespace declar= ation attributes as=0A being in the <em>http://www.w3.org/2000/xmlns/</= em> namespace.=0A By default, SAX2 conforms to the original "Namespaces= in XML"=0A Recommendation, which explicitly states that such attribute= s are=0A not in any namespace.=0A Setting this optional flag to tru= e makes the SAX2 events conform to=0A a later backwards-incompatible re= vision of that recommendation,=0A placing those attributes in a namespa= ce.=0A </td>=0A </tr>=0A=0A <tr>=0A <td>xml-1.1</td>=0A = <td><em>unspecified</em></td>=0A <td> Returns true if the parser s= upports both XML 1.1 and XML 1.0.=0A Returns false if the parser= supports only XML 1.0.=0A </td>=0A </tr>=0A=0A</table>= =0A=0A<p> Support for the default values of the=0A<em>namespaces</em> and <= em>namespace-prefixes</em>=0Aproperties is required.=0ASupport for any othe= r feature flags is entirely optional.=0A</p>=0A=0A<p> For default values no= t specified by SAX2,=0Aeach XMLReader implementation specifies its default,= =0Aor may choose not to expose the feature flag.=0AUnless otherwise specifi= ed here,=0Aimplementations may support changing current values=0Aof these s= tandard feature flags, but not while parsing.=0A</p>=0A=0A<h2> SAX2 Standar= d Handler and Property IDs </h2>=0A=0A<p> For parser interface characterist= ics that are described=0Aas objects, a separate namespace is defined. The= =0Aobjects in this namespace are again identified by URI, and=0Athe standar= d property URIs have the prefix=0A<code>http://xml.org/sax/properties/</cod= e> before an identifier such as=0A<code>lexical-handler</code> or=0A<code>d= om-node</code>. Manage those properties using=0A<em>setProperty()</em>. T= hose identifiers are: </p>=0A=0A<table border=3D"1" cellpadding=3D"3" cells= pacing=3D"0" width=3D"100%">=0A <tr align=3D"center" bgcolor=3D"#ccccff"= >=0A <th>Property ID</th>=0A <th>Description</th>=0A </tr>=0A=0A <tr>=0A= <td>declaration-handler</td>=0A <td> Used to see most DTD declarations exc= ept those treated=0A as lexical ("document element name is ...") or whi= ch are=0A mandatory for all SAX parsers (<em>DTDHandler</em>).=0A T= he Object must implement <a href=3D"ext/DeclHandler.html"=0A ><em>org.x= ml.sax.ext.DeclHandler</em></a>.=0A </td>=0A </tr>=0A=0A <tr>=0A = <td>document-xml-version</td>=0A <td> May be examined only durin= g a parse, after the startDocument()=0A callback has been comple= ted; read-only. This property is a =0A literal string describing= the actual XML version of the document, =0A such as "1.0" or "1= .1".=0A </td>=0A </tr>=0A =0A <tr>=0A <td>dom-node<= /td>=0A <td> For "DOM Walker" style parsers, which ignore their=0A <em>= parser.parse()</em> parameters, this is used to=0A specify the DOM (sub= )tree being walked by the parser.=0A The Object must implement the=0A = <em>org.w3c.dom.Node</em> interface.=0A </td>=0A </tr>=0A=0A <tr>= =0A <td>lexical-handler</td>=0A <td> Used to see some syntax events that ar= e essential in some=0A applications: comments, CDATA delimiters, selec= ted general=0A entity inclusions, and the start and end of the DTD=0A = (and declaration of document element name).=0A The Object must imple= ment <a href=3D"ext/LexicalHandler.html"=0A ><em>org.xml.sax.ext.Lexica= lHandler</em></a>.=0A </td>=0A </tr>=0A=0A <tr>=0A <td>xml-string</t= d>=0A <td> Readable only during a parser callback, this exposes a <b>TBS</b= >=0A chunk of characters responsible for the current event. </td>=0A </= tr>=0A=0A</table>=0A=0A<p> All of these standard properties are optional;= =0AXMLReader implementations need not support them.=0A</p>=0A=0A</body></ht= ml>=0A= |