PatchSet 4178 Date: 2003/12/02 21:39:57 Author: dalibor Branch: HEAD Tag: (none) Log: Added package docs for GNU JAXP
Members: libraries/javalib/javax/xml/parsers/package.html:INITIAL->1.1 libraries/javalib/javax/xml/transform/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/package.html:INITIAL->1.1 libraries/javalib/org/xml/sax/package.html:INITIAL->1.1 libraries/javalib/gnu/xml/aelfred2/package.html:INITIAL->1.1 libraries/javalib/gnu/xml/dom/package.html:INITIAL->1.1 libraries/javalib/gnu/xml/pipeline/package.html:INITIAL->1.1 libraries/javalib/gnu/xml/util/package.html:INITIAL->1.1 libraries/javalib/javax/xml/transform/dom/package.html:INITIAL->1.1 libraries/javalib/javax/xml/transform/sax/package.html:INITIAL->1.1 libraries/javalib/javax/xml/transform/stream/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/css/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/events/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/html/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/ranges/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/stylesheets/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/traversal/package.html:INITIAL->1.1 libraries/javalib/org/w3c/dom/views/package.html:INITIAL->1.1 libraries/javalib/org/xml/sax/ext/package.html:INITIAL->1.1 libraries/javalib/org/xml/sax/helpers/package.html:INITIAL->1.1 =================================================================== Checking out kaffe/libraries/javalib/javax/xml/parsers/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/javax/xml/parsers/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/javax/xml/parsers/package.html Tue Dec 2 21:55:55 2003 @@ -0,0 +1,16 @@ +<html><head>javax.xml.parsers</head><body> + +<p>Bootstrapping APIs for JAXP parsers. +This is the first portable API defined for bootstrapping DOM. + +<p>JAXP parsers bootstrap in two stages. +First is getting a factory, and configuring it. +Second is asking that factory for a parser. + +<p>The SAX bootstrapping support corresponds to functionality +found in the <em>org.xml.sax.helpers</em> package, except +that it uses the JAXP two stage bootstrap paradigm and +that the parser that's bootstrapped is normally wrapping +a SAX parser rather than exposing it for direct use. + +</body></html> =================================================================== Checking out kaffe/libraries/javalib/javax/xml/transform/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/javax/xml/transform/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/javax/xml/transform/package.html Tue Dec 2 21:55:55 2003 @@ -0,0 +1,38 @@ +<html><head>trax </head><body> + +<p>Base "TRAX" API for XSLT transformers. +This API borrows many structural notions from SAX, +such as the way error handling and external entity +resolution are handled, although it does not reuse +the corresponding SAX classes. +To use XSLT transformers: <ul> + +<li>Start with <em>TransformerFactory.newInstance()</em>; + +<li>Then you may wish to configure that factory through +its features and properties. This includes modifying +the way errors are handled and URIs are resolved. + +<li>Then you have several options for how to perform +the XSLT transformations. One generic option is to ask the +factory for a <a href="Transformer.html">Transformer</a> +and then use <em>Transformer.transform()</em> to pull +input text onto output text. + +<li>Alternatively, most factories support flexible integration +with SAX event streams. You can cast such factories to a +<a href="sax/SAXTransformerFactory.html">SAXTransformerFactory</a> +and perform either push or pull mode transformations. + +</ul> + +<p>The <a href="OutputKeys.html">OutputKeys</a> class +holds constants that can be used to configure output +properties used with <em>Result</em> objects, as if +they were specified in <em>xslt:output</em> attributes +in the stylesheet specifying the transform. + +<p>The <a href="Templates.html">Templates</a> class +accomodates the notion of "compiled" transforms. + +</body></html> =================================================================== Checking out kaffe/libraries/javalib/org/w3c/dom/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/org/w3c/dom/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/org/w3c/dom/package.html Tue Dec 2 21:55:56 2003 @@ -0,0 +1,9 @@ +<html><head> +<title>DOM Level 2</title> +</head><body> + +<p>Contains the core and "XML" feature set of the +<a href="http://www.w3.org/TR/2000/REC-DOM-Level-2-core-20001113/"> +DOM Level 2</a> Recommendation. </p> + +</body></html> =================================================================== Checking out kaffe/libraries/javalib/org/xml/sax/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/org/xml/sax/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/org/xml/sax/package.html Tue Dec 2 21:55:56 2003 @@ -0,0 +1,229 @@ +<html><head> +<!-- $Id: package.html,v 1.1 2003/12/02 21:39:59 dalibor Exp $ --> +</head><body> + +<p> This package provides the core SAX APIs. +Some SAX1 APIs are deprecated to encourage integration of +namespace-awareness into designs of new applications +and into maintainance of existing infrastructure. </p> + +<p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> +for more information about SAX.</p> + + +<h2> SAX2 Standard Feature Flags </h2> + +<p> One of the essential characteristics of SAX2 is that it added +feature flags which can be used to examine and perhaps modify +parser modes, in particular modes such as validation. +Since features are identified by (absolute) URIs, anyone +can define such features. +Currently defined standard feature URIs have the prefix +<code>http://xml.org/sax/features/</code> before an identifier such as +<code>validation</code>. Turn features on or off using +<em>setFeature</em>. Those standard identifiers are: </p> + + +<table border="1" cellpadding="3" cellspacing="0" width="100%"> + <tr align="center" bgcolor="#ccccff"> + <th>Feature ID</th> + <th>Default</th> + <th>Description</th> + </tr> + + <tr> + <td>external-general-entities</td> + <td><em>unspecified</em></td> + <td> Reports whether this parser processes external + general entities; always true if validating</td> + </tr> + + <tr> + <td>external-parameter-entities</td> + <td><em>unspecified</em></td> + <td> Reports whether this parser processes external + parameter entities; always true if validating</td> + </tr> + + <tr> + <td>is-standalone</td> + <td><em>none</em></td> + <td> May be examined only during a parse, after the + <em>startDocument()</em> callback has been made; read-only. + The value is true if the document specified the + "standalone" flag in its XML declaration, + and otherwise is false. </td> + </tr> + + <tr> + <td>lexical-handler/parameter-entities</td> + <td><em>unspecified</em></td> + <td> true indicates that the LexicalHandler will report the + beginning and end of parameter entities + </td> + </tr> + + <tr> + <td>namespaces</td> + <td>true</td> + <td> true indicates namespace URIs and unprefixed local names + for element and attribute names will be available </td> + </tr> + + <tr> + <td>namespace-prefixes</td> + <td>false</td> + <td> true indicates XML 1.0 names (with prefixes) and attributes + (including <em>xmlns*</em> attributes) will be available </td> + </tr> + + <tr> + <td>resolve-dtd-uris</td> + <td><em>true</em></td> + <td> A value of "true" indicates that system IDs in declarations will + be absolutized (relative to their base URIs) before reporting. + (That is the default behavior for all SAX2 XML parsers.) + A value of "false" indicates those IDs will not be absolutized; + parsers will provide the base URI from + <em>Locator.getSystemId()</em>. + This applies to system IDs passed in <ul> + <li><em>DTDHandler.notationDecl()</em>, + <li><em>DTDHandler.unparsedEntityDecl()</em>, and + <li><em>DeclHandler.externalEntityDecl()</em>. + </ul> + It does not apply to <em>EntityResolver.resolveEntity()</em>, + which is not used to report declarations, or to + <em>LexicalHandler.startDTD()</em>, which already provides + the non-absolutized URI. + </td> + </tr> + + <tr> + <td>string-interning</td> + <td><em>unspecified</em></td> + <td> true if all XML names (for elements, prefixes, attributes, + entities, notations, and local names), + as well as Namespace URIs, will have been interned + using <em>java.lang.String.intern</em>. This supports fast + testing of equality/inequality against string constants.</td> + </tr> + + <tr> + <td>use-attributes2</td> + <td><em>unspecified</em></td> + <td> Returns true if the <em>Attributes</em> objects passed by + this parser in <em>ContentHandler.startElement()</em> + implement the <a href="ext/Attributes2.html" + ><em>org.xml.sax.ext.Attributes2</em></a> interface. + That interface exposes additional information, + such as whether the attribute was specified in the + source text rather than defaulted. + </td> + </tr> + + <tr> + <td>use-locator2</td> + <td><em>unspecified</em></td> + <td> Returns true if the <em>Locator</em> objects passed by + this parser in <em>ContentHandler.setDocumentLocator()</em> + implement the <a href="ext/Locator2.html" + ><em>org.xml.sax.ext.Locator2</em></a> interface. + That interface exposes additional entity information, + such as the character encoding and XML version used. + </td> + </tr> + + <tr> + <td>use-entity-resolver2</td> + <td><em>true</em> (when recognized)</td> + <td> Returns true if, when <em>setEntityResolver</em> is given + an object implementing the <a href="ext/EntityResolver2.html" + ><em>org.xml.sax.ext.EntityResolver2</em></a> interface, + those new methods will be used. + Returns false to indicate that those methods will not be used. + </td> + </tr> + + <tr> + <td>validation</td> + <td><em>unspecified</em></td> + <td> controls whether the parser is reporting all validity + errors; if true, all external entities will be read. </td> + </tr> + +</table> + +<p> Support for the default values of the +<em>namespaces</em> and <em>namespace-prefixes</em> +properties is required. +</p> + +<p> For default values not specified by SAX2, +each XMLReader implementation specifies its default, +or may choose not to expose the feature flag. +Unless otherwise specified here, +implementations may support changing current values +of these standard feature flags, but not while parsing. +</p> + +<h2> SAX2 Standard Handler and Property IDs </h2> + +<p> For parser interface characteristics that are described +as objects, a separate namespace is defined. The +objects in this namespace are again identified by URI, and +the standard property URIs have the prefix +<code>http://xml.org/sax/properties/</code> before an identifier such as +<code>lexical-handler</code> or +<code>dom-node</code>. Manage those properties using +<em>setProperty()</em>. Those identifiers are: </p> + +<table border="1" cellpadding="3" cellspacing="0" width="100%"> + <tr align="center" bgcolor="#ccccff"> + <th>Property ID</th> + <th>Description</th> + </tr> + + <tr> + <td>declaration-handler</td> + <td> Used to see most DTD declarations except those treated + as lexical ("document element name is ...") or which are + mandatory for all SAX parsers (<em>DTDHandler</em>). + The Object must implement <a href="ext/DeclHandler.html" + ><em>org.xml.sax.ext.DeclHandler</em></a>. + </td> + </tr> + + <tr> + <td>dom-node</td> + <td> For "DOM Walker" style parsers, which ignore their + <em>parser.parse()</em> parameters, this is used to + specify the DOM (sub)tree being walked by the parser. + The Object must implement the + <em>org.w3c.dom.Node</em> interface. + </td> + </tr> + + <tr> + <td>lexical-handler</td> + <td> Used to see some syntax events that are essential in some + applications: comments, CDATA delimeters, selected general + entity inclusions, and the start and end of the DTD + (and declaration of document element name). + The Object must implement <a href="ext/LexicalHandler.html" + ><em>org.xml.sax.ext.LexicalHandler</em></a>. + </td> + </tr> + + <tr> + <td>xml-string</td> + <td> Readable only during a parser callback, this exposes a <b>TBS</b> + chunk of characters responsible for the current event. </td> + </tr> + +</table> + +<p> All of these standard properties are optional; +XMLReader implementations need not support them. +</p> + +</body></html> =================================================================== Checking out kaffe/libraries/javalib/gnu/xml/aelfred2/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/gnu/xml/aelfred2/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/gnu/xml/aelfred2/package.html Tue Dec 2 21:55:56 2003 @@ -0,0 +1,477 @@ +<!DOCTYPE html PUBLIC + '-//W3C//DTD XHTML 1.0 Transitional//EN' + 'http://www.w3.org/TR/xhtml1/DTD/transitional.dtd'> + +<html><head> + <title>package overview</title> +<!-- +/* + * Copyright (c) 1999-2001 by David Brownell. + * This file is distributed under the GPL. + * + * $Id: package.html,v 1.1 2003/12/02 21:39:54 dalibor Exp $ + */ +--> +</head><body> + +<p> This package contains Ælfred2, which includes an +enhanced SAX2-compatible version of the Ælfred +non-validating XML parser, a modular (and hence optional) +DTD validating parser, and modular (and hence optional) +JAXP glue to those. +Use these like any other SAX2 parsers. </p> + +<ul> + <li><a href="#about">About Ælfred</a><ul> + <li><a href="#principles">Design Principles</a></li> + <li><a href="#name">About the Name Ælfred</a></li> + <li><a href="#encodings">Character Encodings</a></li> + <li><a href="#violations">Known Conformance Violations</a></li> + <li><a href="#license">Licensing</a></li> + </ul></li> + + <li><a href="#changes">Changes Since the Last Microstar Release</a><ul> + <li><a href="#sax2">SAX2 Support</a></li> + <li><a href="#validation">Validation</a></li> + <li><a href="#smaller">You Want Smaller?</a></li> + <li><a href="#bugfixes">Bugs Fixed</a></li> + </ul></li> + +</ul> + +<p> Some of the documentation below was modified from the original +Ælfred README.txt file. All of it has been updated. </p> + + +<h2><a name="about">About Ælfred</a></h2> + +<p>Ælfred is a Java-based XML parser originally from +Microstar Software Limited (no longer in existence) and +more or less placed into the public domain. + + +<h3><a name="principles">Design Principles</a></h3> + +<p>In most Java applets and applications, XML should not be the central +feature; instead, XML is the means to another end, such as loading +configuration information, reading meta-data, or parsing transactions.</p> + +<p> When an XML parser is only a single component of a much larger +program, it cannot be large, slow, or resource-intensive. With Java +applets, in particular, code size is a significant issue. The standard +modem is still not operating at 56 Kbaud, or sometimes even with data +compression. Assuming an uncompressed 28.8 Kbaud modem, only about +3 KBytes can be downloaded in one second; compression often doubles +that speed, but a V.90 modem may not provide another doubling. When +used with embedded processors, similar size concerns apply. </p> + +<p> Ælfred is designed for easy and efficient use over the Internet, +based on the following principles: </p> <ol> + +<li> Ælfred must be as small as possible, so that it doesn't add too + much to an applet's download time. </li> + +<li> Ælfred must use as few class files as possible, to minimize the + number of HTTP connections necessary. (The use of JAR files has made this + be less of a concern.) </li> + +<li> Ælfred must be compatible with most or all Java implementations + and platforms. (Write once, run anywhere.) </li> + +<li> Ælfred must use as little memory as possible, so that it does + not take away resources from the rest of your program. (It doesn't force + you to use DOM or a similar costly data structure API.)</li> + +<li> Ælfred must run as fast as possible, so that it does not slow down + the rest of your program. </li> + +<li> Ælfred must produce correct output for well-formed and valid + documents, but need not reject every document that is not valid or + not well-formed. (In Ælfred2, correctness was a bigger concern + than in the original version; and a validation option is available.) </li> + +<li> Ælfred must provide full internationalization from the first + release. (Ælfred2 now automatically handles all encodings + supported by the underlying JVM; previous versions handled only + UTF-8, UTF_16, ASCII, and ISO-8859-1.)</li> + +</ol> + +<p>As you can see from this list, Ælfred is designed for production +use, but neither validation nor perfect conformance was a requirement. +Good validating parsers exist, including one in this package, +and you should use them as appropriate. (See conformance reviews +available at <a href="http://www.xml.com/">http://www.xml.com</a>) +</p> + +<p> One of the main goals of Ælfred2 was to significantly improve +conformance, while not significantly affecting the other goals stated above. +Since the only use of this parser is with SAX, some classes could be +removed, and so the overall size of Ælfred was actually reduced. +Subsequent performance work produced a notable speedup (over twenty +percent on larger files). That is, the tradeoffs between speed, size, and +conformance were re-targeted towards conformance and support of newer APIs +(SAX2), with a a positive performance impact. </p> + +<p> The role anticipated for this version of Ælfred is as a +lightweight Free Software SAX parser that can be used in essentially every +Java program where the handful of conformance violations (noted below) +are acceptable. +That certainly includes applets, and +nowadays one must also mention embedded systems as being even more +size-critical. +At this writing, all parsers that are more conformant are +significantly larger, even when counting the optional +validation support in this version of Ælfred. </p> + + +<h3><a name="name">About the Name <em>Ælfred</em></a></h3> + +<p>Ælfred the Great (AElfred in ASCII) was King of Wessex, and +some say of King of England, at the time of his death in 899 AD. +Ælfred introduced a wide-spread literacy program in the hope that +his people would learn to read English, at least, if Latin was too +difficult for them. This Ælfred hopes to bring another sort of +literacy to Java, using XML, at least, if full SGML is too difficult.</p> + +<p>The initial Æ ligature ("AE)" is also a reminder that XML is +not limited to ASCII.</p> + + +<h3><a name="encodings">Character Encodings</a></h3> + +<p> The Ælfred parser currently builds in support for a handful +of input encodings. Of course these include UTF-8 and UTF-16, which +all XML parsers are required to support:</p> <ul> + + <li> UTF-8 ... the standard eight bit encoding, used unless + you provide an encoding declaration or a MIME charset tag.</li> + + <li> US-ASCII ... an extremely common seven bit encoding, + which happens to be a subset of UTF-8 and ISO-8859-1 as well + as many other encodings. XHTML web pages using US-ASCII + (without an encoding declaration) are probably more + widely interoperable than those in any other encoding. </li> + + <li> ISO-8859-1 ... includes accented characters used in + much of western Europe (but excluding the Euro currency + symbol).</li> + + <li> UTF-16 ... with several variants, this encodes each + sixteen bit Unicode character in sixteen bits of output. + Variants include UTF-16BE (big endian, no byte order mark), + UTF-16LE (little endian, no byte order mark), and + ISO-10646-UCS-2 (an older and less used encoding, using a + version of Unicode without surrogate pairs). This is + essentially the native encoding used by Java. </li> + + <li> ISO-10646-UCS-4 ... a seldom-used four byte encoding, + also known as UTF-32BE. Four byte order variants are supported, + including one known as UTF-32LE. Some operating systems + standardized on UCS-4 despite its significant size penalty, + in anticipation that Unicode (even with surrogate pairs) + would eventually become limiting. UCS-4 permits encoding + of non-Unicode characters, which Java can't represent (and + XML doesn't allow). + </li> + + </ul> + +<p> If you use any encoding other than UTF-8 or UTF-16 you should +make sure to label your data appropriately: </p> + +<blockquote> +<?xml version="1.0" encoding="<b>ISO-8859-15</b>"?> +</blockquote> + +<p> Encodings accessed through <code>java.io.InputStreamReader</code> +are now fully supported for both external labels (such as MIME types) +and internal types (as shown above). +There is one limitation in the support for internal labels: +the encodings must be derived from the US-ASCII encoding, +the EBCDIC family of encodings is not recognized. +Note that Java defines its +own encoding names, which don't always correspond to the standard +Internet encoding names defined by the IETF/IANA, and that Java +may even <em>require</em> use of nonstandard encoding names. +Please report +such problems; some of them can be worked around in this parser, +and many can be worked around by using external labels. +</p> + +<p>Note that if you are using the Euro symbol with an fixed length +eight bit encoding, you should probably be using the encoding label +<em>iso-8859-15</em> or, with a Microsoft OS, <em>cp-1252</em>. +Of course, UTF-8 and UTF-16 handle the Euro symbol directly. +</p> + + +<h3><a name="violations">Known Conformance Violations</a></h3> + +<p>Known conformance issues should be of negligible importance for +most applications, and include: </p><ul> + + <li> Rather than following the voluminous "Appendix B" rules about + what characters may appear in names (and name tokens), the Unicode + rules embedded in <em>java.lang.Character</em> are used. + This means mostly that some names are inappropriately accepted, + though a few are inappropriately rejected. (It's much simpler + to avoid that much special case code. Recent OASIS/NIST test + cases may have these rules be realistically testable.) </li> + + <li> Text containing "]]>" is not rejected unless it fully resides + in an internal buffer ... which is, thankfully, the typical case. This + text is illegal, but sometimes appears in illegal attempts to + nest CDATA sections. (Not catching that boundary condition + substantially simplifies parsing text.) </li> + + <li> Surrogate characters that aren't correctly paired are ignored + rather than rejected, unless they were encoded using UTF-8. (This + simplifies parsing text.) Unicode 3.1 assigned the first characters + to those character codes, in early 2001, so few documents (or tools) + use such characters in any case. </li> + + <li> Declarations following references to an undefined parameter + entity reference are not ignored. (Not maintaining and using state + about this validity error simplifies declaration handling; few + XML parsers address this constraint in any case.) </li> + + <li> Well formedness constraints for general entity references + are not enforced. (The code to handle the "content" production + is merged with the element parsing code, making it hard to reuse + for this additional situation.) </li> + +</ul> + +<p> When tested against the July 12, 1999 version of the OASIS +XML Conformance test suite, an earlier version passed 1057 of 1067 tests. +That contrasts with the original version, which passed 867. The +current parser is top-ranked in terms of conformance, as is its +validating sibling (which has some additional conformance violations +imposed on it by SAX2 API deficiencies as well as some of the more +curious SGML layering artifacts found in the XML specification). </p> + +<p> The XML 1.0 specification itself was not without problems, +and after some delays the W3C has come out with a revised +"second edition" specification. While that doesn't resolve all +the problems identified the XML specification, many of the most +egregious problems have been resolved. (You still need to drink +magic Kool-Aid before some DTD-related issues make sense.) +To the extent possible, this parser conforms to that second +edition specification, and does well against corrected versions +of the OASIS/NIST XML conformance test cases. See <a href= +"http://xmlconf.sourceforge.net">http://xmlconf.sourceforge.net</a> +for more information about SAX2/XML conformance testing. </p> + + +<h3><a name="licensing">Licensing</a></h3> + +<p> As noted above, the original distribution was more or less +public domain. The license had the constraint that modifications +be clearly documented, as has been done here. </p> + +<p> This version is Copyright (c) 1999-2001 by David Brownell, +and all the modifications are distributed under the GNU General +Public License (GPL). It is subject to the "Library Exception", +supporting use in some environments (such as embedded systems where +dynamic linking may not be available) by proprietary code without +necessarily requiring all code to be licencsed under the GPL. +</p> + + +<h2><a name="changes">Changes Since the last Microstar Release</a></h2> + +<p> As noted above, Microstar has not updated this parser since +the summer of 1998, when it released version 1.2a on its web site. +This release is intended to benefit the developer community by +refocusing the API on SAX2, and improving conformance to the extent +that most developers should not need to use another XML parser. </p> + +<p> The code has been cleaned up (referring to the XML 1.0 spec in +all the production numbers in +comments, rather than some preliminary draft, for one example) and +has been sped up a bit as well. +JAXP support has been added, although developers are still +strongly encouraged to use the SAX2 APIs directly. </p> + + +<h3><a name="sax2">SAX2 Support</a></h3> + +<p> The original version of Ælfred did not support the +SAX2 APIs. </p> + +<p> This version supports the SAX2 APIs, exposing the standard +boolean feature descriptors. It supports the "DeclHandler" property +to provide access to all DTD declarations not already exposed +through the SAX1 API. The "LexicalHandler" property is supported, +exposing entity boundaries (including the unnamed external subset) and +things like comments and CDATA boundaries. SAX1 compatibility is +currently provided.</p> + + +<h3><a name="validation">Validation</a></h3> + +<p> In the 'pipeline' package in this same software distribution is an +<a href="../pipeline/ValidationConsumer.html">XML Validation component</a> +using any full SAX2 event stream (including all document type declarations) +to validate. There is now a <a href="XmlReader.html">XmlReader</a> class +which combines that class and this enhanced Ælfred parser, creating +an optionally validating SAX2 parser. </p> + +<p> As noted in the documentation for that validating component, certain +validity constraints can't reliably be tested by a layered validator. +These include all constraints relying on +layering violations (exposing XML at the level of tokens or below, +required since XML isn't a context-free grammar), some that +SAX2 doesn't support, and a few others. The resulting validating +parser is conformant enough for most applications that aren't doing +strange SGML tricks with DTDs. +Moreover, that validating filter can be used without +a parser ... any application component that emits SAX event streams +can DTD-validate its output on demand. </p> + +<h3><a name="smaller">You want Smaller?</a></h3> + +<p> You'll have noticed that the original version of Ælfred +had small size as a top goal. Ælfred2 normally includes a +DTD validation layer, but you can package without that. +Similarly, JAXP factory support is available but optional. +Then the main added cost due to this revision are for +supporting the SAX2 API itself; DTD validation is as +cleanly layered as allowed by SAX2.</p> + +<h3><a name="bugfixes">Bugs Fixed</a></h3> + +<p> Bugs fixed in Ælfred2 include: </p> + +<ol> + <li> Originally Ælfred didn't close file descriptors, which + led to file descriptor leakage on programs which ran for any + length of time. </li> + + <li> NOTATION declarations without system identifiers are + now handled correctly. </li> + + <li> DTD events are now reported for all invocations of a + given parser, not just the first one. </li> + + <li> More correct character handling: <ul> + + <li> Rejects out-of-range characters, both in text and in + character references. </li> + + <li> Correctly handles character references that expand to + surrogate pairs. </li> + + <li> Correctly handles UTF-8 encodings of surrogate pairs. </li> + + <li> Correctly handles Unicode 3.1 rules about illegal UTF-8 + encodings: there is only one legal encoding per character. </li> + + <li> PUBLIC identifiers are now rejected if they have illegal + characters. </li> + + <li> The parser is more correct about what characters are allowed + in names and name tokens. Uses Unicode rules (built in to Java) + rather than the voluminous XML rules, although some extensions + have been made to match XML rules more closely.</li> + + <li> Line ends are now normalized to newlines in all known + cases. </li> + + </ul></li> + + <li> Certain validity errors were previously treated as well + formedness violations. <ul> + + <li> Repeated declarations of an element type are no + longer fatal errors. </li> + + <li> Undeclared parameter entity references are no longer + fatal errors. </li> + + </ul></li> + + <li> Attribute handling is improved: <ul> + + <li> Whitespace must exist between attributes. </li> + + <li> Only one value for a given attribute is permitted. </li> + + <li> ATTLIST declarations don't need to declare attributes. </li> + + <li> Attribute values are normalized when required. </li> + + <li> Tabs in attribute values are normalized to spaces. </li> + + <li> Attribute values containing a literal "<" are rejected. </li> + + </ul></li> + + <li> More correct entity handling: <ul> + + <li> Whitespace must precede NDATA when declaring unparsed + entities.</li> + + <li> Parameter entity declarations may not have NDATA annotations. </li> + + <li> The XML specification has a bug in that it doesn't specify + that certain contexts exist within which parameter entity + expansion must not be performed. Lacking an offical erratum, + this parser now disables such expansion inside comments, + processing instructions, ignored sections, public identifiers, + and parts of entity declarations. </li> + + <li> Entity expansions that include quote characters no longer + confuse parsing of strings using such expansions. </li> + + <li> Whitespace in the values of internal entities is not mapped + to space characters. </li> + + <li> General Entity references in attribute defaults within the + DTD now cause fatal errors when the entity is not defined at the + time it is referenced. </li> + + <li> Malformed general entity references in entity declarations are + now detected. </li> + + </ul></li> + + <li> Neither conditional sections + nor parameter entity references within markup declarations + are permitted in the internal subset. </li> + + <li> Processing instructions whose target names are "XML" + (ignoring case) are now rejected. </li> + + <li> Comments may not include "--".</li> + + <li> Most "]]>" sequences in text are rejected. </li> + + <li> Correct syntax for standalone declarations is enforced. </li> + + <li> Setting a locale for diagnostics only produces an exception + if the language of that locale isn't English. </li> + + <li> Some more encoding names are recognized. These include the + Unicode 3.0 variants of UTF-16 (UTF-16BE, UTF-16LE) as well as + US-ASCII and a few commonly seen synonyms. </li> + + <li> Text (from character content, PIs, or comments) large enough + not to fit into internal buffers is now handled correctly even in + some cases which were originally handled incorrectly.</li> + + <li> Content is now reported for element types for which attributes + have been declared, but no content model is known. (Such documents + are invalid, but may still be well formed.) </li> + +</ol> + +<p> Other bugs may also have been fixed. </p> + +<p> For better overall validation support, some of the validity +constraints that can't be verified using the SAX2 event stream +are now reported directly by Ælfred2. </p> + +</body></html> + =================================================================== Checking out kaffe/libraries/javalib/gnu/xml/dom/package.html RCS: /home/cvs/kaffe/kaffe/libraries/javalib/gnu/xml/dom/package.html,v VERS: 1.1 *************** --- /dev/null Sun Aug 4 19:57:58 2002 +++ kaffe/libraries/javalib/gnu/xml/dom/package.html Tue Dec 2 21:55:56 2003 @@ -0,0 +1,270 @@ +<html><head> +<!-- $Id: package.html,v 1.1 2003/12/02 21:39:55 dalibor Exp $ --> +<title>foo</title> +</head><body> + +<p> This is a Free Software +DOM Level 2 implementation, supporting these features: +"XML", +"Events", "MutationEvents", +"HTMLEvents" (won't generate them though), +"UIEvents" (also won't generate them), +"USER-Events" (a conformant extension), +and +"Traversal" (optional; no TreeWalker yet). +It includes JAXP bootstrapping support, addressing the issue that +DOM (Levels 1 and 2) doesn't include bootstrapping APIs. +It is intended to be a reasonable base both for +experimentation and supporting additional DOM modules as clean layers. +</p> + +<p>Note that while DOM does not specify its behavior in the +face of concurrent access, this implementation does. +Specifically: +if only one thread at a time accesses a Document, +of if several threads cooperate for read-only access, +then no concurrency conflicts will occur. +If several threads mutate a given document +(or send events using it) at the same time, +there is currently no guarantee that +they won't interfere with each other. +</p> + +<h3> Design Goals </h3> + +<p> A number of DOM implementations are available in Java, including +commercial ones from Sun, IBM, Oracle, and DataChannel as well as +noncommercial ones from Docuverse, OpenXML, and Silfide. Why have +another? Some of the goals of this version: </p> <ul> + + <li> DOM Level 2 support. This was the first generally available + implementation of DOM Level 2 in Java. </li> + + <li> Free Software. This one is distributed under the GPL (with + "library exception") so it can be used with a different class of + application. </li> + + <li> Second implementation syndrome. I can do it simpler this time + around ... and heck, writing it only takes a bit over a day once you + know your way around. (Debugging is of course a different story, + since W3C hasn't provided any conformance test suite and publicly + available suites have poor coverage.) </li> + + <li> Sanity check the then-current Last Call DOM draft. Best to find + bugs early, when they're relatively fixable. Yes, bugs were found. + </li> + + <li> Modularity. Most of the implementations mentioned above are part + of huge packages; take all (including bugs, of which some have far + too many), or take nothing. I prefer a menu approach, when possible. + This code is standalone, not beholden to any particular parser or XSL + or XPath code. </li> + + <li> OK, I'm a hacker, I like to write code. </li> + + </ul> + +<p> This also works with the Gnu Compiler for Java (GCJ). GCJ promises +to be quite the environment for programming Java, both directly and from +C++ using the new CNI interfaces (which really use C++, unlike JNI). </p> + + +<h3> Open Issues </h3> + +<p> At this writing: </p> <ul> + + <li> An approximation of XML rules for legal names is used (Unicode + rules with minor tweaks) rather than the huge character tables in the + XML appendix. </li> + + <li> See below for some restrictions on the mutation event + support ... some events aren't reported (and likely won't be). </li> + + <li> There's no implementation (yet) + for the TreeWalker traversal API.</li> + + <li> More testing and conformance work is needed. </li> + + </ul> + +<p> I ran a profiler a few times and remove some of the performance hotspots, +but it's not tuned. Reporting mutation events, in particular, is +rather costly -- it started at about a 40% penalty for appendNode calls, +I've got it down around 12%, but it'll be hard to shrink it much further. +The overall code size is relatively small, though you may want to be rid of +many of the unused DOM interface classes (HTML, CSS, and so on).</p> + + +<h2><a name="features">Features of this Package</a></h2> + +<p> Starting with DOM Level 2, you can really see that DOM is constructed +as a bunch of optional modules around a core of either XML or HTML +functionality. Different implementations will support different optional +modules. This implementation provides a set of features that should be +useful if you're not depending on the HTML functionality (lots of convenience +functions that mostly don't buy much except API surface area) and user +interface support. That is, browsers will want more -- but what they +need should be cleanly layered over what's already here. </p> + +<h3> Core Feature Set: "XML" </h3> + +<p> This DOM implementation supports the "XML" feature set, which basically +gets you four things over the bare core (which you're officially not supposed +to implement except in conjunction with the "XML" or "HTML" feature). In +order of decreasing utility, those four things are: </p> <ol> + + <li> ProcessingInstruction nodes. These are probably the most + valuable thing. Handy little buggers, in part because all the APIs + you need to use them are provided, and they're designed to let you + escape XML document structure rules in controlled ways.</li> + + <li> CDATASection nodes. These are of of limited utility since CDATA + is just text that prints funny. These are of use to some sorts of + applications, though I encourage folk to not use them. </li> + + <li> DocumentType nodes, and associated Notation and Entity nodes. + These appear to be useless. Briefly, these "Type" nodes expose no + typing information. They're only really usable to expose some lexical + structure that almost every application needs to ignore. (XML editors + might like to see them, but they need true typing information much more.) + I strongly encourage people not to use these. </li> + + <li> EntityReference nodes can show up. These are actively annoying, + since they add an extra level of hierarchy, are the cause of most of + the complexity in attribute values, and their contents are immutable. + Avoid these.</li> + + </ol> + +<h3> Optional Feature Sets: "Events", and friends </h3> + +<p> Events may be one of the more interesting new features in Level 2. +This package provides the core feature set and exposes mutation events. +No gooey events though; if you want that, write a layered implementation! </p> + +<p> Three mutation events aren't currently generated:</p> <ul> + + <li> <em>DOMSubtreeModified</em> is poorly specified. Think of this + as generating one such event around the time of finalization, which + is a fully conformant implementation. This implementation is exactly + as useful as that one. </li> + + <li> <em>DOMNodeRemovedFromDocument</em> and + <em>DOMNodeInsertedIntoDocument</em> are supposed to get sent to *** Patch too long, truncated *** _______________________________________________ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe