From 6c8a62bbfea9ae40fa27ffe8b1756cec414d6db3 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 26 Jul 2005 23:22:38 +0000 Subject: package.html, [...]: Removed. * gnu/java/net/protocol/ftp/package.html, gnu/javax/swing/text/html/package.html, gnu/javax/swing/text/html/parser/package.html, gnu/javax/swing/text/html/parser/models/package.html, gnu/javax/swing/text/html/parser/support/package.html, gnu/javax/swing/text/html/parser/support/low/package.html, gnu/xml/aelfred2/package.html, gnu/xml/dom/package.html, gnu/xml/pipeline/package.html, gnu/xml/transform/package.html, gnu/xml/util/package.html, java/awt/geom/doc-files/Area-1.png, java/awt/geom/doc-files/CubicCurve2D-1.png, java/awt/geom/doc-files/CubicCurve2D-2.png, java/awt/geom/doc-files/CubicCurve2D-3.png, java/awt/geom/doc-files/CubicCurve2D-4.png, java/awt/geom/doc-files/CubicCurve2D-5.png, java/awt/geom/doc-files/Ellipse-1.png, java/awt/geom/doc-files/FlatteningPathIterator-1.html, java/awt/geom/doc-files/GeneralPath-1.png, java/awt/geom/doc-files/QuadCurve2D-1.png, java/awt/geom/doc-files/QuadCurve2D-2.png, java/awt/geom/doc-files/QuadCurve2D-3.png, java/awt/geom/doc-files/QuadCurve2D-4.png, java/awt/geom/doc-files/QuadCurve2D-5.png, javax/imageio/package.html, javax/imageio/event/package.html, javax/imageio/metadata/package.html, javax/imageio/spi/package.html, javax/imageio/stream/package.html, javax/swing/border/doc-files/BevelBorder-1.png, javax/swing/border/doc-files/BevelBorder-2.png, javax/swing/border/doc-files/BevelBorder-3.png, javax/swing/border/doc-files/EmptyBorder-1.png, javax/swing/border/doc-files/EtchedBorder-1.png, javax/swing/border/doc-files/EtchedBorder-2.png, javax/swing/border/doc-files/LineBorder-1.png, javax/swing/border/doc-files/MatteBorder-1.png, javax/swing/border/doc-files/MatteBorder-2.png, javax/swing/border/doc-files/MatteBorder-3.png, javax/swing/border/doc-files/MatteBorder-4.png, javax/swing/border/doc-files/MatteBorder-5.png, javax/swing/border/doc-files/MatteBorder-6.png, javax/swing/border/doc-files/SoftBevelBorder-1.png, javax/swing/border/doc-files/SoftBevelBorder-2.png, javax/swing/border/doc-files/SoftBevelBorder-3.png, javax/swing/plaf/basic/doc-files/BasicBorders-1.png, javax/swing/plaf/basic/doc-files/BasicBorders-2.png, javax/swing/plaf/basic/doc-files/BasicBorders.ButtonBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.FieldBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.MarginBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.MenuBarBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.RadioButtonBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.SplitPaneBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.SplitPaneBorder-2.png, javax/swing/plaf/basic/doc-files/BasicBorders.SplitPaneDividerBorder-1.png, javax/swing/plaf/basic/doc-files/BasicBorders.ToggleButtonBorder-1.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-1.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-2.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-3.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-4.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-5.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-6.png, javax/swing/plaf/basic/doc-files/BasicGraphicsUtils-7.png, javax/swing/plaf/doc-files/ComponentUI-1.dia, javax/swing/plaf/doc-files/ComponentUI-1.png, javax/swing/plaf/doc-files/TreeUI-1.png, javax/xml/datatype/package.html, javax/xml/namespace/package.html, javax/xml/parsers/package.html, javax/xml/transform/package.html, javax/xml/transform/dom/package.html, javax/xml/transform/sax/package.html, javax/xml/transform/stream/package.html, javax/xml/validation/package.html, javax/xml/xpath/package.html: Removed. From-SVN: r102404 --- libjava/gnu/java/net/protocol/ftp/package.html | 60 --- libjava/gnu/javax/swing/text/html/package.html | 50 -- .../swing/text/html/parser/models/package.html | 53 --- .../gnu/javax/swing/text/html/parser/package.html | 51 --- .../text/html/parser/support/low/package.html | 47 -- .../swing/text/html/parser/support/package.html | 47 -- libjava/gnu/xml/aelfred2/package.html | 506 --------------------- libjava/gnu/xml/dom/package.html | 273 ----------- libjava/gnu/xml/pipeline/package.html | 255 ----------- libjava/gnu/xml/transform/package.html | 77 ---- libjava/gnu/xml/util/package.html | 20 - 11 files changed, 1439 deletions(-) delete mode 100644 libjava/gnu/java/net/protocol/ftp/package.html delete mode 100644 libjava/gnu/javax/swing/text/html/package.html delete mode 100644 libjava/gnu/javax/swing/text/html/parser/models/package.html delete mode 100644 libjava/gnu/javax/swing/text/html/parser/package.html delete mode 100644 libjava/gnu/javax/swing/text/html/parser/support/low/package.html delete mode 100644 libjava/gnu/javax/swing/text/html/parser/support/package.html delete mode 100644 libjava/gnu/xml/aelfred2/package.html delete mode 100644 libjava/gnu/xml/dom/package.html delete mode 100644 libjava/gnu/xml/pipeline/package.html delete mode 100644 libjava/gnu/xml/transform/package.html delete mode 100644 libjava/gnu/xml/util/package.html (limited to 'libjava/gnu') diff --git a/libjava/gnu/java/net/protocol/ftp/package.html b/libjava/gnu/java/net/protocol/ftp/package.html deleted file mode 100644 index fa3e34d..0000000 --- a/libjava/gnu/java/net/protocol/ftp/package.html +++ /dev/null @@ -1,60 +0,0 @@ - - - - -GNU Classpath - gnu.java.net.protocol.ftp - - - -

