sboag 01/01/11 23:46:58
Modified: java/xdocs/sources/design design2_0_0.xml trax.gif
xalan1_1x1.gif
Added: java/xdocs/sources/design compilation.gif xalan.gif
xslt_abstract.gif
Log:
Update of design doc to match reality.
Revision Changes Path
1.3 +63 -314 xml-xalan/java/xdocs/sources/design/design2_0_0.xml
Index: design2_0_0.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/design/design2_0_0.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- design2_0_0.xml 2001/01/10 20:48:27 1.2
+++ design2_0_0.xml 2001/01/12 07:46:58 1.3
@@ -5,7 +5,8 @@
<p>Author: Scott Boag<br/>State: In Progress</p>
<ul>
<li><link anchor="intro">Introduction</link></li>
- <li><link anchor="overarch">Overview of Architecture</link></li>
+ <li><link anchor="requirements">Xalan Requirements</link></li>
+ <li><link anchor="overarch">Overview of Architecture</link></li>
<li><link anchor="process">Process Module</link></li>
<li><link anchor="templates">Templates Module</link></li>
<li><link anchor="transformer">Transformer Module</link></li>
@@ -17,26 +18,25 @@
<ul><li><link anchor="xpathdbconn">XPath Database
Connection</link></li></ul>
<li><link anchor="utils">Utils Package</link></li>
<li><link anchor="other">Other Packages</link></li>
- <li><link anchor="coding">Coding Conventions</link></li>
- <li><link anchor="open">Open Issues</link></li>
+ <li><link anchor="compilation">Xalan Stylesheet Complilation to
Java</link></li><li><link anchor="optimizations">Future
Optimizations</link></li><li><link anchor="coding">Coding
Conventions</link></li>
+
<li><jump href="../apidocs/index.html">Xalan-J 2.0 Javadoc</jump></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
<p><link>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 processor. The main goals of
this redesign are
- to: </p>
- <ol>
+ and redesign of the Xalan-J 1.x processor. This document will
expand and grow over time, and is also incomplete in some sections, though
hopefully overall accurate. The reader should be able to get a good overall
idea of the internal design of Xalan, and begin to understand the process flow,
and also the technical challanges.</p>
+ <p>The main goals of this redesign are
+ to: </p><ol>
<li>Make the design and code more understandable by Open Source
people.</li>
<li>Reduce code size and complexity.</li>
<li>By simplifying the code, make optimization easier.</li>
<li>Make modules generally more localized, and less tangled
with other
modules.</li>
- <li>Begin the adoption of the TrAX (Transformations for XML)
- interfaces.</li>
- <li>Increase the streamability of transformations.</li></ol>
+ <li>Conform to the <jump
href="http://java.sun.com/aboutJava/communityprocess/jsr/jsr_063_jaxp11.html";>javax.xml.transform
(TrAX [Transformations for XML])</jump> interfaces.</li>
+ <li>Increase the ability to incrementally produce the result
tree.</li></ol>
<p>The techniques used toward these goals are to:</p>
<ol>
<li>In general, flatten the hierarchy of packages, in order to
make the
@@ -59,13 +59,21 @@
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
- <jump
href="http://xml-archive.webweaving.org/xml-archive-xalan";>Xalan-dev</jump>
list, and by software metrics tools.</p>
+ <jump href="http://archive.covalent.net/";>Xalan-dev</jump>
list, and by software metrics tools.</p>
<p>Please note that the diagrams in this design document are meant to
be
useful abstractions, and may not always be exact.</p>
- </s2><anchor name="overarch"/>
+ </s2><anchor name="requirements"/>
+ <s2 title="Xalan Requirements"><p><link>Xalan
Requirements</link></p><p>These are the concrete general requirements of Xalan,
as I understand them, and covering both the Java and C++ versions. These
requirements have been built up over time by experience with product groups and
general users.</p><ol><li>Java, C++ Versions.</li><li>XSLT 1.0 conformance, and
beyond. (i.e. conform to the current W3C recommendation).</li><li>Have design
and Code understandable by Open Source Community.</li><li>Ability to
interoperate with standard APIs. (SAX2, DOM2, JAXP) [this is currently Less
of an issue with C++].</li><li>High Performance (Raw performance, Incremental
ability, Scaleability to large documents, Reduction of Garbage Collection for
the Java version.)</li><li>Tooling API (Access stylesheet data structures,
Access source node from result event, Ask runtime questions, Debugging
API).</li><li>Support addressing of XML in standalone fashion (i.e. XPath
API).</li><li>Extensibility (Ability to call Java, Ability to call JavaScript,
other languages).</li><li>Multiple data sources (JDBC, LDAP, other data
sources, Direct XML repository coupling).</li></ol></s2><anchor
name="overarch"/>
<s2 title="Overview of Architecture">
- <p><link>Overview of Architecture</link></p>
- <p>Xalan 2.0 is divided into four major modules, and various smaller
+ <p><link>Overview of Architecture</link></p><p>The following diagram
shows the XSLT abstract processing model. A transformation expressed in XSLT
describes rules for transforming a <jump
href="http://www.w3.org/TR/xpath#data-model";>Source Tree </jump> into a result
tree. The transformation is achieved by associating patterns with templates. A
pattern is matched against elements in the source tree. A template is
instantiated to create part of the result tree. The result tree is separate
from the source tree. The structure of the result tree can be completely
different from the structure of the source tree. In constructing the result
tree, elements from the source tree can be filtered and reordered, and
arbitrary structure can be added.
+
+</p><p>The term "tree", as used within this document, describes an
+ abstract structure that consists of nodes or events
that may be produced by
+ XML. A Tree physically may be a DOM tree, a series of
well balanced parse
+ events (such as those coming from a SAX2
ContentHander), a series of requests
+ (the result of which can describe a tree), or a stream
of marked-up
+ characters.</p><p><img src="xslt_abstract.gif"
alt="xslt_abstract.gif"/></p><p>The primary interface for Xalan 2.0 external
usage is defined in the <jump
href="../apidocs/javax/xml/transform/package-summary.html#package_description">javax.xml.transform</jump>
interfaces. These interfaces define a standard and powerful interface to
perform tree-based transformations.</p>
+ <p>The internal architecture of Xalan 2.0 is divided into four major
modules, and various smaller
modules. The main modules are:</p>
<gloss>
<label><code><jump
href="../apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump></code></label>
@@ -89,7 +97,7 @@
patterns.</item>
</gloss>
<p>In addition to the above modules, Xalan implements the
- <jump href="http://trax.openxml.org/";>TrAX</jump> interfaces,
and depends on the
+ <jump
href="../apidocs/javax/xml/transform/package-summary.html#package_description">javax.xml.transform</jump>
interfaces, and depends on the
<jump href="http://www.megginson.com/SAX/Java/index.html";>SAX2</jump>
and <jump href="http://www.w3.org/TR/DOM-Level-2/";>DOM</jump> packages.
</p><p><img src="trax.gif" alt="trax.gif"/></p><p>There is also a general
utilities package that contains both XML utility
classes such as QName, but generally useful classes such as
@@ -121,6 +129,7 @@
<item>This holds resource files needed by Xalan, such as error
message
resources.</item>
</gloss>
+
<gloss>
<label><code><jump
href="../apidocs/org/apache/xalan/trace/package-summary.html">org.apache.xalan.trace</jump></code></label>
<item>This package contains classes and interfaces that allow a
caller to
@@ -129,60 +138,58 @@
</gloss>
<gloss>
<label><code><jump
href="../apidocs/org/apache/xalan/xslt/package-summary.html">org.apache.xalan.xslt</jump></code></label>
- <item>This package is for backwards compatibility with
applications that
- depend on Xalan 1.x interfaces.</item>
+ <item>This package holds the Xalan2 command line
processor.</item>
</gloss>
<p>A more conceptual view of this architecture is as follows:</p><p><img
src="conceptual.gif" alt="Picture of conceptual
architecture."/></p></s2><anchor name="process"/>
<s2 title="Process Module">
- <p><link>Process Module</link></p>
- <p>The <code>org.apache.xalan.process</code> module implements the
- <code>org.apache.xalan.trax.Processor</code> interface, which
provides a
+ <p><link>Processor Module</link></p>
+ <p>The <code><jump
href="../apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump></code>
module implements the
+ <code><jump
href="../apidocs/javax/xml/transform/TransformerFactory.html">javax.xml.transform.TransformerFactory</jump></code>
interface, which provides a
factory method for creating a concrete Processor instance, and
provides methods
- for creating a <code>org.apache.xalan.trax.Templates</code>
instance, which, in
+ for creating a <code><jump
href="../apidocs/javax/xml/transform/Templates.html">javax.xml.transform.Templates</jump></code>
instance, which, in
Xalan and XSLT terms, is the Stylesheet. Thus the task of the
process module is
to read the XSLT input in the form of a file, stream, SAX
events, or a DOM
tree, and produce a Templates/Stylesheet object.</p>
- <p>The overall strategy is to define a schema that dictates the legal
+ <p>The overall strategy is to define a schema in that dictates the
legal
structure for XSLT elements and attributes, and to associate
with those
elements construction-time processors that can fill in the
appropriate fields
in the top-level Stylesheet object, and also associate classes
in the templates
module that can be created in a generalized fashion. This makes
the validation
object-to-class associations centralized and declarative.</p>
<p>The schema's root class is
- <code>org.apache.xalan.processor.XSLTSchema</code>, and it is
here that the
+ <code><jump
href="../apidocs/org/apache/xalan/processor/XSLTSchema.html">org.apache.xalan.processor.XSLTSchema</jump></code>,
and it is here that the
XSLT schema structure is defined. XSLTSchema uses
- <code>org.apache.xalan.processor.XSLTElementDef</code> to
define elements, and
- <code>org.apache.xalan.processor.XSLTAttributeDef</code> to
define attributes.
+ <code><jump
href="../apidocs/org/apache/xalan/processor/XSLTElementDef.html">org.apache.xalan.processor.XSLTElementDef</jump></code>
to define elements, and
+ <code><jump
href="../apidocs/org/apache/xalan/processor/XSLTAttributeDef.html">org.apache.xalan.processor.XSLTAttributeDef</jump></code>
to define attributes.
Both classes hold the allowed namespace, local name, and type
of element or
attribute. The XSLTElementDef also holds a reference to a
- <code>org.apache.xalan.processor.XSLTElementProcessor</code>,
and a sometimes a
+ <code><jump
href="../apidocs/org/apache/xalan/processor/XSLTElementProcessor.html">org.apache.xalan.processor.XSLTElementProcessor</jump></code>,
and a sometimes a
<code>Class</code> object, with which it can create objects
that derive from
- <code>org.apache.xalan.templates.ElemTemplateElement</code>. In
addition, the
+ <code><jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html">org.apache.xalan.templates.ElemTemplateElement</jump></code>.
In addition, the
XSLTElementDef instance holds a list of XSLTElementDef
instances that define
legal elements or character events that are allowed as children
of the given
element.</p>
- <p>The implementation of the
<code>org.apache.xalan.trax.Processor</code>
- interface is in
<code>org.apache.xalan.processor.StylesheetProcessor</code>,
- which creates a
<code>org.apache.xalan.processor.StylesheetHandler</code>
+ <p>The implementation of the <code><jump
href="../apidocs/javax/xml/transform/TransformerFactory.html">javax.xml.transform.TransformerFactory</jump></code>
+ interface is in <code><jump
href="../apidocs/org/apache/xalan/processor/TransformerFactoryImpl.html">org.apache.xalan.processor.TransformerFactoryImpl</jump></code>,
+ which creates a <code><jump
href="../apidocs/org/apache/xalan/processor/StylesheetHandler.html">org.apache.xalan.processor.StylesheetHandler</jump></code>
instance. This instance acts as the ContentHandler for the
parse events, and is
- handed to the <code>org.xml.sax.XMLReader</code>, which the
StylesheetProcessor
- uses to parse the XSLT document. The StylesheetHandler then
receives the parse
+ handed to the <code><jump
href="../apidocs/org/xml/sax/XMLReader.html">org.xml.sax.XMLReader</jump></code>,
which the StylesheetProcessor
+ uses to parse the XSLT document. The
<code>StylesheetHandler</code> then receives the parse
events, which maintains the state of the construction, and
passes the events on
- to the appropriate XSLTElementProcessor for the given event, as
dictated by the
- XSLTElementDef that is associated with the given event.</p>
- <p><img src="process.gif" alt="process.gif"/></p>
- </s2><anchor name="templates"/>
+ to the appropriate <code>XSLTElementProcessor</code> for the
given event, as dictated by the
+ <code>XSLTElementDef</code> that is associated with the given
event.</p>
+ </s2><anchor name="templates"/>
<s2 title="Templates Module">
<p><link>Templates Module</link></p>
- <p>The <code>org.apache.xalan.templates</code> module implements the
- <code>org.apache.xalan.trax.Templates</code> interface, and
defines a set of
+ <p>The <code><jump
href="../apidocs/org/apache/xalan/templates/package-summary.html">org.apache.xalan.templates</jump></code>
module implements the
+ <code><jump
href="../apidocs/javax/xml/transform/Templates.html">javax.xml.transform.Templates</jump></code>
interface, and defines a set of
classes that represent a Stylesheet. The primary purpose of
this module is to
hold stylesheet data, not to perform procedural tasks
associated with the
construction of the data, nor tasks associated with the
transformation itself.
</p>
- <p>A <code>StylesheetRoot</code>, which implements the
- <code>Templates</code> interface, is a type of
<code>StylesheetComposed</code>,
- which is a <code>Stylesheet</code> composed of itself and all
included
+ <p>The base class of all templates objects that are associated with an
XSLT element is the <code><jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html">ElemTemplateElement</jump></code>
object, which in turn implements <code><jump
href="../apidocs/org/apache/xml/utils/UnImplNode.html">UnImplNode</jump></code>.
A <code>ElemTemplateElement</code> object must be immutable once it's
constructed, so that it may be shared among multiple threads concurrently.
Ideally, a <code>ElemTemplateElement</code> should be a data object only, and
be used via a visitor pattern. However, in practice this is impractical,
because it would cause too much data exposure and would have a significant
impact on performance. Therefore, each <code>ElemTemplateElement</code> class
has an <code><jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html#execute(org.apache.xalan.transformer.TransformerImpl,
org.w3c.dom.Node, org.apache.xml.utils.QName)">execute</jump></code> method
where it performs it's transformation duties. A
<code>ElemTemplateElement</code> also knows it's position in the source
stylesheet, and can answer questions about current namespace nodes.</p><p>A
<code><jump
href="../apidocs/org/apache/xalan/templates/StylesheetRoot.html">StylesheetRoot</jump></code>,
which implements the
+ <code>Templates</code> interface, is a type of <code><jump
href="../apidocs/org/apache/xalan/templates/StylesheetComposed.html">StylesheetComposed</jump></code>,
+ which is a <code><jump
href="../apidocs/org/apache/xalan/templates/Stylesheet.html">Stylesheet</jump></code>
composed of itself and all included
<code>Stylesheet</code> objects. A <code>StylesheetRoot</code>
has a global
imports list, which is a list of all imported
<code>StylesheetComposed</code>
instances. From each <code>StylesheetComposed</code> object,
one can iterate
@@ -199,265 +206,27 @@
<code>StylesheetComposed</code> derivative object, if it is a
root
<code>Stylesheet</code> or imported <code>Stylesheet</code>,
has "composed"
getter methods that do take into account imported and included
stylesheets, for
- some of these properties. The table of Stylesheet properties,
with composed
- methods, is as follows. Note that the names of the attributes
are according to
- a formula for translating the xsl names to the Java get/set
method names.</p>
- <table>
- <tr>
- <th>Property</th>
- <th>Type</th>
- <th>XSL Origin</th>
- <th>Composed Methods</th>
- <th>Note</th>
- </tr>
- <tr>
- <td>XmlnsXsl</td>
- <td>String</td>
- <td>xmlns:xsl</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- <tr>
- <td>ExtensionElementPrefixes</td>
- <td>StringVector</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#extension-element";>extension-element-prefixes</jump></code>
- attribute</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- <tr>
- <td>ExcludeResultPrefixes</td>
- <td>StringVector</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#literal-result-element";>exclude-result-prefixes
- or xsl:exclude-result-prefixes</jump></code>
attributes</td>
- <td>(not sure about this... only from root?)</td>
- <td>I think this should be a root method, and a single list
should be
- made, like with xsl:output.</td>
- </tr>
- <tr>
- <td>Id</td>
- <td>String</td>
- <td>The <code><jump
href="http://www.w3.org/TR/xslt#section-Embedding-Stylesheets";>id</jump></code>
- attribute</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- <tr>
- <td>Version</td>
- <td>String</td>
- <td>The <code><jump
href="http://www.w3.org/TR/xslt#forwards";>version</jump></code> attribute</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- <tr>
- <td>XmlSpace</td>
- <td>boolean</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#strip";>xml:space</jump></code> attribute</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- <tr>
- <td>Import</td>
- <td>Vector (list of StylesheetComposed objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#import";>xsl:import</jump></code> element</td>
- <td>getImportComposed(int i) / getImportCountComposed()</td>
- <td>Composed list contains all imported sheets, not the
importing sheet
- itself.</td>
- </tr>
- <tr>
- <td>Include</td>
- <td>Vector (list of Stylesheet objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#include";>xsl:include</jump></code> element</td>
-
- <td>getIncludeComposed(int i) /
getIncludeCountComposed()</td>
- <td>Composed list contains all directly or indirectly included
- stylesheets.</td>
- </tr>
- <tr>
- <td>DecimalFormat</td>
- <td>Stack (list of DecimalFormatProperties objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#format-number";>xsl:decimal-format</jump></code>
- element</td>
- <td>getDecimalFormatComposed(QName name)</td>
- <td></td>
- </tr>
- <tr>
- <td>StripSpaces</td>
- <td>Stack (list of XPath match pattern objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#strip";>xsl:strip-space</jump></code>
- element</td>
- <td>getWhiteSpaceInfo(TransformerImpl transformContext, Node
- sourceTree, Element targetElement)</td>
- <td></td>
- </tr>
- <tr>
- <td>PreserveSpaces</td>
- <td>Stack (list of XPath match pattern objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#strip";>xsl:preserve-space</jump></code>
- element</td>
- <td>getWhiteSpaceInfo(TransformerImpl transformContext, Node
- sourceTree, Element targetElement)</td>
- <td></td>
- </tr>
- <tr>
- <td>Output</td>
- <td>OutputFormatExtended</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#output";>xsl:output</jump></code> element</td>
- <td>getOutputComposed() on StylesheetRoot only</td>
- <td></td>
- </tr>
- <tr>
- <td>Key</td>
- <td>Vector (list of KeyDeclaration objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#key";>xsl:key</jump></code> element</td>
- <td>getKeysComposed()</td>
- <td></td>
- </tr>
- <tr>
- <td>AttributeSet</td>
- <td>Vector (list of ElemAttributeSet objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#attribute-sets";>xsl:attribute-set</jump></code>
- element</td>
- <td>On StylesheetRoot only?</td>
- <td></td>
- </tr>
- <tr>
- <td>Variable</td>
- <td>Vector (list of ElemVariable objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#top-level-variables";>xsl:variable</jump></code>
- element</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td>Param</td>
- <td>Vector (list of ElemParam objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#top-level-variables";>xsl:param</jump></code>
- element</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td>Template</td>
- <td>Vector (list of ElemTemplate objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#section-Defining-Template-Rules";>xsl:template</jump></code>
- element</td>
- <td>getTemplateComposed(TransformerImpl transformContext, Node
- sourceTree, Node targetNode, QName mode) and
getTemplateComposed(QName
- qname)</td>
- <td></td>
- </tr>
- <tr>
- <td>NamespaceAlias</td>
- <td>Vector (list of ElemTemplate objects)</td>
- <td><code><jump
href="http://www.w3.org/TR/xslt#literal-result-element";>xsl:namespace-alias</jump></code>
- element</td>
- <td>On StylesheetRoot only?</td>
- <td></td>
- </tr>
- <tr>
- <td>NonXslTopLevel</td>
- <td>Hashtable (table of opaque objects keyed by QName)</td>
- <td>Any top-level non-xslt element.</td>
- <td>none.</td>
- <td></td>
- </tr>
- <tr>
- <td>Href</td>
- <td>URL</td>
- <td>The location of the stylesheet, possibly set by
xsl:include or
- xsl:import.</td>
- <td>none.</td>
- <td></td>
- </tr>
- <tr>
- <td>StylesheetRoot</td>
- <td>StylesheetRoot</td>
- <td>The root of the stylesheet tree, for quick access.</td>
- <td>none.</td>
- <td></td>
- </tr>
- <tr>
- <td>StylesheetParent</td>
- <td>Stylesheet</td>
- <td>The importing or including stylesheet.</td>
- <td>none.</td>
- <td></td>
- </tr>
- <tr>
- <td>StylesheetComposed</td>
- <td>StylesheetComposed</td>
- <td>The closest importing stylesheet.</td>
- <td>none.</td>
- <td></td>
- </tr>
- <tr>
- <td>NamespaceDecls</td>
- <td>Linked list of NameSpace elements</td>
- <td>xmlns:foo attribute map</td>
- <td>(none, applies to stylesheet only)</td>
- <td></td>
- </tr>
- </table>
+ some of these properties.</p>
+
</s2><anchor name="transformer"/>
<s2 title="Transformer Module">
<p><link>Transformer Module</link></p>
- <p>The <jump
href="../apidocs/org/apache/xalan/transformer/package-summary.html">Transformer</jump>
module is in charge of run-time transformations. The <jump
href="../apidocs/org/apache/xalan/transformer/TransformerImpl.html">TransformerImpl</jump>
object, which implements the TrAX <jump
href="http://trax.openxml.org/javadoc/trax/Transformer.html";>Transformer</jump>
interface, and has an association with a <jump
href="../apidocs/org/apache/xalan/templates/StylesheetRoot.html">StylesheetRoot</jump>
object, begins the processing of the source tree (or provides a <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html";>ContentHandler</jump>
reference), and performs the transformation. The Transformer package does as
much of the transformation as it can, but element level operations are
generally performed in the <jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html#execute(org.apache.xalan.transformer.TransformerImpl,
org.w3c.dom.Node,
org.apache.xalan.utils.QName)">ElemTemplateElement.execute(...)</jump>
methods.</p><p>Result Tree events are fed into a <jump
href="../apidocs/org/apache/xalan/transformer/ResultTreeHandler.html">ResultTreeHandler</jump>
object, which acts as a layer between the direct calls to the result
-tree content handler (often a Serializer), and the Transformer. For one
thing,
+ <p>The <jump
href="../apidocs/org/apache/xalan/transformer/package-summary.html">Transformer</jump>
module is in charge of run-time transformations. The <jump
href="../apidocs/org/apache/xalan/transformer/TransformerImpl.html">TransformerImpl</jump>
object, which implements the TrAX <jump
href="../apidocs/javax/xml/transform/Transformer.html">Transformer</jump>
interface, and has an association with a <jump
href="../apidocs/org/apache/xalan/templates/StylesheetRoot.html">StylesheetRoot</jump>
object, begins the processing of the source tree (or provides a <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html";>ContentHandler</jump>
reference via the<code><jump
href="../apidocs/org/apache/xalan/stree/SourceTreeHandler.html">SourceTreeHandler</jump></code>),
and performs the transformation. The Transformer package does as much of the
transformation as it can, but element level operations are generally performed
in the <jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html#execute(org.apache.xalan.transformer.TransformerImpl,
org.w3c.dom.Node,
org.apache.xalan.utils.QName)">ElemTemplateElement.execute(...)</jump>
methods.</p><p>Result Tree events are fed into a <jump
href="../apidocs/org/apache/xalan/transformer/ResultTreeHandler.html">ResultTreeHandler</jump>
object, which acts as a layer between the direct calls to the result
+tree content handler (often a <jump
href="../apidocs/org/apache/xalan/serialize/package-summary.html">Serializer</jump>),
and the <code>Transformer</code>. For one thing,
we have to delay the call to
startElement(name, atts) because of the
xsl:attribute and xsl:copy calls. In other words,
the attributes have to be fully collected before you
- can call startElement.</p><p>Other important classes in this package
are:</p><gloss><label>CountersTable and Counter</label><item>The Counter class
does incremental counting for support of xsl:number.
+ can call startElement.</p><p>Other important classes in this package
are:</p><gloss><label>CountersTable and Counter</label><item>The <code><jump
href="../apidocs/org/apache/xalan/transformer/Counter.html">Counter</jump></code>
class does incremental counting for support of xsl:number.
This class stores a cache of counted nodes (m_countNodes).
It tries to cache the counted nodes in document order...
- the node count is based on its position in the cache list. The
CountersTable class is a table of counters, keyed by ElemNumber objects, each
- 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
+ the node count is based on its position in the cache list. The <code><jump
href="../apidocs/org/apache/xalan/transformer/CountersTable.html">CountersTable</jump></code>
class is a table of counters, keyed by <code><jump
href="../apidocs/org/apache/xalan/templates/ElemNumber.html">ElemNumber</jump></code>
objects, each
+ of which has a list of <code>Counter</code>
objects.</item></gloss><gloss><label>KeyIterator, KeyManager, and
KeyTable</label><item>These classes handle mapping of keys declared with the
xsl:key element. They attempt to work incrementally, locating nodes on request
but indexing all as they traverse the tree, and stopping when the requested
node is found. If a requested node is not found, then the entire tree will be
traversed. Such is the nature of
xsl:key.</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><anchor name="stree"/>
- <s3 title="Stree Module"><p><link>Stree Module [And discussions about
streaming]</link></p><p>The Stree module implements the default <jump
href="http://www.w3.org/TR/xpath#data-model";>Source Tree </jump> for Xalan,
that is to be transformed. It implements read-only <jump
href="http://www.w3.org/TR/DOM-Level-2/";>DOM2</jump> 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 <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#startDocument()">StartDocument</jump>
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 <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String,%20java.lang.String,%20java.lang.String)">endElement</jump>
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 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
-example, so I may be missing some):</p>
-<ol>
-<li>path: "/address" context: "address" (at </address>, you get rid of
the
-whole "person/address" stuff);</li>
-
-<li>path: "/adn" context: "adn";</li>
-
-<li>path: "/medicalrecord" context: "/" (for possibly repetitive nodes, the
-context is always the parent node).</li>
-</ol>
-<p>And all the rest goes to trash!!!!</p>
-
-<p>Let me refine:</p>
-
-<p>you analyze the whole stylesheet like that (would be good if optimization
-and xpath list could be done simultaneously) and you end up with a list of
-expanded paths mapped to all the templates.</p>
+ is primarily intended as a tooling interface.</item></gloss><p>Even though
the following modules are defined in the <code>org.apache.xalan</code> package,
instead of the transformer package, they are defined in this section as they
are mostly related to runtime transformation.</p><anchor name="stree"/>
+ <s3 title="Stree Module"><p><link>Stree Module [And discussions about
streaming]</link></p><p>The Stree module implements the default <jump
href="http://www.w3.org/TR/xpath#data-model";>Source Tree </jump> for Xalan,
that is to be transformed. It implements read-only <jump
href="http://www.w3.org/TR/DOM-Level-2/";>DOM2</jump> interfaces, and provides
some information needed for fast transforms, such as document order indexes.
It also attempts to allow an incremental transform by launching the transform
on a secondary thread as soon as the SAX2 <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#startDocument()">StartDocument</jump>
event has occurred. When the transform requests a node, and the node is not
present, the getFirstChild and GetNextSibling methods will wait until the child
node has arrived, or an <jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String,%20java.lang.String,%20java.lang.String)">endElement</jump>
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. However, this model would only be possible</p><p>This
kind of incrementality 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></s3><s3 title="Serializer
Module"><p><link>Serializer Module</link></p><p>XML serialization is a term
used for turning a tree or set of events into a stream, and should not be
confused with Java object serialization. The Xalan serializers implement the
<jump
href="http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/ContentHandler.html";>ContentHandler</jump>
to turn parser events coming from the transform, into a stream of XML, HTML,
or plain text. The serializers also implement the <code><jump
href="../apidocs/org/apache/xalan/serializer/Serializer.html">Serializer</jump></code>
which allows the transform process to set XSLT output properties and the
output stream or Writer.</p></s3><s3 title="Extensions
Module"><p><link>Extensions Module</link></p><p>This package contains an
implementation of Xalan Extension Mechanism, which uses the <jump
href="http://oss.software.ibm.com/developerworks/opensource/bsf/";>Bean
Scripting Framework</jump>.
-<p>An entry in the list (i would call this list the transformation stack)
would
-consist of 4 things:</p>
-<ol>
-<li>the relevance context xpath (on which the input nodes will be tested for
-pertinence: do we keep it of not);</li>
-
-<li>the transformation rule to apply to the matching nodes (this can just be
a
-forwarder to another template transformation stack);</li>
-
-<li>a result buffer (in which the nodes that can't be streamed are
temporarily
-stored);</li>
-
-<li>the streaming context xpath (triggers streaming of the buffer to the
-output).</li>
-</ol><anchor name="extensions"/>
-</s3><s3 title="Extensions Module"><p><link>Extensions
Module</link></p><p>This package contains an implementation of Xalan Extension
Mechanism, which uses the <jump
href="http://oss.software.ibm.com/developerworks/opensource/bsf/";>Bean
Scripting Framework</jump>.
-
-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 <jump
href="http://xml.apache.org/xalan/extensions.html";>Xalan-J 1 extension
documentation</jump> 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 <jump
href="http://xml.apache.org/xalan/extensions.html";>Xalan-J 2 extension
documentation</jump> 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>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>
@@ -466,23 +235,18 @@
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 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 <jump
href="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</jump>
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 <jump
href="http://www.w3.org/TR/DOM-Level-2/java-binding.html#org.w3c.dom.traversal.NodeIterator";>NodeIterator</jump>
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 document order so that nodes can be found without necessarily
looking ahead or performing a breadth-first search.</p><anchor
name="xpathdbconn"/><s3 title="XPath Database Connection"><p><link>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 <jump
href="http://www.w3.org/TR/xpath#location-paths";>LocationPath</jump> 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 <jump
href="http://xml.apache.org/xalan/apidocs/org/apache/xalan/xpath/XLocator.html";>XLocator</jump>
interface, in Xalan 2 this interface is no longer used, and has been replaced
by the DOM2 <jump
href="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</jump>
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><anchor name="utils"/>
+ 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 <jump
href="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</jump>
interface, and is meant to allow XPath clients to either override the default
behavior or to replace this behavior.</p><p>The <code><jump
href="../apidocs/org/apache/xpath/axes/LocPathIterator.html">LocPathIterator</jump></code>
and <code><jump
href="../apidocs/org/apache/xpath/axes/UnionPathIterator.html">UnionPathIterator</jump></code>
classes implement the <jump
href="http://www.w3.org/TR/DOM-Level-2/java-binding.html#org.w3c.dom.traversal.NodeIterator";>NodeIterator</jump>
interface, and polymorphically use <code><jump
href="../apidocs/org/apache/xpath/axes/AxesWalker.html">AxesWalker</jump></code>
derived objects to execute each step in the path. The whole trick is to
execute the <code>LocationPath</code> in depth-first document order so that
nodes can be found without necessarily looking ahead or performing a
breadth-first search. Because a document order depth-first search requires
state to be saved for many expressions, the default operations create "Waiter"
clones that have to wait while the main <code>AxesWalkers</code> traverses
child nodes (think carefully about what happens when a "//foo/baz" expression
is executed). Optimization is done by implementing specialized iterators and
<code>AxesWalkers</code> for certain types of operations. The decision as to
what type of iterator or walker will be created is done in the <code><jump
href="../apidocs/org/apache/xpath/axes/WalkerFactory.html">WalkerFactory</jump></code>
class.</p><p>[Frankly, the implementation of the default AxesWalker, with it's
waiters, is the one totally incomprehensible part of Xalan. It gets especially
difficult because you can not look to the node ahead. I would be very
interested if any rocket scientists out there can come up with a better
algorithm.]</p><anchor name="xpathdbconn"/><s3 title="XPath Database
Connection"><p><link>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 <jump
href="http://www.w3.org/TR/xpath#location-paths";>LocationPath</jump> 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 <jump
href="http://xml.apache.org/xalan/apidocs/org/apache/xalan/xpath/XLocator.html";>XLocator</jump>
interface, in Xalan 2 this interface is no longer used, and has been replaced
by the DOM2 <jump
href="http://www.w3.org/TR/DOM-Level-2/traversal.html#Iterator-overview";>NodeIterator</jump>
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><anchor name="utils"/>
<s2 title="Utils Package">
<p><link>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 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
- can be used to perform prefix-to-namespace lookup
- for an XPath.</item></gloss><gloss><label>QName</label><item>Class to
represent a qualified XML
name.</item></gloss><gloss><label>StringToStringTable</label><item>A very
simple lookup table that stores a list of strings for lookup. Used when a
hashtable is too much
overhead.</item></gloss><gloss><label>SystemIDResolver</label><item>Able to
take a SystemID string and try and turn it into a good absolute
URL.</item></gloss><gloss><label>TreeWalker</label><item>Implements a Visitor
design pattern, doing a pre-order walk of the DOM tree, calling a
ContentHandler interface as it goes. Used for DOM-to-SAX
conversion.</item></gloss><gloss><label>Trie</label><item>A digital search trie
for 7-bit ASCII text.</item></gloss><gloss><label>UnImplNode</label><item>To be
subclassed by classes that wish to act as DOM nodes, without having to
implement all the methods. Widely used.</item></gloss></s2><anchor
name="other"/>
+ <p>This package contains general utilities for use by both the xalan and
xpath packages.</p></s2><anchor name="other"/>
<s2 title="Other Packages">
<p><link>Other Packages</link></p>
<gloss><label>client</label><item>Implementation of Xalan Applet
[should we keep this?].
</item></gloss>
- <gloss><label>dtm</label><item>Implementation of the Document
Table Model (DTM) [Should we keep this?].</item></gloss>
- <gloss><label>extensions</label><item>Implementation of Xalan
Extension Mechanism, which uses the Bean Scripting Framework.</item></gloss>
- <gloss><label>lib</label><item>Implementation of Xalan-specific
extensions [I want to add lots more extensions to this
package!].</item></gloss><gloss><label>res</label><item>Contains strings that
require internationalization.</item></gloss></s2><anchor name="coding"/>
+
+
+ <gloss><label>lib</label><item>Implementation of Xalan-specific
extensions.</item></gloss><gloss><label>res</label><item>Contains strings that
require internationalization.</item></gloss></s2><anchor
name="compilation"/><s2 title="Xalan Stylesheet Complilation to
Java"><p><link>Xalan Stylesheet Complilation to Java</link></p><p>We are doing
some work on compiling stylesheet objects to Java. This is a work in progress,
and is not meant for general use yet. For the moment, we are writing out Java
text files, and then compiling them to bytecodes via javac, rather than
directly producing bytecodes. The CompilingStylesheetProcessor derives from
TransformerFactoryImpl to produce these classes, which are then bundled into a
jar file. For the moment the full Xalan jar is required, but we're looking at
ways to only use a subset of Xalan, so that only a minimal jar would be
required.</p><p><img src="compilation.gif"
alt="compilation.gif"/></p></s2><anchor name="optimizations"/><s2 title="Future
Optimizations"><p><link>Future Optimizations</link></p><p>This section
enumerates some optimizations that we're planning to do in future versions of
Xalan.</p><p>Likely near term optimizations (next six months?):</p><ol><li>By
pre-analysis of the stylesheet, prune nodes from the tree that have been
processed and can be predicted that they won't be visited
again.</li><li>Eliminate redundent expressions (xsl:when, variable sets, rooted
patterns, etc.).</li><li>Optimize variable patterns such as <xsl:variable
name="foo"><xsl:variable select="yada"/></xsl:variable> into
<xsl:variable name="foo" select="string(yada)"/>, in order to reduce
result tree fragment creation.</li><li>Reduce size of Stree
nodes.</li><li>Implement our own NamespaceSupport class (the SAX2 one is too
expensive).</li><li>More specialization of itterators and walkers.</li><li>Full
Java compilation support.</li><li>Schema Awareness (if "//foo", the Schema can
tell us where to look, but we need standard interface to
Schemas).</li></ol><p>Likely longer term optimizations (12-18
months?):</p><ol><li>On-the-fly indexing.</li><li>Predict if nodes won't be
processed at all, and so don't build them, achieve full streaming support for a
certain class of stylesheets.</li></ol></s2><anchor name="coding"/>
<s2 title="Coding Conventions">
<p><link>Coding Conventions</link></p>
<p>This section documents the coding conventions used in the Xalan
@@ -504,20 +268,5 @@
protected member variables should not be declared.</li>
</ol>
</s2><anchor name="open"/>
- <s2 title="Open Issues">
- <p><link>Open Issues</link></p>
- <p>This section documents architectural and design issues that I still
- consider to be open or unsolved. (This list is ongoing, and
will change over
- time... it's simply a place for me to note problems that are
ongoing and need
- to be solved.)</p>
- <gloss>
- <label>Space stripping</label>
- <item>In Xalan 1.x, it is clear that space stripping was a major
- performance issue. This needs to be solved in Xalan 2.0 by
stripping the
- space nodes as the document is being parsed. This is a major
problem though for
- DOM trees. This can be perhaps be solved by preprocessing the
DOM tree and
- creating a table of space-stripping parent elements, when the
nodes can't be
- pre-stripped.</item>
- </gloss>
- </s2>
+
</s1>
1.2 +48 -96 xml-xalan/java/xdocs/sources/design/trax.gif
<<Binary file>>
1.2 +33 -33 xml-xalan/java/xdocs/sources/design/xalan1_1x1.gif
<<Binary file>>
1.1 xml-xalan/java/xdocs/sources/design/compilation.gif
<<Binary file>>
1.1 xml-xalan/java/xdocs/sources/design/xalan.gif
<<Binary file>>
1.1 xml-xalan/java/xdocs/sources/design/xslt_abstract.gif
<<Binary file>>
