dleslie 01/06/27 13:24:58
Modified: java/xdocs/sources/design design2_0_0.xml
Log:
Fixed anchors and use of <code> to enable transformation to DITA
along with the "standard" Xalan xml sources.
Revision Changes Path
1.4 +51 -46 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- design2_0_0.xml 2001/01/12 07:46:58 1.3
+++ design2_0_0.xml 2001/06/27 20:24:56 1.4
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
-<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
+<!DOCTYPE s1 SYSTEM "../../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>
+ <p><img src="xmllogo.gif" alt="xmllogo.gif"/></p>
<p>Author: Scott Boag<br/>State: In Progress</p>
<ul>
<li><link anchor="intro">Introduction</link></li>
@@ -23,7 +23,6 @@
<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. 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>
@@ -63,9 +62,10 @@
<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="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="Xalan Requirements">
+ <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>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>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
@@ -76,23 +76,23 @@
<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>
+ <label><jump
href="../apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump></label>
<item>The module that processes the stylesheet, and provides the main
entry point into Xalan.</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/templates/package-summary.html">org.apache.xalan.templates</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/templates/package-summary.html">org.apache.xalan.templates</jump></label>
<item>The module that defines the stylesheet structures, including the
Stylesheet object, template element instructions, and Attribute Value
Templates. </item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/transformer/package-summary.html">org.apache.xalan.transformer</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/transformer/package-summary.html">org.apache.xalan.transformer</jump></label>
<item>The module that applies the source tree to the Templates, and
produces a result tree.</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xpath/package-summary.html">org.apache.xpath</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xpath/package-summary.html">org.apache.xpath</jump></label>
<item>The module that processes both XPath expressions, and XSLT Match
patterns.</item>
</gloss>
@@ -108,45 +108,44 @@
<p>In addition to the above packages, there are the following additional
packages:</p>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/client/package-summary.html">org.apache.xalan.client</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/client/package-summary.html">org.apache.xalan.client</jump></label>
<item>This package has a client applet. I suspect this should be moved
into the samples directory.</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/extensions/package-summary.html">org.apache.xalan.extensions</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/extensions/package-summary.html">org.apache.xalan.extensions</jump></label>
<item>This holds classes belonging to the Xalan extensions mechanism,
which allows Java code and script to be called from within a
stylesheet.</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/lib/package-summary.html">org.apache.xalan.lib</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/lib/package-summary.html">org.apache.xalan.lib</jump></label>
<item>This is the built-in Xalan extensions library, which holds
extensions such as Redirect (which allows a stylesheet to produce
multiple
output files).</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/res/package-summary.html">org.apache.xalan.res</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/res/package-summary.html">org.apache.xalan.res</jump></label>
<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>
+ <label><jump
href="../apidocs/org/apache/xalan/trace/package-summary.html">org.apache.xalan.trace</jump></label>
<item>This package contains classes and interfaces that allow a caller
to
add trace listeners to the transformation, allowing an interface to
XSLT
debuggers and similar tools.</item>
</gloss>
<gloss>
- <label><code><jump
href="../apidocs/org/apache/xalan/xslt/package-summary.html">org.apache.xalan.xslt</jump></code></label>
+ <label><jump
href="../apidocs/org/apache/xalan/xslt/package-summary.html">org.apache.xalan.xslt</jump></label>
<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>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
+ <p>The <jump
href="../apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump>
module implements the
+ <jump
href="../apidocs/javax/xml/transform/TransformerFactory.html">javax.xml.transform.TransformerFactory</jump>
interface, which provides a
factory method for creating a concrete Processor instance, and
provides methods
- for creating a <code><jump
href="../apidocs/javax/xml/transform/Templates.html">javax.xml.transform.Templates</jump></code>
instance, which, in
+ for creating a <jump
href="../apidocs/javax/xml/transform/Templates.html">javax.xml.transform.Templates</jump>
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>
@@ -157,39 +156,38 @@
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><jump
href="../apidocs/org/apache/xalan/processor/XSLTSchema.html">org.apache.xalan.processor.XSLTSchema</jump></code>,
and it is here that the
+ <jump
href="../apidocs/org/apache/xalan/processor/XSLTSchema.html">org.apache.xalan.processor.XSLTSchema</jump>,
and it is here that the
XSLT schema structure is defined. XSLTSchema uses
- <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.
+ <jump
href="../apidocs/org/apache/xalan/processor/XSLTElementDef.html">org.apache.xalan.processor.XSLTElementDef</jump>
to define elements, and
+ <jump
href="../apidocs/org/apache/xalan/processor/XSLTAttributeDef.html">org.apache.xalan.processor.XSLTAttributeDef</jump>
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><jump
href="../apidocs/org/apache/xalan/processor/XSLTElementProcessor.html">org.apache.xalan.processor.XSLTElementProcessor</jump></code>,
and a sometimes a
+ <jump
href="../apidocs/org/apache/xalan/processor/XSLTElementProcessor.html">org.apache.xalan.processor.XSLTElementProcessor</jump>,
and a sometimes a
<code>Class</code> object, with which it can create objects that
derive from
- <code><jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html">org.apache.xalan.templates.ElemTemplateElement</jump></code>.
In addition, the
+ <jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html">org.apache.xalan.templates.ElemTemplateElement</jump>.
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><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>
+ <p>The implementation of the <jump
href="../apidocs/javax/xml/transform/TransformerFactory.html">javax.xml.transform.TransformerFactory</jump>
+ interface is in <jump
href="../apidocs/org/apache/xalan/processor/TransformerFactoryImpl.html">org.apache.xalan.processor.TransformerFactoryImpl</jump>,
+ which creates a <jump
href="../apidocs/org/apache/xalan/processor/StylesheetHandler.html">org.apache.xalan.processor.StylesheetHandler</jump>
instance. This instance acts as the ContentHandler for the parse
events, and is
- handed to the <code><jump
href="../apidocs/org/xml/sax/XMLReader.html">org.xml.sax.XMLReader</jump></code>,
which the StylesheetProcessor
+ handed to the <jump
href="../apidocs/org/xml/sax/XMLReader.html">org.xml.sax.XMLReader</jump>, 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 <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><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
+ <p>The <jump
href="../apidocs/org/apache/xalan/templates/package-summary.html">org.apache.xalan.templates</jump>
module implements the
+ <jump
href="../apidocs/javax/xml/transform/Templates.html">javax.xml.transform.Templates</jump>
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>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
+ <p>The base class of all templates objects that are associated with an XSLT
element is the <jump
href="../apidocs/org/apache/xalan/templates/ElemTemplateElement.html">ElemTemplateElement</jump>
object, which in turn implements <jump
href="../apidocs/org/apache/xml/utils/UnImplNode.html">UnImplNode</jump>. 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 <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> 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 <jump
href="../apidocs/org/apache/xalan/templates/StylesheetRoot.html">StylesheetRoot</jump>,
which implements the
+ <code>Templates</code> interface, is a type of <jump
href="../apidocs/org/apache/xalan/templates/StylesheetComposed.html">StylesheetComposed</jump>,
+ which is a <jump
href="../apidocs/org/apache/xalan/templates/Stylesheet.html">Stylesheet</jump>
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
@@ -210,45 +208,52 @@
</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="../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
+ <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 <jump
href="../apidocs/org/apache/xalan/stree/SourceTreeHandler.html">SourceTreeHandler</jump>),
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 <code><jump
href="../apidocs/org/apache/xalan/transformer/Counter.html">Counter</jump></code>
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 <jump
href="../apidocs/org/apache/xalan/transformer/Counter.html">Counter</jump> 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 <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
+ the node count is based on its position in the cache list. The <jump
href="../apidocs/org/apache/xalan/transformer/CountersTable.html">CountersTable</jump>
class is a table of counters, keyed by <jump
href="../apidocs/org/apache/xalan/templates/ElemNumber.html">ElemNumber</jump>
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 <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>.
+ <s3 title="Stree Module [and discussions about streaming]">
+ <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>
+<anchor name="serializer"/>
+<s3 title="Serializer Module">
+<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 <jump
href="../apidocs/org/apache/xalan/serializer/Serializer.html">Serializer</jump> which
allows the transform process to set XSLT output properties and the output stream or
Writer.</p></s3><anchor name="extensions"/>
+<s3 title="Extensions Module">
+<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 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>
<p>The XPath module first compiles the XPath strings into expression trees, and
then executes these expressions via a call to the XPath execute(...) function. </p>
<p>Major classes are:</p><gloss><label>XPath</label><item>Represents a compiled XPath.
Major function is <code>XObject execute(XPathContext xctxt, Node contextNode,
- PrefixResolver
namespaceContext).</code></item></gloss><gloss><label>XPathAPI</label><item>The
methods in this class are convenience methods into the
+ PrefixResolver
namespaceContext)</code>.</item></gloss><gloss><label>XPathAPI</label><item>The
methods in this class are convenience methods into the
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 <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"/>
+ 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 <jump
href="../apidocs/org/apache/xpath/axes/LocPathIterator.html">LocPathIterator</jump>
and <jump
href="../apidocs/org/apache/xpath/axes/UnionPathIterator.html">UnionPathIterator</jump>
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 <jump
href="../apidocs/org/apache/xpath/axes/AxesWalker.html">AxesWalker</jump> 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
<jump href="../apidocs/org/apache/xpath/axes/WalkerFactory.html">WalkerFactory</jump>
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>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.</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>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"/>
+ <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>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>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
source.</p>
<ol>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