-This package contains an FTP client. It can handle both active and passive -mode connections and the various transfer modes and representation types. -

- -

-Interaction with the server is via a simple stream interface. Only one -concurrent stream (input or output) is supported. -

- -

-The control connection to the server can be protected using TLS -(the starttls method). -

- - - diff --git a/libjava/gnu/javax/swing/text/html/package.html b/libjava/gnu/javax/swing/text/html/package.html deleted file mode 100644 index c7e7744..0000000 --- a/libjava/gnu/javax/swing/text/html/package.html +++ /dev/null @@ -1,50 +0,0 @@ - - - - -GNU Classpath - javax.swing.text.html - - -

Provides supporting classes for web browsers, - web robots, web page content analysers, web editors and - other applications applications working with Hypertext - Markup Language (HTML). -

- - - diff --git a/libjava/gnu/javax/swing/text/html/parser/models/package.html b/libjava/gnu/javax/swing/text/html/parser/models/package.html deleted file mode 100644 index 18e61ae..0000000 --- a/libjava/gnu/javax/swing/text/html/parser/models/package.html +++ /dev/null @@ -1,53 +0,0 @@ - - - - -GNU Classpath - gnu.javax.swing.text.html.parser.models - - -

This package contains classes for working with content models. In this implementation, the -standardized content model is pre-processed by transformer into an instance of -node. Node holds a single element of the content model with the optional unary operation. -The derived class list holds multiple nodes connected by the same binary operation. -As the members of this list can also be lists itself, these structures support -the most of required operations. Several cases when the model cannot be expressed using -BNF syntax are handled providing specialised classes that are also derived from node. -

-@author Audrius Meskauskas, Lithuania - - diff --git a/libjava/gnu/javax/swing/text/html/parser/package.html b/libjava/gnu/javax/swing/text/html/parser/package.html deleted file mode 100644 index cd050f9..0000000 --- a/libjava/gnu/javax/swing/text/html/parser/package.html +++ /dev/null @@ -1,51 +0,0 @@ - - - - -GNU Classpath - javax.swing.text.html.parser - - -

