dleslie 00/07/28 06:30:08
Modified: xdocs/sources xalandesign.xml
xdocs/sources/design design2_0_0.xml
Log:
Updated Xalan-J 2.0 Design document
Revision Changes Path
1.3 +3 -4 xml-xalan/xdocs/sources/xalandesign.xml
Index: xalandesign.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalandesign.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xalandesign.xml 2000/05/31 15:57:44 1.2
+++ xalandesign.xml 2000/07/28 13:30:06 1.3
@@ -58,11 +58,10 @@
* <http://www.apache.org/>.
-->
-<book title="Xalan 1.0.1 Design" copyright="2000 The Apache Software
Foundation">
+<book title="Xalan 2.0.0 Design" copyright="2000 The Apache Software
Foundation">
- <document id="design1_1_0"
+ <document id="design2_0_0"
label="Xalan-J 2.0.0 Design"
- source="design/design1_1_0.xml"/>
-
+ source="design/design2_0_0.xml"/>
</book>
1.2 +13 -15 xml-xalan/xdocs/sources/design/design2_0_0.xml
Index: design2_0_0.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/design/design2_0_0.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- design2_0_0.xml 2000/07/28 02:08:26 1.1
+++ design2_0_0.xml 2000/07/28 13:30:07 1.2
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<!DOCTYPE s1 SYSTEM
"file:///C:\x\xml-stylebook\styles\apachexml\dtd\document.dtd">
+<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Xalan-J 2.0 Design">
<p><link>Xalan-J 2.0 Design</link><img src="xmllogo.gif"
alt="xmllogo.gif"/></p>
<ul>
@@ -11,8 +11,7 @@
<p><link idref="intro">Introduction</link></p>
<p>This document presents the basic design for Xalan-J 2.0, which is a
<jump
href="http://www.awl.com/cseng/titles/0-201-89542-0/techniques/refactoring.htm";>refactoring</jump>
- and redesign of the Xalan-J 1.x proces
- sor. The main goals of this redesign are
+ and redesign of the Xalan-J 1.x processor. The main goals of
this redesign are
to: </p>
<ol>
<li>Make the design and code more understandable by Open Source
@@ -34,17 +33,16 @@
is less prone to error.</li>
<li>Break the transformation process into a separate package,
away from
the stylesheet objects.</li>
- <li>Create this design document, as a start-point for people
wanting to
- approach the code.</li>
+ <li>Create this design document, as a starting point for people
interested in
+ approaching the code.</li>
</ol>
<p>The goals are not:</p>
<ol>
<li>To add more features in the progress of this refactoring.
This is
- design and code clean-up, to meet the above-named goals. In
the course of the
- refactoring, it is expected that it will be <em>much</em>
easier to add
+ design and code clean-up in order to meet the above-named
goals. We expect that it will be <em>much</em> easier to add
features once this work is completed.</li>
- <li>To optimize code for the sake of optimization. However, it
is
- expected that the code will be faster once the work is
complete.</li>
+ <li>To optimize code for the sake of optimization. However, we
+ expect that the code will be faster once this work is
complete.</li>
</ol>
<p>How well we've achieved the goals will be measured by feedback from
the
<link
anchor="http://xml-archive.webweaving.org/xml-archive-xalan";>Xalan-dev</link>
list, and by software metrics tools.</p>
@@ -403,10 +401,10 @@
of which has a list of Counter
objects.</item></gloss><gloss><label>KeyIterator, KeyManager, and
KeyTable</label><item>These classes handle mapping of keys declared with the
xsl:key element.</item></gloss><gloss><label>TransformState</label><item>This
interface is meant to be used by a consumer of SAX2 events produced by Xalan,
and enables the consumer
to get information about the state of the transform. It
is primarily intended as a tooling interface.</item></gloss><p>Even though
the following modules are defined in the org.apache.xalan package, instead of
the transformer package, they are defined in this section as they are mostly
related to runtime transformation.</p>
- <s3 title="Stree Module"><p><link idref="stree">Stree Module [And
discussions about streaming]</link></p><p>The Stree module implements the
default <link anchor="http://www.w3.org/TR/xpath#data-model";>Source Tree
</link> for Xalan, that is to be transformed. It implements read-only <link
anchor="http://www.w3.org/TR/DOM-Level-2/";>DOM2</link> interfaces, and provides
some information needed for fast transforms, such as document order indexes.
It also attempts to allow a streaming transform by launching the transform on a
secondary thread as soon as the SAX2 <link
anchor="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#startDocument()">StartDocument</link>
event has occured. When the transform requests a node, and node is not
present, the getFirstChild and GetNextSibling methods will wait until the child
node has arrived, or an <link
anchor="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String,%20java.lang.String,%20java.lang.St
ring)">endElement</link> event has occured.</p><p>Note that the secondary
thread is an issue. It would be better to do the same thing as described above
on a single thread, but using the parser in 'pull' mode, or simply with a
parseNext method so the parse would occur in blocks.</p><p>This kind of
streaming is not perfect because it still requires an entire source tree to be
concretely built. There have been a lot of good discussions on the xalan-dev
list about how to do static analysis of a stylesheet, and be able to allocate
only the nodes needed by the transform, while they are needed (or not allocate
source objects at all).</p><p>Vincent-Olivier Arsenault <[EMAIL
PROTECTED]> has proposed the following design:</p><p>By looking at the
stylesheet you know how streamable it is (of course this
+ <s3 title="Stree Module"><p><link idref="stree">Stree Module [And
discussions about streaming]</link></p><p>The Stree module implements the
default <link anchor="http://www.w3.org/TR/xpath#data-model";>Source Tree
</link> for Xalan, that is to be transformed. It implements read-only <link
anchor="http://www.w3.org/TR/DOM-Level-2/";>DOM2</link> interfaces, and provides
some information needed for fast transforms, such as document order indexes.
It also attempts to allow a streaming transform by launching the transform on a
secondary thread as soon as the SAX2 <link
anchor="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#startDocument()">StartDocument</link>
event has occurred. When the transform requests a node, and node is not
present, the getFirstChild and GetNextSibling methods will wait until the child
node has arrived, or an <link
anchor="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String,%20java.lang.String,%20java.lang.S
tring)">endElement</link> event has occurred.</p><p>Note that the secondary
thread is an issue. It would be better to do the same thing as described above
on a single thread, but using the parser in 'pull' mode, or simply with a
parseNext method so the parse would occur in blocks.</p><p>This kind of
streaming is not perfect because it still requires an entire source tree to be
concretely built. There have been a lot of good discussions on the xalan-dev
list about how to do static analysis of a stylesheet, and be able to allocate
only the nodes needed by the transform, while they are needed (or not allocate
source objects at all).</p><p>Vincent-Olivier Arsenault <[EMAIL
PROTECTED]> has proposed the following design:</p><p>By looking at the
stylesheet you know how streamable it is (of course this
needs strict adherence to the xslt recommendation). since there's a root
template and no <xsl:apply-templates/> you can build your context list
-containing only absolute x-path (which means nodes get out of context
+containing only absolute xpath which means nodes get out of context
faster).</p>
<p>The paths of the relevant nodes, for this stylesheet, are (ok this is an
@@ -425,7 +423,7 @@
<p>Let me refine:</p>
<p>you analyze the whole stylesheet like that (would be good if optimization
-and x-path list could be done simultaneously) and you end up with a list of
+and xpath list could be done simultaneously) and you end up with a list of
expanded paths mapped to all the templates.</p>
<p>An entry in the list (i would call this list the transformation stack)
would
@@ -445,7 +443,7 @@
</ol>
</s3><s3 title="Extensions Module"><p><link idref="extensions">Extensions
Module</link></p><p>This package contains an implementation of Xalan Extension
Mechanism, which uses the <link
anchor="http://oss.software.ibm.com/developerworks/opensource/bsf/";>Bean
Scripting Framework</link>.
-The Bean Scripting Framework (BSF) is an architecture for incorporating
scripting into Java applications and applets. Scripting languages such as
Netscape Rhino (Javascript), VBScript, Perl, Tcl, Python, NetRexx and Rexx can
be used to augment XSLT's functionality. In addition, the Xalan extension
mechanism allows use of Java classes. See the <link
anchor="http://xml.apache.org/xalan/extensions.html";>XalanJ 1 extension
documentation</link> for a description of using extensions in a stylesheet.
Please note that the W3C XSL Working Group is working on a specification for
standard extension bindings, and this module will change to follow that
specification. </p><p>[More needed... -sb]</p></s3></s2><anchor name="xpath"/>
+The Bean Scripting Framework (BSF) is an architecture for incorporating
scripting into Java applications and applets. Scripting languages such as
Netscape Rhino (Javascript), VBScript, Perl, Tcl, Python, NetRexx and Rexx can
be used to augment XSLT's functionality. In addition, the Xalan extension
mechanism allows use of Java classes. See the <link
anchor="http://xml.apache.org/xalan/extensions.html";>Xalan-J 1 extension
documentation</link> for a description of using extensions in a stylesheet.
Please note that the W3C XSL Working Group is working on a specification for
standard extension bindings, and this module will change to follow that
specification. </p><p>[More needed... -sb]</p></s3></s2><anchor name="xpath"/>
<s2 title="XPath Module">
<p><link idref="xpath">XPath Module</link></p>
<p>This module is pulled out of the Xalan package, and put in the
org.apache package, to emphasize that the intention is that this package can be
used independently of the XSLT engine, even though it has dependencies on the
Xalan utils module.</p><p><img src="org_apache.gif" alt="xalan --->
xpath"/></p>
@@ -454,10 +452,10 @@
low-level XPath
API.</item></gloss><gloss><label>XPathContext</label><item>Used as the runtime
execution context for
XPath.</item></gloss><gloss><label>DOMHelper</label><item>Used as a helper for
handling DOM issues. May be subclassed to take advantage
of specific DOM
implementations.</item></gloss><gloss><label>SourceTreeManager</label><item>bottlenecks
all management of source trees. The methods
in this class should allow easy garbage collection of source
- trees, and should centralize parsing for those source
trees.</item></gloss><gloss><label>Expression</label><item>The base-class of
all expression objects, allowing polymorphic behaviors.</item></gloss><p>The
general architecture of the XPath module is diveded into the compiler, and
categories of expression objects.</p><p><img src="xpath.gif" alt="xpath
modules"/></p><p>The most important module is the axes module. This module
implements the DOM2 <link
anchor="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</link>
interface, and is meant to allow XPath clients to either override the default
behavior or to replace this behavior.</p><p>The LocPathIterator and
UnionPathIterator classes implement the <link
anchor="http://www.w3.org/TR/DOM-Level-2/java-binding.html#org.w3c.dom.traversal.NodeIterator";>NodeIterator</link>
interface, and polymorphically use AxesWalker derived objects to execute each
step in the path. The whole trick is to execute the LocationPath in
depth-first d
ocument order so that nodes can be found without necessarily looking ahead or
performing a bredth-first search.</p><s3 title="XPath Database
Connection"><p><link idref="xpath-database">XPath Direct Database
Connections</link></p><p>An important part of the XPath design in both Xalan 1
and Xalan 2, is to enable database connections to be used as drivers directly
to the XPath <link
anchor="http://www.w3.org/TR/xpath#location-paths";>LocationPath</link>
handling. This allows databases to be directly connected to the transform, and
be able to take advantage of internal indexing and the like. While in Xalan 1
this was done via the <link
anchor="http://xml.apache.org/xalan/apidocs/org/apache/xalan/xpath/XLocator.html";>XLocator</link>
interface, in Xalan 2 this interface is no longer used, and has been replaced
by the DOM2 <link
anchor="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</link>
interface. An application or extension should be able to install their own
NodeIterator for
a given document.</p><p><img src="data.gif" alt="data.gif"/></p><p>[More to
do]</p></s3></s2>
+ trees, and should centralize parsing for those source
trees.</item></gloss><gloss><label>Expression</label><item>The base-class of
all expression objects, allowing polymorphic behaviors.</item></gloss><p>The
general architecture of the XPath module is divided into the compiler, and
categories of expression objects.</p><p><img src="xpath.gif" alt="xpath
modules"/></p><p>The most important module is the axes module. This module
implements the DOM2 <link
anchor="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</link>
interface, and is meant to allow XPath clients to either override the default
behavior or to replace this behavior.</p><p>The LocPathIterator and
UnionPathIterator classes implement the <link
anchor="http://www.w3.org/TR/DOM-Level-2/java-binding.html#org.w3c.dom.traversal.NodeIterator";>NodeIterator</link>
interface, and polymorphically use AxesWalker derived objects to execute each
step in the path. The whole trick is to execute the LocationPath in
depth-first d
ocument order so that nodes can be found without necessarily looking ahead or
performing a breadth-first search.</p><s3 title="XPath Database
Connection"><p><link idref="xpath-database">XPath Direct Database
Connections</link></p><p>An important part of the XPath design in both Xalan 1
and Xalan 2, is to enable database connections to be used as drivers directly
to the XPath <link
anchor="http://www.w3.org/TR/xpath#location-paths";>LocationPath</link>
handling. This allows databases to be directly connected to the transform, and
be able to take advantage of internal indexing and the like. While in Xalan 1
this was done via the <link
anchor="http://xml.apache.org/xalan/apidocs/org/apache/xalan/xpath/XLocator.html";>XLocator</link>
interface, in Xalan 2 this interface is no longer used, and has been replaced
by the DOM2 <link
anchor="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</link>
interface. An application or extension should be able to install their own
NodeIterator for
a given document.</p><p><img src="data.gif" alt="data.gif"/></p><p>[More to
do]</p></s3></s2>
<s2 title="Utils Package">
<p><link idref="utils">Utils Package</link></p>
- <p>This package contains general utilities for use by both the xalan and
xpath packages. It is the intention that many of these utility classes (or
their equivelents) be eventually brought into the org.apache.xml package for
general use. The list of major utilities are as
follows:</p><gloss><label>AttList</label><item>Wraps a DOM attribute list in a
SAX Attributes.</item></gloss><gloss><label>BoolStack, IntStack, IntVector,
etc.</label><item>Simple stacks and vectors for primative
values.</item></gloss><gloss><label>DefaultErrorHandler</label><item>Implements
SAX error handler for default
reporting.</item></gloss><gloss><label>DOMBuilder</label><item>Takes SAX events
(in addition to some extra events
+ <p>This package contains general utilities for use by both the xalan and
xpath packages. It is the intention that many of these utility classes (or
their equivalents) be eventually brought into the org.apache.xml package for
general use. The list of major utilities are as
follows:</p><gloss><label>AttList</label><item>Wraps a DOM attribute list in a
SAX Attributes.</item></gloss><gloss><label>BoolStack, IntStack, IntVector,
etc.</label><item>Simple stacks and vectors for primitive
values.</item></gloss><gloss><label>DefaultErrorHandler</label><item>Implements
SAX error handler for default
reporting.</item></gloss><gloss><label>DOMBuilder</label><item>Takes SAX events
(in addition to some extra events
that SAX doesn't handle yet) and adds the result to a document
or document fragment.</item></gloss><gloss><label>Heap</label><item>Classic
heap
implementation.</item></gloss><gloss><label>MutableAttrListImpl</label><item>Mutable
version of
AttributesImpl.</item></gloss><gloss><label>NameSpace</label><item>A
representation of a
namespace.</item></gloss><gloss><label>NodeVector</label><item>A very simple
table that stores a list of
Nodes.</item></gloss><gloss><label>ObjectPool</label><item>Used for reuse of
objects.</item></gloss><gloss><label>PrefixResolver</label><item>The class that
implements this interface can resolve prefixes
to
namespaces.</item></gloss><gloss><label>PrefixResolverDefault</label><item>This
class implements a generic PrefixResolver for a DOM, that
