libjava/org/xml/sax/package.html

   1 <html><head>
   2
   3 <!-- $Id: package.html,v 1.2.2.2 2002/01/12 21:42:21 dbrownell Exp $ -->
   4
   5 </head><body>
   6
   7 <p> This package provides the core SAX APIs.
   8 Some SAX1 APIs are deprecated to encourage integration of
   9 namespace-awareness into designs of new applications
  10 and into maintainance of existing infrastructure. </p>
  11
  12 <p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  13 for more information about SAX.</p>
  14
  15
  16 <h2> SAX2 Standard Feature Flags </h2>
  17
  18 <p> One of the essential characteristics of SAX2 is that it added
  19 feature flags which can be used to examine and perhaps modify
  20 parser modes, in particular modes such as validation.
  21 Since features are identified by (absolute) URIs, anyone
  22 can define such features.
  23 Currently defined standard feature URIs have the prefix
  24 <code>http://xml.org/sax/features/</code> before an identifier such as
  25 <code>validation</code>.  Turn features on or off using
  26 <em>setFeature</em>.  Those standard identifiers are: </p>
  27
  28
  29 <table border="1" cellpadding="3" cellspacing="0" width="100%">
  30     <tr align="center" bgcolor="#ccccff">
  31         <th>Feature ID</th>
  32         <th>Default</th>
  33         <th>Description</th>
  34         </tr>
  35
  36     <tr>
  37         <td>external-general-entities</td>
  38         <td><em>unspecified</em></td>
  39         <td> Reports whether this parser processes external
  40             general entities; always true if validating</td>
  41         </tr>
  42
  43     <tr>
  44         <td>external-parameter-entities</td>
  45         <td><em>unspecified</em></td>
  46         <td> Reports whether this parser processes external
  47             parameter entities; always true if validating</td>
  48         </tr>
  49
  50     <tr>
  51         <td>lexical-handler/parameter-entities</td>
  52         <td><em>unspecified</em></td>
  53         <td> true indicates that the LexicalHandler will report the
  54             beginning and end of parameter entities
  55             </td>
  56         </tr>
  57
  58     <tr>
  59         <td>namespaces</td>
  60         <td>true</td>
  61         <td> true indicates namespace URIs and unprefixed local names
  62             for element and attribute names will be available </td>
  63         </tr>
  64
  65     <tr>
  66         <td>namespace-prefixes</td>
  67         <td>false</td>
  68         <td> true indicates XML 1.0 names (with prefixes) and attributes
  69             (including <em>xmlns*</em> attributes) will be available </td>
  70         </tr>
  71
  72     <tr>
  73         <td>string-interning</td>
  74         <td><em>unspecified</em></td>
  75         <td> true if all XML names (for elements, prefixes, attributes,
  76             entities, notations, and local names),
  77             as well as Namespace URIs, will have been interned
  78             using <em>java.lang.String.intern</em>. This supports fast
  79             testing of equality/inequality against string constants.</td>
  80         </tr>
  81
  82     <tr>
  83         <td>validation</td>
  84         <td><em>unspecified</em></td>
  85         <td> controls whether the parser is reporting all validity
  86             errors; if true, all external entities will be read.  </td>
  87         </tr>
  88
  89 </table>
  90
  91 <p> Support for the default values of the
  92 <em>namespaces</em> and <em>namespace-prefixes</em>
  93 properties is required.
  94 </p>
  95
  96 <p> For default values not specified by SAX2,
  97 each XMLReader implementation specifies its default,
  98 or may choose not to expose the feature flag.
  99 Unless otherwise specified here,
 100 implementations may support changing current values
 101 of these standard feature flags, but not while parsing.
 102 </p>
 103
 104 <h2> SAX2 Standard Handler and Property IDs </h2>
 105
 106 <p> For parser interface characteristics that are described
 107 as objects, a separate namespace is defined.  The
 108 objects in this namespace are again identified by URI, and
 109 the standard property URIs have the prefix
 110 <code>http://xml.org/sax/properties/</code> before an identifier such as
 111 <code>lexical-handler</code> or
 112 <code>dom-node</code>.  Manage those properties using
 113 <em>setProperty()</em>.  Those identifiers are: </p>
 114
 115 <table border="1" cellpadding="3" cellspacing="0" width="100%">
 116     <tr align="center" bgcolor="#ccccff">
 117         <th>Property ID</th>
 118         <th>Description</th>
 119         </tr>
 120
 121     <tr>
 122         <td>declaration-handler</td>
 123         <td> Used to see most DTD declarations except those treated
 124             as lexical ("document element name is ...") or which are
 125             mandatory for all SAX parsers (<em>DTDHandler</em>).
 126             The Object must implement <a href="ext/DeclHandler.html"
 127             ><em>org.xml.sax.ext.DeclHandler</em></a>.
 128             </td>
 129         </tr>
 130
 131     <tr>
 132         <td>dom-node</td>
 133         <td> For "DOM Walker" style parsers, which ignore their
 134             <em>parser.parse()</em> parameters, this is used to
 135             specify the DOM (sub)tree being walked by the parser.
 136             The Object must implement the
 137             <em>org.w3c.dom.Node</em> interface.
 138             </td>
 139         </tr>
 140
 141     <tr>
 142         <td>lexical-handler</td>
 143         <td> Used to see some syntax events that are essential in some
 144             applications:  comments, CDATA delimeters, selected general
 145             entity inclusions, and the start and end of the DTD
 146             (and declaration of document element name).
 147             The Object must implement <a href="ext/LexicalHandler.html"
 148             ><em>org.xml.sax.ext.LexicalHandler</em></a>.
 149             </td>
 150         </tr>
 151
 152     <tr>
 153         <td>xml-string</td>
 154         <td> Readable only during a parser callback, this exposes a <b>TBS</b>
 155             chunk of characters responsible for the current event. </td>
 156         </tr>
 157
 158 </table>
 159
 160 <p> All of these standard properties are optional;
 161 XMLReader implementations need not support them.
 162 </p>
 163
 164 </body></html>