Provides the error tolerant, DTD-driven HTML 4.01 parser. -The parser that is used in web robots, html content analysers, -web browsers, web editors and other related applications. -It should compativle with the older HTML versions, supporting -obsoleted HTML featues. This package also includes some -supporting classes.

-@author Audrius Meskauskas, Lithuania - - diff --git a/libjava/gnu/javax/swing/text/html/parser/support/low/package.html b/libjava/gnu/javax/swing/text/html/parser/support/low/package.html deleted file mode 100644 index 1735830..0000000 --- a/libjava/gnu/javax/swing/text/html/parser/support/low/package.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - -GNU Classpath - gnu.javax.swing.text.html.parser.support.low - - -

This package contains classes that are directly used to process -the text input: adapted stream tokenizer, specialized buffer and text-level content models .

-@author Audrius Meskauskas, Lithuania - - diff --git a/libjava/gnu/javax/swing/text/html/parser/support/package.html b/libjava/gnu/javax/swing/text/html/parser/support/package.html deleted file mode 100644 index 97c6439..0000000 --- a/libjava/gnu/javax/swing/text/html/parser/support/package.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - -GNU Classpath - gnu.javax.swing.text.html.parser.support - - -

This package provides various specialised classes, needed by HTML parser. -

-@author Audrius Meskauskas, Lithuania - - diff --git a/libjava/gnu/xml/aelfred2/package.html b/libjava/gnu/xml/aelfred2/package.html deleted file mode 100644 index e204258..0000000 --- a/libjava/gnu/xml/aelfred2/package.html +++ /dev/null @@ -1,506 +0,0 @@ - - - - package overview - - - -

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.

- - - -

About Ælfred

- -

Ælfred is a XML parser written in the java programming language. - -

Design Principles

- -

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.

- -

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.

- -

Ælfred is designed for easy and efficient use over the Internet, -based on the following principles:

    - -
  1. Ælfred must be as small as possible, so that it doesn't add too - much to an applet's download time.
    2. - -
  2. Æ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.)
    3. - -
  3. Ælfred must be compatible with most or all Java implementations - and platforms. (Write once, run anywhere.)
    4. - -
  4. Æ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.)
    5. - -
  5. Ælfred must run as fast as possible, so that it does not slow down - the rest of your program.
    6. - -
  6. Æ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.)
    7. - -
  7. Æ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.)
    8. - -
- -

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 http://www.xml.com) -

- -

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.

- -

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.

- - -

About the Name Ælfred

- -

Æ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.

- -

The initial Æ ligature ("AE)" is also a reminder that XML is -not limited to ASCII.

- - -

Character Encodings

- -

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:

- -

If you use any encoding other than UTF-8 or UTF-16 you should -make sure to label your data appropriately:

- -
-<?xml version="1.0" encoding="ISO-8859-15"?> -
- -

Encodings accessed through java.io.InputStreamReader -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 require 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. -

- -

Note that if you are using the Euro symbol with an fixed length -eight bit encoding, you should probably be using the encoding label -iso-8859-15 or, with a Microsoft OS, cp-1252. -Of course, UTF-8 and UTF-16 handle the Euro symbol directly. -

- - -

Known Conformance Violations

- -

Known conformance issues should be of negligible importance for -most applications, and include:

- -

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).

- -

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 http://xmlconf.sourceforge.net -for more information about SAX2/XML conformance testing.

- - -

Copyright and distribution terms

- -

-The software in this package is distributed under the GNU General Public -License (with a special exception described below). -

- -

-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: - - http://www.gnu.org/software/classpath/ -

- -
-  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.
-
- -

Some of this documentation was modified from the original -Ælfred README.txt file. All of it has been updated.

- -

- - -

Changes Since the last Microstar Release

- -

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.

- -

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.

- - -

SAX2 Support

- -

The original version of Ælfred did not support the -SAX2 APIs.

- -

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.

- - -

Validation

- -

