From 28f2d47f7f922dc1a30ba31f8e47d7d2b37b3536 Mon Sep 17 00:00:00 2001 From: tromey Date: Tue, 26 Jul 2005 23:22:38 +0000 Subject: * 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. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@102404 138bc75d-0d04-0410-961f-82ee72b054a4 --- libjava/gnu/xml/dom/package.html | 273 --------------------------------------- 1 file changed, 273 deletions(-) delete mode 100644 libjava/gnu/xml/dom/package.html (limited to 'libjava/gnu/xml/dom') diff --git a/libjava/gnu/xml/dom/package.html b/libjava/gnu/xml/dom/package.html deleted file mode 100644 index fbc864a4d74..00000000000 --- 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.)

- - - - -- cgit v1.2.3