Checkin external modules: SAX 2.0 r2 prerelease; SAX2-ext 1.0

git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225904 13f79535-47bb-0310-9956-ffa450edef68

java/external/src/org/xml/sax/ext/package.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>SAX2-ext: SAX2 Extension Handlers 1.0</title>
+</head>
+
+<body>
+<h1>SAX2-ext: SAX2 Extension Handlers 1.0</h1>
+
+<blockquote>
+<p class="copyright">This document is in the <strong>PUBLIC
+DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
+kind.</p>
+</blockquote>
+
+<p>This package, SAX2-ext, is an extension package for SAX2.  It is
+designed both to allow SAX drivers to pass certain types of none-core
+information to applications and to serve as a simple model for other
+SAX2 extension packages.</p>
+
+<p><strong>NOTE:</strong> this package alone does add any
+functionality; it simply provides optional interfaces for SAX2 drivers
+to use.  You must find a SAX2 driver that supports these interfaces if
+you actually want to have access to lexical and declaration
+information.</p>
+
+<p>The SAX2-ext package currently contains two extension handlers for
+SAX2:</p>
+
+<ol>
+
+<li><a href="javadoc/org/xml/sax/ext/LexicalHandler.html"
+>LexicalHandler</a>, which reports comments, the DOCTYPE declaration,
+CDATA sections, and (some) entity boundaries; and</li>
+
+<li><a href="javadoc/org/xml/sax/ext/DeclHandler.html"
+>DeclHandler</a>, which reports element, attribute, and entity
+declarations.</li>
+
+</ol>
+
+<p>This package is independent of the SAX2 core, and that independence
+has several consequences:</p>
+
+<ul>
+
+<li>SAX2 drivers are <em>not</em> required to support these handlers,
+and you cannot assume that the classes will be present in every SAX2
+installation.</li>
+
+<li>This package may be updated independently of SAX2 (i.e. new
+handlers may be added without updating SAX2 itself).</li>
+
+<li>The handlers are not supported explicitly by the SAX2
+<var>XMLFilter</var> interface (i.e. events are not passed on by
+default); you can subclass XMLFilter if you need such behaviour.</li>
+
+<li>The handlers need to be registered differently than regular SAX2
+handlers.</li>
+
+</ul>
+
+<p>To set a LexicalHandler, for example, you need to do something like 
+this:</p>
+
+<blockquote><pre xml:space="preserve">
+LexicalHandler lh = new MyLexicalHandler();
+try {
+  xmlReader.setProperty("http://xml.org/sax/properties/lexical-handler",
+                        lh);
+} catch (SAXException e) {
+  System.out.println("LexicalHandler not supported by this SAX2 driver.");
+}
+</pre></blockquote>
+
+
+<div>
+<h2>SAX2-ext Properties</h2>
+
+<p>Here is a full definition of the two new SAX2 properties introduced
+in this version of SAX2-ext:</p>
+
+<dl>
+
+<dt><code>http://xml.org/sax/properties/lexical-handler</code></dt>
+<dd><strong>data type:</strong>
+<code>org.xml.sax.ext.LexicalHandler</code></dd>
+<dd><strong>description:</strong> An optional extension handler for
+lexical events like comments.</dd>
+<dd><strong>access:</strong> read/write</dd>
+
+<dt><code>http://xml.org/sax/properties/declaration-handler</code></dt>
+<dd><strong>data type:</strong>
+<code>org.xml.sax.ext.DeclHandler</code></dd>
+<dd><strong>description:</strong> An optional extension handler for
+DTD-related events other than notations and unparsed entities.</dd>
+<dd><strong>access:</strong> read/write</dd>
+
+</dl>
+
+<p><strong>See also:</strong> the package's <a
+href="javadoc/index.html">JavaDoc</a> documentation.</p>
+
+<!-- end of "SAX2-ext Properties" -->
+</div>
+
+<hr />
+
+<address>$Id$</address>
+
+</body>
+</html>