In the 'pipeline' package in this same software distribution is an -XML Validation component -using any full SAX2 event stream (including all document type declarations) -to validate. There is now a XmlReader class -which combines that class and this enhanced Ælfred parser, creating -an optionally validating SAX2 parser.

- -

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.

- -

You want Smaller?

- -

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.

- -

Bugs Fixed

- -

Bugs fixed in Ælfred2 include:

- -
    -
  1. Originally Ælfred didn't close file descriptors, which - led to file descriptor leakage on programs which ran for any - length of time.
    2. - -
  2. NOTATION declarations without system identifiers are - now handled correctly.
    3. - -
  3. DTD events are now reported for all invocations of a - given parser, not just the first one.
    4. - -
  4. More correct character handling:
      - -
    • Rejects out-of-range characters, both in text and in - character references.
      • - -
    • Correctly handles character references that expand to - surrogate pairs.
      • - -
    • Correctly handles UTF-8 encodings of surrogate pairs.
      • - -
    • Correctly handles Unicode 3.1 rules about illegal UTF-8 - encodings: there is only one legal encoding per character.
      • - -
    • PUBLIC identifiers are now rejected if they have illegal - characters.
      • - -
    • 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.
      • - -
    • Line ends are now normalized to newlines in all known - cases.
      • - -
    5. - -
  5. Certain validity errors were previously treated as well - formedness violations.
      - -
    • Repeated declarations of an element type are no - longer fatal errors.
      • - -
    • Undeclared parameter entity references are no longer - fatal errors.
      • - -
    6. - -
  6. Attribute handling is improved:
      - -
    • Whitespace must exist between attributes.
      • - -
    • Only one value for a given attribute is permitted.
      • - -
    • ATTLIST declarations don't need to declare attributes.
      • - -
    • Attribute values are normalized when required.
      • - -
    • Tabs in attribute values are normalized to spaces.
      • - -
    • Attribute values containing a literal "<" are rejected.
      • - -
    7. - -
  7. More correct entity handling:
      - -
    • Whitespace must precede NDATA when declaring unparsed - entities.
      • - -
    • Parameter entity declarations may not have NDATA annotations.
      • - -
    • 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.
      • - -
    • Entity expansions that include quote characters no longer - confuse parsing of strings using such expansions.
      • - -
    • Whitespace in the values of internal entities is not mapped - to space characters.
      • - -
    • 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.
      • - -
    • Malformed general entity references in entity declarations are - now detected.
      • - -
    8. - -
  8. Neither conditional sections - nor parameter entity references within markup declarations - are permitted in the internal subset.
    9. - -
  9. Processing instructions whose target names are "XML" - (ignoring case) are now rejected.
    10. - -
  10. Comments may not include "--".
    11. - -
  11. Most "]]>" sequences in text are rejected.
    12. - -
  12. Correct syntax for standalone declarations is enforced.
    13. - -
  13. Setting a locale for diagnostics only produces an exception - if the language of that locale isn't English.
    14. - -
  14. 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.
    15. - -
  15. 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.
    16. - -
  16. 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.)
    17. - -
- -

Other bugs may also have been fixed.

- -

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.

- - - diff --git a/libjava/gnu/xml/dom/package.html b/libjava/gnu/xml/dom/package.html deleted file mode 100644 index fbc864a..0000000 --- a/libjava/gnu/xml/dom/package.html +++ /dev/null @@ -1,273 +0,0 @@ - - - -

-This is a Free Software DOM Level 3 implementation, supporting these features: -

-It is intended to be a reasonable base both for -experimentation and supporting additional DOM modules as clean layers. -

- -

-Note that while DOM does not specify its behavior in the -face of concurrent access, this implementation does. -Specifically: -

-

- -

Design Goals

- -

-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: -

- - - -

-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).

- - -

Open Issues

- -

At this writing:

- - -

-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). -

- - -

Features of this Package

- -

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.

- -

Core Feature Set: "XML"

- -

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:

    - -
  1. 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.
    2. - -
  2. 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.
    3. - -
  3. 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.
    4. - -
  4. 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.
    5. - -
- -

