mirror of
https://github.com/autc04/Retro68.git
synced 2024-11-08 09:07:53 +00:00
507 lines
20 KiB
HTML
507 lines
20 KiB
HTML
<!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,2000,2001 The Free Software Foundation, Inc.
|
|
*/
|
|
-->
|
|
</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="#copyright">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>
|
|
|
|
<h2><a name="about">About Ælfred</a></h2>
|
|
|
|
<p>Ælfred is a XML parser written in the java programming language.
|
|
|
|
<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="copyright">Copyright and distribution terms</a></h3>
|
|
|
|
<p>
|
|
The software in this package is distributed under the GNU General Public
|
|
License (with a special exception described below).
|
|
</p>
|
|
|
|
<p>
|
|
A copy of GNU General Public License (GPL) is included in this distribution,
|
|
in the file COPYING. If you do not have the source code, it is available at:
|
|
|
|
<a href="http://www.gnu.org/software/classpath/">http://www.gnu.org/software/classpath/</a>
|
|
</p>
|
|
|
|
<pre>
|
|
Linking this library statically or dynamically with other modules is
|
|
making a combined work based on this library. Thus, the terms and
|
|
conditions of the GNU General Public License cover the whole
|
|
combination.
|
|
|
|
As a special exception, the copyright holders of this library give you
|
|
permission to link this library with independent modules to produce an
|
|
executable, regardless of the license terms of these independent
|
|
modules, and to copy and distribute the resulting executable under
|
|
terms of your choice, provided that you also meet, for each linked
|
|
independent module, the terms and conditions of the license of that
|
|
module. An independent module is a module which is not derived from
|
|
or based on this library. If you modify this library, you may extend
|
|
this exception to your version of the library, but you are not
|
|
obligated to do so. If you do not wish to do so, delete this
|
|
exception statement from your version.
|
|
|
|
Parts derived from code which carried the following notice:
|
|
|
|
Copyright (c) 1997, 1998 by Microstar Software Ltd.
|
|
|
|
AElfred is free for both commercial and non-commercial use and
|
|
redistribution, provided that Microstar's copyright and disclaimer are
|
|
retained intact. You are free to modify AElfred for your own use and
|
|
to redistribute AElfred with your modifications, provided that the
|
|
modifications are clearly documented.
|
|
|
|
This program is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
merchantability or fitness for a particular purpose. Please use it AT
|
|
YOUR OWN RISK.
|
|
</pre>
|
|
|
|
<p> Some of this documentation was modified from the original
|
|
Ælfred README.txt file. All of it has been updated. </p>
|
|
|
|
</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>
|
|
|