Optional Feature Sets: "Events", and friends

- -

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!

- -

Three mutation events aren't currently generated:

- -

In addition, certain kinds of attribute modification aren't reported. -A fix is known, but it couldn't report the previous value of the attribute. -More work could fix all of this (as well as reduce the generally high cost -of childful attributes), but that's not been done yet.

- -

Also, note that it is a Bad Thing™ to have the listener -for a mutation event change the ancestry for the target of that event. -Or to prevent mutation events from bubbling to where they're needed. -Just don't do those, OK?

- -

As an experimental feature (named "USER-Events"), you can provide -your own "user" events. Just name them anything starting with "USER-" -and you're set. Dispatch them through, bubbling, capturing, or what -ever takes your fancy. One important thing you can't currently do is -pass any data (like an object) with those events. Maybe later there -will be a "UserEvent" interface letting you get some substantial use -out of this mechanism even if you're not "inside" of a DOM package.

- -

You can create and send HTML events. Ditto UIEvents. Since DOM -doesn't require a UI, it's the UI's job to send them; perhaps that's -part of your application.

- -

This package may be built without the ability to report mutation -events, gaining a significant speedup in DOM construction time. However, -if that is done then certain other features -- notably node iterators -and getElementsByTagname -- will not be available. - - -

Optional Feature: "Traversal"

- -

Each DOM node has all you need to walk to everything connected -to that node. Lightweight, efficient utilities are easily layered on -top of just the core APIs.

- -

Traversal APIs are an optional part of DOM Level 2, providing -a not-so-lightweight way to walk over DOM trees, if your application -didn't already have such utilities for use with data represented via -DOM. Implementing this helped debug the (optional) event and mutation -event subsystems, so it's provided here.

- -

At this writing, the "TreeWalker" interface isn't implemented.

- - - -

DOM Functionality to Avoid

- -

For what appear to be a combination of historical and "committee -logic" reasons, DOM has a number of features which I strongly advise -you to avoid using in your library and application code. These -include the following types of DOM nodes; see the documentation for the -implementation class for more information:

- -

If you really need to use unparsed entities or notations, use SAX; -it offers better support for all DTD-related functionality. -It also exposes actual -document typing information (such as element content models).

- -

Also, when accessing attribute values, use methods that provide their -values as single strings, rather than those which expose value substructure -(Text and EntityReference nodes). (See the DomAttr -documentation for more information.)

- -

Note that many of these features were provided as partial support for -editor functionality (including the incomplete DTD access). Full editor -functionality requires access to potentially malformed lexical structure, -at the level of unparsed tokens and below. Access at such levels is so -complex that using it in non-editor applications sacrifices all the -benefits of XML; editor aplications need extremely specialized APIs.

- -

(This isn't a slam against DTDs, note; only against the broken support -for them in DOM. Even despite inclusion of some dubious SGML legacy features -such as notations and unparsed entities, -and the ongoing proliferation of alternative schema and validation tools, -DTDs are still the most widely adopted tool -to constrain XML document structure. -Alternative schemes generally focus on data transfer style -applications; open document architectures comparable to -DocBook 4.0 don't yet exist in the schema world. -Feel free to use DTDs; just don't expect DOM to help you.)

- - - - diff --git a/libjava/gnu/xml/pipeline/package.html b/libjava/gnu/xml/pipeline/package.html deleted file mode 100644 index 352f4c8..0000000 --- a/libjava/gnu/xml/pipeline/package.html +++ /dev/null @@ -1,255 +0,0 @@ - -blah -<!-- -/* - * Copyright (C) 1999-2001 The Free Software Foundation, Inc. - */ ---> - - -

This package exposes a kind of XML processing pipeline, based on sending -SAX events, which can be used as components of application architectures. -Pipelines are used to convey streams of processing events from a producer -to one or more consumers, and to let each consumer control the data seen by -later consumers. - -

There is a PipelineFactory class which -accepts a syntax describing how to construct some simple pipelines. Strings -describing such pipelines can be used in command line tools (see the -DoParse class) -and in other places that it is -useful to let processing be easily reconfigured. Pipelines can of course -be constructed programmatically, providing access to options that the -factory won't. - -

Web applications are supported by making it easy for servlets (or -non-Java web application components) to be part of a pipeline. They can -originate XML (or XHTML) data through an InputSource or in -response to XML messages sent from clients using CallFilter -pipeline stages. Such facilities are available using the simple syntax -for pipeline construction. - - -

Programming Models

- -

Pipelines should be simple to understand. - -

- - -

Producers: XMLReader or Custom

- -

Many producers will be SAX2 XMLReader objects, and -will read (pull) data which is then written (pushed) as events. -Typically these will parse XML text (acquired from -org.xml.sax.helpers.XMLReaderFactory) or a DOM tree -(using a DomParser) -These may be bound to event consumer using a convenience routine, -EventFilter.bind(). -Once bound, these producers may be given additional documents to -sent through its pipeline. - -

In other cases, you will write producers yourself. For example, some -data structures might know how to write themselves out using one or -more XML models, expressed as sequences of SAX2 event callbacks. -An application module might -itself be a producer, issuing startDocument and endDocument events -and then asking those data structures to write themselves out to a -given EventConsumer, or walking data structures (such as JDBC query -results) and applying its own conversion rules. WAP format XML -(WBMXL) can be directly converted to producer output. - -

SAX2 introduced an "XMLFilter" interface, which is a kind of XMLReader. -It is most useful in conjunction with its XMLFilterImpl helper class; -see the EventFilter javadoc -for information contrasting that XMLFilterImpl approach with the -relevant parts of this pipeline framework. Briefly, such XMLFilterImpl -children can be either producers or consumers, and are more limited in -configuration flexibility. In this framework, the focus of filters is -on the EventConsumer side; see the section on -pipe fitting below. - - -

Consume to Standard or Custom Data Representations

- -

Many consumers will be used to create standard representations of XML -data. The TextConsumer takes its events -and writes them as text for a single XML document, -using an internal XMLWriter. -The DomConsumer takes its events and uses -them to create and populate a DOM Document. - -

In other cases, you will write consumers yourself. For example, -you might use a particular unmarshaling filter to produce objects -that fit your application's requirements, instead of using DOM. -Such consumers work at the level of XML data models, rather than with -specific representations such as XML text or a DOM tree. You could -convert your output directly to WAP format data (WBXML). - - -

Pipe Fitting

- -

Pipelines are composite event consumers, with each stage having -the opportunity to transform the data before delivering it to any -subsequent stages. - -

The PipelineFactory class -provides access to much of this functionality through a simple syntax. -See the table in that class's javadoc describing a number of standard -components. Direct API calls are still needed for many of the most -interesting pipeline configurations, including ones leveraging actual -or logical concurrency. - -

Four basic types of pipe fitting are directly supported. These may -be used to construct complex pipeline networks.

- -

Note that filters can be as complex as -XSLT transforms -available) on input data, or as simple as removing simple syntax data -such as ignorable whitespace, comments, and CDATA delimiters. -Some simple "built-in" filters are part of this package. - - -

Coding Conventions: Filter and Terminus Stages

- -

If you follow these coding conventions, your classes may be used -directly (give the full class name) in pipeline descriptions as understood -by the PipelineFactory. There are four constructors the factory may -try to use; in order of decreasing numbers of parameters, these are:

- -

Of course, classes may support more than one such usage convention; -if they do, they can automatically be used in multiple modes. If you -try to use a terminus class as a filter, and that terminus has a constructor -with the appropriate number of arguments, it is automatically wrapped in -a "tee" filter. - - -

Debugging Tip: "Tee" Joints can Snapshot Data

- -

It can sometimes be hard to see what's happening, when something -goes wrong. Easily fixed: just snapshot the data. Then you can find -out where things start to go wrong. - -

If you're using pipeline descriptors so that they're easily -administered, just stick a write ( filename ) -filter into the pipeline at an appropriate point. - -

Inside your programs, you can do the same thing directly: perhaps -by saving a Writer (perhaps a StringWriter) in a variable, using that -to create a TextConsumer, and making that the first part of a tee -- -splicing that into your pipeline at a convenient location. - -

You can also use a DomConsumer to buffer the data, but remember -that DOM doesn't save all the information that XML provides, so that DOM -snapshots are relatively low fidelity. They also are substantially more -expensive in terms of memory than a StringWriter holding similar data. - -

Debugging Tip: Non-XML Producers

- -

Producers in pipelines don't need to start from XML -data structures, such as text in XML syntax (likely coming -from some XMLReader that parses XML) or a -DOM representation (perhaps with a -DomParser). - -

One common type of event producer will instead make -direct calls to SAX event handlers returned from an -EventConsumer. -For example, making ContentHandler.startElement -calls and matching ContentHandler.endElement calls. - -

Applications making such calls can catch certain -common "syntax errors" by using a -WellFormednessFilter. -That filter will detect (and report) erroneous input data -such as mismatched document, element, or CDATA start/end calls. -Use such a filter near the head of the pipeline that your -producer feeds, at least while debugging, to help ensure that -you're providing legal XML Infoset data. - -

You can also arrange to validate data on the fly. -For DTD validation, you can configure a -ValidationConsumer -to work as a filter, using any DTD you choose. -Other validation schemes can be handled with other -validation filters. - - diff --git a/libjava/gnu/xml/transform/package.html b/libjava/gnu/xml/transform/package.html deleted file mode 100644 index d435596..0000000 --- a/libjava/gnu/xml/transform/package.html +++ /dev/null @@ -1,77 +0,0 @@ - - - -

GNU JAXP XSL transformer

- -
-This package contains a Java XSL transformer compliant with the JAXP -specification. It depends on the GNU DOM and XPath implementations, and -will generate GNU DOM nodes unless a specific target from another -implementation was given. It understands DOM, SAX, and stream sources -and result sinks and supports these JAXP features. -
- -
-To use this transformer, set the system property -javax.xml.transform.TransformerFactory to the value -gnu.xml.transform.TransformerFactoryImpl. You can then -instantiate TransformerFactory -and transformers in the ordinary manner. Reuse of stylesheets is -supported using the JAXP Templates -mechanism. -
- -

Architecture

- -
-When given a stylesheet source, this implementation compiles it internally -into a Stylesheet object, which is a container for templates and state. -Each stylesheet instruction is represented by a subclass of TemplateNode, -which is arranged in a directed graph: each TemplateNode has a reference -to its first child and the next node. -
- -
-The transformation process consists of identifying the Template that matches -the root of the source context, and calling apply on its -corresponding TemplateNode. This in turn processes its children and next -TemplateNode, depending on the semantics of each node type. -
- -
-Template nodes may reference XPath expressions or patterns. These are fully -compiled to objects of type Expr at the -time the stylesheet is compiled. -
- -

Conformance

- -
-This implementation is feature complete, but the XSLT specification is -large and there are still many bugs that need to be ironed out. It has -been tested against the OASIS XSLT TC test suite, comprising unit tests -from the Xalan project and Microsoft. Conformance to these unit tests -is approximately 70% at the current time, although normal usage of the -transformer should involve relatively few surprises (the test suite is -designed to test very complex and obscure functionality). -
- -

Known bugs

- - - -
-Obviously we'd like to improve conformance and fix these bugs. If you're -interested in working on any of these issues please -contact us. -
- - - diff --git a/libjava/gnu/xml/util/package.html b/libjava/gnu/xml/util/package.html deleted file mode 100644 index 6e6c0d7..0000000 --- a/libjava/gnu/xml/util/package.html +++ /dev/null @@ -1,20 +0,0 @@ - - - org.brownell.xml package - - -

This package contains XML utilities, including SAX2 XML writers - and a parser of DOM trees, plus a command line driver. - That driver - connects parsers simple processing pipelines. - It can be handy for command line validation or - transformation tasks, possibly in batch mode, - or within Makefiles.

- - -- cgit v1.1