You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sh...@apache.org on 2014/05/16 18:11:35 UTC
svn commit: r1595253 [16/18] - in /xalan/java/branches/WebSite: ./ xalan-j/
xalan-j/design/ xalan-j/design/resources/ xalan-j/resources/ xalan-j/xsltc/
xalan-j/xsltc/resources/
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_predicates.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_predicates.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_predicates.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_predicates.html Fri May 16 16:11:33 2014
@@ -0,0 +1,562 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: XSLTC Predicate Handling</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">XSLTC Design</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">XSLTC Predicate Handling</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="index.html">Overview</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_compiler.html">Compiler design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_whitespace_design.html">Whitespace</a>
+</li>
+<li>
+<a href="xsl_sort_design.html">xsl:sort</a>
+</li>
+<li>
+<a href="xsl_key_design.html">Keys</a>
+</li>
+<li>
+<a href="xsl_comment_design.html">Comment design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_lang_design.html">lang()</a>
+</li>
+<li>
+<a href="xsl_unparsed_design.html">Unparsed entities</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_if_design.html">If design</a>
+</li>
+<li>
+<a href="xsl_choose_design.html">Choose|When|Otherwise design</a>
+</li>
+<li>
+<a href="xsl_include_design.html">Include|Import design</a>
+</li>
+<li>
+<a href="xsl_variable_design.html">Variable|Param design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_runtime.html">Runtime</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_dom.html">Internal DOM</a>
+</li>
+<li>
+<a href="xsltc_namespace.html">Namespaces</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_trax.html">Translet & TrAX</a>
+</li>
+<li>XPath Predicates<br />
+</li>
+<li>
+<a href="xsltc_iterators.html">Xsltc Iterators</a>
+</li>
+<li>
+<a href="xsltc_native_api.html">Xsltc Native API</a>
+</li>
+<li>
+<a href="xsltc_trax_api.html">Xsltc TrAX API</a>
+</li>
+<li>
+<a href="xsltc_performance.html">Performance Hints</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>XSLTC Predicate Handling</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Definition</h3>
+
+ <p>According to Michael Kay's "XSLT Programmer's Reference" page
+ 736, a predicate is "An expression used to filter which nodes are
+ selected by a particular step in a path expression, or to select a subset of
+ the nodes in a node-set. A Boolean expression selects the nodes for which the
+ predicate is true; a numeric expression selects the node at the position
+ given by the value of the expression, for example '[1]' selects the first
+ node.". Note that a predicate containing a boolean expression can
+ return zero, one or more nodes, while a predicate containing a numeric
+ expression can return only zero or one node.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Examples</h3>
+
+ <p>I'll list a few examples that I can refer back to later on in this
+ document. All examples will use this XML document:</p>
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+ <doc>
+ <foo location="Drumcondra">
+ <bar name="Cat and Cage"/>
+ <bar name="Fagan's"/>
+ <bar name="Gravedigger's"/>
+ <bar name="Ivy House"/>
+ <foo>
+ <foo location="Town">
+ <bar name="Peter's Pub"/>
+ <bar name="Grogan's"/>
+ <bar name="Hogans's"/>
+ <bar name="Brogan's"/>
+ </foo>
+ </doc></pre>
+</blockquote>
+
+ <p>Here are some examples of a predicate with boolean expressions:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="//bar[contains(@name,'ogan')]">
+ <xsl:for-each select="//bar[parent::*/@location = 'Drumcondra']">
+ <xsl:for-each select="//bar[@name = 'Cat and Cage']"></pre>
+</blockquote>
+
+ <p>The first two select more than one node, while the last selects only one.
+ The last expression could select more nodes if the input document was
+ different. Now, here are a few examples of predicates with numeric
+ expressions:</p>
+<blockquote class="source">
+<pre>
+ <xsl:value-of select="//bar[1]">
+ <xsl:value-of select="/doc/foo[2]/bar[1]">
+ <xsl:value-of select="/doc/foo[2]/bar"></pre>
+</blockquote>
+ <p>The last expression will return more than one node, but the step that
+ contains the predicate returns only one (the second <code><foo></code>
+ element).</p>
+
+ <p>The above are the basic types of predicates. These can be grouped to create
+ a predicate pipeline, where the first predicate reduces the node-set that the
+ second predicate filters, and so on. Here are some examples:</p>
+<blockquote class="source">
+<pre>
+ A: <for-each select="//bar[contains(@name,'ogan')][2]">
+ C: <for-each select="//bar[2][contains(@name,'ogan')]">
+ B: <for-each select="//bar[position() > 3][2]"></pre>
+</blockquote>
+
+ <p>It is easier to figure out which nodes these expressions should return if
+ one goes through the steps and predicates one by one. In expression
+ <code>A:</code> we first get all <code><bar></code> elements from the
+ whole document. Then the first predicate selects from that node-set only
+ those elements that have a <code>@name</code> attribute that contains
+ "ogan", and we're left with these elements:</p>
+<blockquote class="source">
+<pre>
+ <bar name="Grogan's">
+ <bar name="Hogans's">
+ <bar name="Brogan's"></pre>
+</blockquote>
+ <p>And finally, the last predicate then selects the second of those
+ elements:</p>
+<blockquote class="source">
+<pre>
+ <bar name="Hogans's"></pre>
+</blockquote>
+
+ <p>Expression <code>B:</code> contains the same predicates as <code>A:</code>,
+ but the resulting node set if completely different. We start off with the same
+ set of <code><bar></code> elements, but we apply the
+ <code>"[2]"</code> predicate first, and end up with this
+ element:</p>
+<blockquote class="source">
+<pre>
+ <bar name="Fagan's"></pre>
+</blockquote>
+
+ <p>Fagan's is the bar where the Irish Taoiseach (prime minister) drinks his
+ pints, but its name does not contain the string "<code>ogan</code>",
+ so the resulting node-set is empty.</p>
+
+ <p>The third expressions also starts off with all <code><bar></code>
+ elements, applies the predicate "<code>[position() > 3]</code>",
+ and reduces the node set to these:</p>
+<blockquote class="source">
+<pre>
+ <bar name="Ivy House">
+ <bar name="Peter's Pub">
+ <bar name="Grogan's">
+ <bar name="Hogans's">
+ <bar name="Brogan's"></pre>
+</blockquote>
+ <p>The last predicate "<code>[2]</code>" is applied to this node-set
+ and set is further reduced to:</p>
+<blockquote class="source">
+<pre>
+ <bar name="Peter's Pub"></pre>
+</blockquote>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Categories</h3>
+
+ <p>From the examples in the last chapter we can try to categorize predicate
+ chains/pipelines to simplify our implementation. We can speed up processing
+ significantly if we can avoid using a data-structure (iterator) to represent
+ the intermediate step between predicates. The goal of setting up these
+ categories is to pinpoint those cases where an intermediate iterator has
+ to be used and when it can be avoided.</p>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Single predicate expressions</h4>
+
+ <p>Expressions containing just a single predicate have no intermediate step
+ and there is no need for any extra iterator. The expression inside the
+ predicate can be applied directly to the original iterator. We call this
+ category <b>SIMPLE_CONTEXT</b>.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Expressions containing only non-position predicates</h4>
+
+ <p>Predicate-order is significant when the predicate-chain contains one or
+ more predicate with an expression similar to
+ "<code>position() > 3</code>" or "<code>2</code>". This
+ is because the <code>position()</code> and <code>last()</code> explicitly
+ refer to the intermediate step between applying each predicate. The
+ expression:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="//bar[contains(@name,'ogan')][parent::*/@location = 'Town']"></pre>
+</blockquote>
+ <p>has two predicates that can be applied in any order and still produce the
+ desired node-set. Such predicates can be merged to:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="//bar[contains(@name,'ogan') & (parent::*/@location = 'Town')]"></pre>
+</blockquote>
+ <p>We call this category NO_CONTEXT.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Expressions containing position predicates</h4>
+
+ <p>A predicate-chain, whose predicates' expressions contain any use of the
+ <code>position()</code> or <code>last()</code> functions require some way
+ of representing the intermediate step in an iterator. The first predicate
+ is applied to the original node-set, and the resulting node-set must then
+ be stored in some other iterator, from which the second predicate can get
+ the current position from the iterator's <code>getPosition()</code> and
+ <code>getLast()</code> methods. We call this category
+ GENERAL_CONTEXT</p>
+
+
+
+ <a name="exception">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Expressions containing one position predicate</h4>
+
+ <p>There is one expection from the GENERAL_CONTEXT category. If the
+ predicate-chain contains only one position-predicate, and that predicate is
+ the very first one, then that predicate can call the iterator that contains
+ the first node-set directly. Just look:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="//bar[2][parent::*/@location = 'Drumcondra']"></pre>
+</blockquote>
+ <p>The <code>[2]</code> predicate can be applied to the original iterator
+ for the <code>//bar</code> step. And so can the
+ <code>[parent::*/@location = 'Drumcondra']</code> predicate as well. This
+ is only the case when the position predicate is first in the predicate
+ chain. These types of predicate chains belong in the
+ NO_CONTEXT category.</p>
+
+
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Design details</h3>
+
+ <p>Predicates are handled quite differently in step expressions and step
+ patterns. Step expressions are not implemented with the various contexts in
+ mind and use a specialised iterator to wrap the code for each predicate.
+ Step patterns are more complicated and CPU (or should I say JVM?)
+ exhaustive. Step patterns containing predicates are analysed to determine
+ context type and compiled accordingly.</p>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Predicates and Step expressions</h4>
+
+ <p>The basic behaviour for a predicate is to compile a <b>filter</b>. This
+ filter is an auxiliary class that implements the
+ <code>org.apache.xalan.xsltc.dom.CurrentNodeListFilter</code> interface. The
+ <code>Step</code> or <code>StepPattern</code> that uses the predicate will
+ create a <code>org.apache.xalan.xsltc.dom.CurrentNodeListFilter</code>. This
+ iterator contains the nodes that pass through the predicate. The compiled
+ filter is used by the iterator to determine which nodes that should be
+ included. The <code>org.apache.xalan.xsltc.dom.CurrentNodeListFilter</code>
+ interface contains only a single method:</p>
+<blockquote class="source">
+<pre>
+ public interface CurrentNodeListFilter {
+ public abstract boolean test(int node, int position, int last, int current,
+ AbstractTranslet translet, NodeIterator iter);
+ }</pre>
+</blockquote>
+
+ <p>The code that is compiled into the <code>test()</code> method is the
+ code for the predicate's expression. The <code>Predicate</code> class
+ compiles the filter class and a <code>test()</code> method skeleton, while
+ some sub-class of the <code>Expression</code> class compiles the actual
+ code that goes into this method.</p>
+
+ <p>The iterator is initialised with a filter that implements this interface:
+ </p>
+<blockquote class="source">
+<pre>
+ public CurrentNodeListIterator(NodeIterator source,
+ CurrentNodeListFilter filter,
+ int currentNode,
+ AbstractTranslet translet) {
+ this(source, !source.isReverse(), filter, currentNode, translet);
+ }</pre>
+</blockquote>
+
+ <p>The iterator will use its source iterator to provide it with the initial
+ node-set. Each node that is returned from this set is passed through the
+ filter before returned by the <code>next()</code> method. Note that the
+ source iterator can also be a current node-list iterator (if two or more
+ predicates are chained together).</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Optimisations in Step expressions</h4>
+
+ <h5>Node-value iterators</h5>
+
+ <p>Some simple predicates that test for node values are handled by the
+ <code>NodeValueIterator</code> class at runtime. These are:</p>
+<blockquote class="source">
+<pre>
+ A: foo[@attr = <value>]
+ B: foo[bar = <value>]
+ C: foo/bar[. = <value>]</pre>
+</blockquote>
+
+ <p>The first case is handled by creating an iterator that represents
+ <code>foo/@attr</code>, then passing this iterator and a test-value to
+ a <code>NodeValueIterator</code>. The <b><value></b> is an
+ expression that is compiled and passed to the iterator as a string. It
+ does <b>not</b> have to be a literal string as the string value is
+ found at runtime. The last two cases are similarly handled by creating an
+ iterator for <code>foo/bar</code> and passing that and the test-value to
+ a <code>NodeValueIterator</code>.</p>
+
+
+
+ <h5>Nth descendant iterators</h5>
+
+ <p>The <code>Step</code> class is also optimised for position-predicates
+ that are applied to descendant iterators:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="//bar[3]"></pre>
+</blockquote>
+
+ <p>Such step/predicate combinations are handled by the internal DOM's
+ inner class <code>NthDescendantIterator</code>.</p>
+
+
+
+ <h5>Nth position iterators</h5>
+
+ <p>Similarly, the <code>Step</code> class is optimised for
+ position-predicates that are applied to basic steps:</p>
+<blockquote class="source">
+<pre>
+ <xsl:for-each select="bar[3]"></pre>
+</blockquote>
+
+ <p>Such step/predicate combinations are handled by the internal DOM's
+ inner class <code>NthPositionIterator</code>.</p>
+
+
+
+ <h5>Node test</h5>
+
+ <p>The predicate class contains a method that tells you if it is a boolean
+ test:</p>
+<blockquote class="source">
+<pre>
+ public boolean isBooleanTest();</pre>
+</blockquote>
+
+ <p>This can be, but it currently is not, used by the <code>Step</code> class
+ to compile in optimised code. Some work to be done here!</p>
+
+
+
+
+
+ <a name="step-patterns">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Predicates and StepPatterns</h4>
+
+ <p>Using predicates in patterns is slow on any XSLT processor, and XSLTC
+ is no exception. This is why the predicate context is carefully analysed
+ by the <code>StepPattern</code> class, so that the compiled code is
+ specialised to handle the specific predicate(s) in use. First we should
+ consider the basic step pattern.</p>
+
+ <h5>Basic pattern handling</h5>
+
+ <p>All patterns are grouped (by the <code>Mode</code> class) according to
+ their <b>
+<i>kernel</i>
+</b>-node type. The kernel node-type is node-type of the
+ <b>last</b> step in a pattern:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="foo/bar/baz"> ... <xsl:template></pre>
+</blockquote>
+
+ <p>In this case the type for elements <code><baz></code> is the
+ kernel type. This step is <b>not</b> compiled as a step pattern. The node
+ type is passed to the <code>Mode</code> class and is used to place the
+ remainder of the pattern code inside the big <code>switch()</code> statement
+ in the translet's <code>applyTemplates()</code> method. The whole pattern
+ is then <b>reduced</b> to:</p>
+<blockquote class="source">
+<pre>
+ match="foo/bar"</pre>
+</blockquote>
+
+ <p>The <code>StepPattern</code> representing the <code><bar></code>
+ element test is compiled under the appropriate <code>case:</code> section
+ of the <code>switch()</code> statement. The code compiled for the step
+ pattern is basically just a call to the DOM's <code>getType()</code>
+ method and a test for the desired node type. There are two special cases
+ for:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="foo/*/baz"> ... <xsl:template>
+ <xsl:template match="foo/*@[2]"> ... <xsl:template></pre>
+</blockquote>
+
+ <p>In the first case we call <code>isElement()</code> and in the second case
+ we call <code>isAttribute()</code>, instead of <code>getType()</code>.</p>
+
+
+
+ <h5>Patterns with predicates</h5>
+
+ <p>The <code>typeCheck()</code> method of the <code>StepPattern</code>
+ invokes a method that analyses the predicates of the step pattern and
+ determines their context. (Note that this method needs to be updated to
+ handle the exception to the GENERAL_CONTEXT metioned in the section
+ <a href="#exception">Expressions containing one position predicate</a> earlier in this document.) The <code>translate()</code> method of the
+ <code>StepPattern</code> class contains a <code>switch()</code> statement
+ that calls methods that are tailored for compiling code for the various
+ predicate contexts.</p>
+
+
+
+
+
+
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_predicates.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_runtime.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_runtime.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_runtime.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_runtime.html Fri May 16 16:11:33 2014
@@ -0,0 +1,677 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: XSLTC runtime environment</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">XSLTC Design</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">XSLTC runtime environment</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="index.html">Overview</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_compiler.html">Compiler design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_whitespace_design.html">Whitespace</a>
+</li>
+<li>
+<a href="xsl_sort_design.html">xsl:sort</a>
+</li>
+<li>
+<a href="xsl_key_design.html">Keys</a>
+</li>
+<li>
+<a href="xsl_comment_design.html">Comment design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_lang_design.html">lang()</a>
+</li>
+<li>
+<a href="xsl_unparsed_design.html">Unparsed entities</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_if_design.html">If design</a>
+</li>
+<li>
+<a href="xsl_choose_design.html">Choose|When|Otherwise design</a>
+</li>
+<li>
+<a href="xsl_include_design.html">Include|Import design</a>
+</li>
+<li>
+<a href="xsl_variable_design.html">Variable|Param design</a>
+</li></ul><hr /><ul>
+<li>Runtime<br />
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_dom.html">Internal DOM</a>
+</li>
+<li>
+<a href="xsltc_namespace.html">Namespaces</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_trax.html">Translet & TrAX</a>
+</li>
+<li>
+<a href="xsltc_predicates.html">XPath Predicates</a>
+</li>
+<li>
+<a href="xsltc_iterators.html">Xsltc Iterators</a>
+</li>
+<li>
+<a href="xsltc_native_api.html">Xsltc Native API</a>
+</li>
+<li>
+<a href="xsltc_trax_api.html">Xsltc TrAX API</a>
+</li>
+<li>
+<a href="xsltc_performance.html">Performance Hints</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>XSLTC runtime environment</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Contents</h3>
+
+ <p>This document describes the design and overall architecture of XSLTC's
+ runtime environment. This does not include the internal DOM and the DOM
+ iterators, which are all covered in separate documents.</p>
+
+ <ul>
+ <li>
+<a href="#overview">Runtime overview</a>
+</li>
+ <li>
+<a href="#translet">The compiled translet</a>
+</li>
+ <li>
+<a href="#types">External/internal type mapping</a>
+</li>
+ <li>
+<a href="#mainloop">Main program loop</a>
+</li>
+ <li>
+<a href="#library">Runtime library</a>
+</li>
+ <li>
+<a href="#output">Output handling</a>
+</li>
+ </ul>
+
+
+
+
+
+ <a name="overview">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Runtime overview</h3>
+
+ <p>This figure shows the main components of XSLTC's runtime environment:</p>
+
+ <p>
+<img src="runtime_design.gif" alt="runtime_design.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 1: Runtime environment overview</i>
+</b>
+</p>
+
+ <p>The various steps these components have to go through to transform a
+ document are:</p>
+
+ <ul>
+ <li>instanciate a parser and hand it the input document</li>
+ <li>build an internal DOM from the parser's SAX events</li>
+ <li>instanciate the translet object</li>
+ <li>pass control to the translet object</li>
+ <li>receive output events from the translet</li>
+ <li>format the output document</li>
+ </ul>
+
+ <p>This process can be initiated either through XSLTC's native API or
+ through the implementation of the JAXP/TrAX API.</p>
+
+ <a name="translet">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>The compiled translet</h3>
+
+ <p>A translet is always a subclass of <code>AbstractTranslet</code>. As well
+ as having access to the public/protected methods in this class, the
+ translet is compiled with these methods:</p>
+<blockquote class="source">
+<pre>
+ public void transform(DOM, NodeIterator, TransletOutputHandler);</pre>
+</blockquote>
+
+ <p>This method is passed a <code>DOMImpl</code> object. Depending on whether
+ the stylesheet had any calls to the <code>document()</code> function this
+ method will either generate a <code>DOMAdapter</code> object (when only one
+ XML document is used as input) or a <code>MultiDOM</code> object (when there
+ are more than one XML input documents). This DOM object is passed on to
+ the <code>topLevel()</code> method.</p>
+
+ <p>When the <code>topLevel()</code> method returns, we initiate the output
+ document by calling <code>startDocument()</code> on the supplied output
+ handler object. We then call <code>applyTemplates()</code> to get the actual
+ output contents, before we close the output document by calling
+ <code>endDocument()</code> on the output handler.</p>
+<blockquote class="source">
+<pre>
+ public void topLevel(DOM, NodeIterator, TransletOutputHandler);</pre>
+</blockquote>
+
+ <p>This method handles all of these top-level elements:</p>
+ <ul>
+ <li>
+<code><xsl:output></code>
+</li>
+ <li>
+<code><xsl:decimal-format></code>
+</li>
+ <li>
+<code><xsl:key></code>
+</li>
+ <li>
+<code><xsl:param></code> (for global parameters)</li>
+ <li>
+<code><xsl:variable></code> (for global variables)</li>
+ </ul>
+<blockquote class="source">
+<pre>
+ public void applyTemplates(DOM, NodeIterator, TransletOutputHandler);</pre>
+</blockquote>
+
+ <p>This is the method that produces the actual output. Its central element
+ is a big <code>switch()</code> statement that is used to trigger the code
+ that represent the available templates for the various node in the input
+ document. See the chapter on the
+ <a href="#mainloop">main program loop</a> for details on this method.
+ </p>
+<blockquote class="source">
+<pre>
+ public void <init>();</pre>
+</blockquote>
+
+ <a name="namesarray">â</a>
+ <p>The translet's constructor initializes a table of all the elements we
+ want to search for in the XML input document. This table is called the
+ <code>namesArray</code>, and maps each element name to an unique integer
+ value, know as the elements "translet-type".
+ The DOMAdapter, which acts as a mediator between the DOM and the translet,
+ will map these element identifier to the element identifiers used internally
+ in the DOM. See the section on <a href="#types">extern/internal type
+ mapping</a> and the internal DOM design document for details on this.</p>
+
+ <p>The constructor also initializes any <code>DecimalFormatSymbol</code>
+ objects that are used to format numbers before passing them to the
+ output post-processor. The output processor uses thes symbols to format
+ decimal numbers in the output.</p>
+<blockquote class="source">
+<pre>
+ public boolean stripSpace(int nodeType);</pre>
+</blockquote>
+
+ <p>This method is only present if any <code><xsl:strip-space></code>
+ or <code><xsl:preserve-space></code> elements are present in the
+ stylesheet. If that is the case, the translet implements the
+ <code>StripWhitespaceFilter</code> interface by containing this method.</p>
+
+
+
+
+
+ <a name="types">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>External/internal type mapping</h3>
+
+ <p>This is the very core of XSL transformations:
+ <b>Read carefully!!!</b>
+</p>
+
+ <a name="external-types">â</a>
+ <p>Every node in the input XML document(s) is assigned a type by the DOM
+ builder class. This type is a unique integer value which represents the
+ element, so that for instance all <code><bob></code> elements in the
+ input document will be given type <code>7</code> and can be referred to by
+ that integer. These types can be used for lookups in the
+ <a href="#namesarray">namesArray</a> table to get the actual
+ element name (in this case "bob"). The type identifiers used in the DOM are
+ referred to as <b>external types</b> or <b>DOM types</b>, as they are
+ types known only outside of the translet.</p>
+
+ <a name="internal-types">â</a>
+ <p>Similarly the translet assignes types to all element and attribute names
+ that are referenced in the stylesheet. This type assignment is done at
+ compile-time, while the DOM builder assigns the external types at runtime.
+ The element type identifiers used by the translet are referred to as
+ <b>internal types</b> or <b>translet types</b>.</p>
+
+ <p>It is not very probable that there will be a one-to-one mapping between
+ internal and external types. There will most often be elements in the DOM
+ (ie. the input document) that are not mentioned in the stylesheet, and
+ there could be elements in the stylesheet that do not match any elements
+ in the DOM. Here is an example:</p>
+
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+ <xsl:stylesheet version="1.0" xmlns:xsl="blahblahblah">
+
+ <xsl:template match="/">
+ <xsl:for-each select="//B">
+ <xsl:apply-templates select="." />
+ </xsl:for-each>
+ <xsl:for-each select="C">
+ <xsl:apply-templates select="." />
+ </xsl:for-each>
+ <xsl:for-each select="A/B">
+ <xsl:apply-templates select="." />
+ </xsl:for-each>
+ </xsl:template>
+
+ </xsl:stylesheet>
+</pre>
+</blockquote>
+
+ <p>In this stylesheet we are looking for elements <code><B></code>,
+ <code><C></code> and <code><A></code>. For this example we can
+ assume that these element types will be assigned the values 0, 1 and 2.
+ Now, lets say we are transforming this XML document:</p>
+
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+
+ <A>
+ The crocodile cried:
+ <F>foo</F>
+ <B>bar</B>
+ <B>baz</B>
+ </A>
+</pre>
+</blockquote>
+
+ <p>This XML document has the elements <code><A></code>,
+ <code><B></code> and <code><F></code>, which we assume are
+ assigned the types 7, 8 and 9 respectively (the numbers below that are
+ assigned for specific element types, such as the root node, text nodes,etc).
+ This causes a mismatch between the type used for <code><B></code> in
+ the translet and the type used for <code><B></code> in the DOM. The
+ DOMAdapter class (which mediates between the DOM and the translet) has been
+ given two tables for convertint between the two types; <code>mapping</code>
+ for mapping from internal to external types, and <code>reverseMapping</code>
+ for the other way around.</p>
+
+ <p>The translet contains a <code>String[]</code> array called
+ <code>namesArray</code>. This array contains all the element and attribute
+ names that were referenced in the stylesheet. In our example, this array
+ would contain these string (in this specific order): "B",
+ "C" and "A". This array is passed as one of the
+ parameters to the DOM adapter constructor (the other parameter is the DOM
+ itself). The DOM adapter passes this table on to the DOM. The DOM generates
+ a hashtable that maps its known element names to the types the translet
+ knows. The DOM does this by going through the <code>namesArray</code> from
+ the translet sequentially, looks up each name in the hashtable, and is then
+ able to map the internal type to an external type. The result is then passed
+ back to the DOM adapter.</p>
+
+ <p>External types that are not interesting for the translet (such as the
+ type for <code><F></code> elements in the example above) are mapped
+ to a generic <code>"ELEMENT"</code> type (integer value 3), and are more or
+ less ignored by the translet. Uninterresting attributes are similarly
+ mapped to internal type <code>"ATTRIBUTE"</code> (integer value 4).</p>
+
+ <p>It is important that we separate the DOM from the translet. In several
+ cases we want the DOM as a structure completely independent from the
+ translet - even though the DOM is a structure internal to XSLTC. One such
+ case is when transformations are offered by a servlet as a web service.
+ Any DOM that is built should potentially be stored in a cache and made
+ available for simultaneous access by several translet/servlet couples.</p>
+
+ <p>
+<img src="runtime_type_mapping.gif" alt="runtime_type_mapping.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 2: Two translets accessing a single dom using different type mappings</i>
+</b>
+</p>
+
+
+
+
+
+ <a name="mainloop">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Main program loop</h3>
+
+ <p>The main body of the translet is the <code>applyTemplates()</code>
+ method. This method goes through these steps:</p>
+
+ <ul>
+ <li>
+ Get the next node from the node iterator
+ </li>
+ <li>
+ Get the internal type of this node. The DOMAdapter object holds the
+ internal/external type mapping table, and it will supply the translet
+ with the internal type of the current node.
+ </li>
+ <li>
+ Execute a switch statement on the internal node type. There will be
+ one "case" label for each recognised node type - this includes the
+ first 7 internal node types.
+ </li>
+ </ul>
+
+ <p>The root node will have internal type 0 and will cause any initial
+ literal elements to be output. Text nodes will have internal node type 1
+ and will simply be dumped to the output handler. Unrecognized elements
+ will have internal node type 3 and will be given the default treatment
+ (a new iterator is created for the node's children, and this iterator
+ is passed with a recursive call to <code>applyTemplates()</code>).
+ Unrecognised attribute nodes (type 4) will be handled like text nodes.
+ This makes up the default (built in) templates of any stylesheet. Then,
+ we add one <code>"case"</code>for each node type that is matched by any
+ pattern in the stylesheet. The <code>switch()</code> statement in
+ <code>applyTemplates</code> will thereby look something like this:</p>
+
+<blockquote class="source">
+<pre>
+ public void applyTemplates(DOM dom, NodeIterator,
+ TransletOutputHandler handler) {
+
+ // get nodes from iterator
+ while ((node = iterator.next()) != END) {
+ // get internal node type
+ switch(DOM.getType(node)) {
+
+ case 0: // root
+ outputPreable(handler);
+ break;
+ case 1: // text
+ DOM.characters(node,handler);
+ break;
+ case 3: // unrecognised element
+ NodeIterator newIterator = DOM.getChildren(node);
+ applyTemplates(DOM,newIterator,handler);
+ break;
+ case 4: // unrecognised attribute
+ DOM.characters(node,handler);
+ break;
+ case 7: // elements of type <B>
+ someCompiledCode();
+ break;
+ case 8: // elements of type <C>
+ otherCompiledCode();
+ break;
+ default:
+ break;
+ }
+ }
+ }
+</pre>
+</blockquote>
+
+ <p>Each recognised element will have its own piece of compiled code.</p>
+
+ <p>Note that each "case" will not lead directly to a single template.
+ There may be several templates that match node type 7
+ (say <code><B></code>). In the sample stylesheet in the previous
+ chapter we have to templates that would match a node <code><B></code>.
+ We have one <code>match="//B"</code> (match just any <code><B></code>
+ element) and one <code>match="A/B"</code> (match a <code><B></code>
+ element that is a child of a <code><A></code> element). In this case
+ we would have to compile code that first gets the type of the current node's
+ parent, and then compared this type with the type for
+ <code><A></code>. If there was no match we will have executed the
+ first <code><xsl:for-each></code> element, but if there was a match
+ we will have executed the last one. Consequentally, the compiler will
+ generate the following code (well, it will look like this anyway):</p>
+
+<blockquote class="source">
+<pre>
+ switch(DOM.getType(node)) {
+ :
+ :
+ case 7: // elements of type <B>
+ int parent = DOM.getParent(node);
+ if (DOM.getType(parent) == 9) // type 9 = elements <A>
+ someCompiledCode();
+ else
+ evenOtherCompiledCode();
+ break;
+ :
+ :
+ }
+</pre>
+</blockquote>
+
+ <p>We could do the same for namespaces, that is, assign a numeric value
+ to every namespace that is references in the stylesheet, and use an
+ <code>"if"</code> statement for each namespace that needs to be checked for
+ each type. Lets say we had a stylesheet like this:</p>
+
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+ <xsl:stylesheet version="1.0" xmlns:xsl="blahblahblah">
+
+ <xsl:template match="/"
+ xmlns:foo="http://foo.com/spec"
+ xmlns:bar="http://bar.net/ref">
+ <xsl:for-each select="foo:A">
+ <xsl:apply-templates select="." />
+ </xsl:for-each>
+ <xsl:for-each select="bar:A">
+ <xsl:apply-templates select="." />
+ </xsl:for-each>
+ </xsl:template>
+
+ </xsl:stylesheet>
+</pre>
+</blockquote>
+
+ <p>And a stylesheet like this:</p>
+
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+
+ <DOC xmlns:foo="http://foo.com/spec"
+ xmlns:bar="http://bar.net/ref">
+ <foo:A>In foo namespace</foo:A>
+ <bar:A>In bar namespace</bar:A>
+ </DOC>
+</pre>
+</blockquote>
+
+ <p>We could still keep the same type for all <code><A></code> elements
+ regardless of what namespace they are in, and use the same <code>"if"</code>
+ structure within the <code>switch()</code> statement above. The other option
+ is to assign different types to <code><foo:A></code> and
+ <code><bar:A></code> elements. The latter is the option we chose, and
+ it is described in detail in the namespace design document.</p>
+
+
+
+
+
+ <a name="library">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Runtime library</h3>
+
+ <p>The runtime library offers basic functionality to the translet at
+ runtime. It is analoguous to UNIX's <code>libc</code>. The whole runtime
+ library is contained in a single class file:</p>
+
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.runtime.BasisLibrary
+</pre>
+</blockquote>
+
+ <p>This class contains a large set of static methods that are invoked by
+ the translet. These methods are largely independent from eachother, and
+ they implement the following:</p>
+
+ <ul>
+ <li>simple XPath functions that do not require a lot of code
+ compiled into the translet class</li>
+ <li>functions for formatting decimal numbers to strings</li>
+ <li>functions for comparing nodes, node-sets and strings - used by
+ equality expressions, predicates and other</li>
+ <li>functions for generating localised error messages</li>
+ </ul>
+
+ <p>The runtime library is a central part of XSLTC. But, as metioned earlier,
+ the functions within the library are rarely related, so there is no real
+ overall design/architecture. The only common attribute of many of the
+ methods in the library is that all static methods that implement an XPath
+ function and with a capital <code>F</code>.</p>
+
+
+
+
+
+ <a name="output">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Output handler</h3>
+
+ <p>The translet passes its output to an output post-processor before the
+ final result is handed to the client application over a standard SAX
+ interface. The interface between the translet and the output handler is
+ very similar to a SAX interface, but it has a few non-standard additions.
+ This interface is described in this file:</p>
+
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.TransletOutputHandler
+</pre>
+</blockquote>
+
+ <p>This interface is implemented by:</p>
+
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.runtime.TextOutput
+</pre>
+</blockquote>
+
+ <p>This class, despite its name, handles all types of output (XML, HTML and
+ TEXT). Our initial idea was to have a base class implementing the
+ <code>TransletOutputHandler</code> interface, and then have one subclass
+ for each of the output types. This proved very difficult, as the output
+ type is not always known until after the transformation has started and
+ some elements have been output. But, this is an area where a change like
+ that has the potential to increase performance significantly. Output
+ handling has a lot to do with analyzing string contents, and by narrowing
+ down the number of string comparisons and string updates one can acomplish
+ a lot.</p>
+
+ <p>The main tasks of the output handler are:</p>
+
+ <ul>
+ <li>determine the output type based on the output generated by the
+ translet (not always necessary)</li>
+ <li>generate SAX events for the client application</li>
+ <li>insert the necessary namespace declarations in the output</li>
+ <li>escape special characters in the output</li>
+ <li>insert <DOCTYPE> and <META> elements in HTML output</li>
+ </ul>
+
+ <p>There is a very clear link between the output handler and the
+ <code>org.apache.xalan.xsltc.compiler.Output</code> class that handles
+ the <code><xsl:output></code> element. The <code>Output</code> class
+ stores many output settings and parameters in the translet class file and
+ the translet passes these on to the output handler.</p>
+
+
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_runtime.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax.html Fri May 16 16:11:33 2014
@@ -0,0 +1,837 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: The Translet API and TrAX</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">XSLTC Design</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">The Translet API and TrAX</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="index.html">Overview</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_compiler.html">Compiler design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_whitespace_design.html">Whitespace</a>
+</li>
+<li>
+<a href="xsl_sort_design.html">xsl:sort</a>
+</li>
+<li>
+<a href="xsl_key_design.html">Keys</a>
+</li>
+<li>
+<a href="xsl_comment_design.html">Comment design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_lang_design.html">lang()</a>
+</li>
+<li>
+<a href="xsl_unparsed_design.html">Unparsed entities</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_if_design.html">If design</a>
+</li>
+<li>
+<a href="xsl_choose_design.html">Choose|When|Otherwise design</a>
+</li>
+<li>
+<a href="xsl_include_design.html">Include|Import design</a>
+</li>
+<li>
+<a href="xsl_variable_design.html">Variable|Param design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_runtime.html">Runtime</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_dom.html">Internal DOM</a>
+</li>
+<li>
+<a href="xsltc_namespace.html">Namespaces</a>
+</li></ul><hr /><ul>
+<li>Translet & TrAX<br />
+</li>
+<li>
+<a href="xsltc_predicates.html">XPath Predicates</a>
+</li>
+<li>
+<a href="xsltc_iterators.html">Xsltc Iterators</a>
+</li>
+<li>
+<a href="xsltc_native_api.html">Xsltc Native API</a>
+</li>
+<li>
+<a href="xsltc_trax_api.html">Xsltc TrAX API</a>
+</li>
+<li>
+<a href="xsltc_performance.html">Performance Hints</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>The Translet API and TrAX</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Contents</h3>
+
+ <p>Note: This document describes the design of XSLTC's TrAX implementation.
+ The XSLTC <a href="xsltc_trax_api.html">TrAX API user documentation</a>
+ is kept in a separate document.</p>
+
+ <p>The structure of this document is, and should be kept, as follows:</p>
+
+ <ul>
+ <li>A brief introduction to TrAX/JAXP</li>
+ <li>Overall design of the XSLTC TrAX implementation</li>
+ <li>Detailed design of various TrAX components</li>
+ </ul>
+
+ <ul>
+ <li>
+<a href="#abstract">Abstract</a>
+</li>
+ <li>
+<a href="#trax">TrAX basics</a>
+</li>
+ <li>
+<a href="#config">TrAX configuration</a>
+</li>
+ <li>
+<a href="#design">XSLTC TrAX architecture</a>
+</li>
+ <li>
+<a href="#detailed_design">XSLTC TrAX detailed design</a>
+</li>
+ <ul>
+ <li>
+<a href="#factory_design">TransformerFactory design</a>
+</li>
+ <li>
+<a href="#templates_design">Templates design</a>
+</li>
+ <li>
+<a href="#transformer_design">Transformer design</a>
+</li>
+ <li>
+<a href="#config_design">TrAX configuration design</a>
+</li>
+ </ul>
+ </ul>
+
+
+
+
+ <a name="abstract">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Abstract</h3>
+
+ <p>JAXP is the Java extension API for XML parsing. TrAX is an API for XML
+ transformations and is included in the later versions of JAXP. JAXP includes
+ two packages, one for XML parsing and one for XML transformations (TrAX):</p>
+<blockquote class="source">
+<pre>
+ javax.xml.parsers
+ javax.xml.transform</pre>
+</blockquote>
+
+ <p>XSLTC is an XSLT processing engine and fulfills the role as an XML
+ transformation engine behind the TrAX portion of the JAXP API. XSLTC is a
+ provider for the TrAX API and a client of the JAXP parser API.</p>
+
+ <p>This document describes the design used for integrating XSLTC translets
+ with the JAXP TrAX API. The heart of the design is a wrapper class around the
+ XSLTC compiler that extends the JAXP <code>SAXTransformerFactory</code>
+ interface. This factory delivers translet class definitions (Java bytecodes)
+ wrapped inside TrAX <code>Templates</code> objects. These
+ <code>Templates</code> objects can be used to instanciate
+ <code>Transformer</code> objects that transform XML documents into markup or
+ plain text. Alternatively a <code>Transformer</code> object can be created
+ directly by the <code>TransformerFactory</code>, but this approach is not
+ recommended with XSLTC. The reason for this will be explained later in this
+ document.</p>
+
+
+
+
+
+ <a name="trax">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>TrAX basics</h3>
+
+ <p>The Java API for XML Processing (JAXP) includes an XSLT framework based
+ on the Transformation API for XML (TrAX). A JAXP transformation application
+ can use the TrAX framework in two ways. The simplest way is:</p>
+
+ <ul>
+ <li>create an instance of the TransformerFactory class</li>
+ <li>from the factory instance and a given XSLT stylesheet, create a new
+ Transformer object</li>
+ <li>call the Transformer object's transform() method, specifying the XML
+ input and a Result object.</li>
+ </ul>
+<blockquote class="source">
+<pre>
+ import javax.xml.transform.*;
+
+ public class Compile {
+
+ public void run(Source xsl) {
+ ....
+ TransformerFactory factory = TransformerFactory.newInstance();
+ Transformer transformer = factory.newTransformer(xsl);
+ ....
+ }
+ }</pre>
+</blockquote>
+
+ <p>This suits most conventional XSLT processors that transform XML documents
+ in one go. XSLTC needs one extra step to compile the XSL stylesheet into a
+ Java class (a "translet"). Fortunately TrAX has another approach
+ that suits XSLTC two-step transformation model:</p>
+
+ <ul>
+ <li>create an instance of the TransformerFactory class</li>
+ <li>from the factory instance and a given XSLTC, stylesheet, create a new
+ Templates object (this step will compile the stylesheet and put the
+ bytecodes for translet class(es) into the Templates object)</li>
+ <li>from the Template object create a Transformer object (this will
+ instanciate a new translet object).</li>
+ <li>call the Transformer object's transform() method, specifying the XML
+ input and a Result object.</li>
+ </ul>
+<blockquote class="source">
+<pre>
+ import javax.xml.transform.*;
+
+ public class Compile {
+
+ public void run(Source xsl) {
+ ....
+ TransformerFactory factory = TransformerFactory.newInstance();
+ Templates templates = factory.newTemplates(xsl);
+ Transformer transformer = templates.newTransformer();
+ ....
+ }
+ }</pre>
+</blockquote>
+
+ <p>Note that the first two steps need be performed only once for each
+ stylesheet. Once the stylesheet is compiled into a translet and wrapped in a
+ <code>Templates</code> object, the <code>Templates</code> object can be used
+ over and over again to create Transformer object (instances of the translet).
+ The <code>Templates</code> instances can even be serialized and stored on
+ stable storage (ie. in a memory or disk cache) for later use.</p>
+
+ <p>The code below illustrates a simple JAXP transformation application that
+ creates the <code>Transformer</code> directly. Remember that this is not the
+ ideal approach with XSLTC, as the stylesheet is compiled for each
+ transformation.</p>
+<blockquote class="source">
+<pre>
+ import javax.xml.transform.stream.StreamSource;
+ import javax.xml.transform.stream.StreamResult;
+ import javax.xml.transform.Transformer;
+ import javax.xml.transform.TransformerFactory;
+
+ public class Proto {
+
+ public void run(String xmlfile, String xslfile) {
+ Transformer transformer;
+ TransformerFactory factory = TransformerFactory.newInstance();
+
+ try {
+ StreamSource stylesheet = new StreamSource(xslfile);
+ transformer = factory.newTransformer(stylesheet);
+ transformer.transform(new StreamSource(xmlfile),
+ new StreamResult(System.out));
+ }
+ catch (Exception e) {
+ // handle errors...
+ }
+ :
+ :
+ }</pre>
+</blockquote>
+
+ <p>This approach seems simple is probably used in many applications. But, the
+ use of <code>Templates</code> objects is useful when multiple instances of
+ the same <code>Transformer</code> are needed. <code>Transformer</code>
+ objects are not thread safe, and if a server wants to handle several clients
+ requests it would be best off to create one global <code>Templates</code>
+ object, and then from this create a <code>Transformer</code> object for each
+ thread handling the requests. This approach is also by far the best for
+ XSLTC, as the <code>Templates</code> object will hold the class definitions
+ that make up the translet and its auxiliary classes. (Note that the bytecodes
+ and not the actuall class definitions are stored when serializing a
+ <code>Templates</code> object to disk. This is because of class loader
+ security restrictions.) To accomodate this second approach to TrAX
+ transformations, the above class would be modified as follows:</p>
+<blockquote class="source">
+<pre>
+ try {
+ StreamSource stylesheet = new StreamSource(xslfile);
+ Templates templates = factory.newTemplates(stylesheet);
+ transformer = templates.newTransformer();
+ transformer.transform(new StreamSource(inputFilename),
+ new StreamResult(System.out));
+ }
+ catch (Exception e) {
+ // handle errors...
+ }</pre>
+</blockquote>
+
+
+
+
+
+ <a name="config">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>TrAX configuration</h3>
+
+ <p>JAXP's <code>TransformerFactory</code> is configurable similar to the
+ other Java extensions. The API supports configuring thefactory by:</p>
+
+ <ul>
+ <li>passing vendor-specific attributes from the application, through the
+ TrAX interface, to the underlying XSL processor</li>
+ <li>registering an ErrorListener that will be used to pass error and
+ warning messages from the XSL processor to the application</li>
+ <li>registering an URIResolver that the application can use to load XSL
+ and XML documents on behalf of the XSL processor (the XSL processor will
+ use this to support the xsl:include and xsl:import elements and the
+ document() functions.</li>
+ </ul>
+
+ <p>The JAXP TransformerFactory can be queried at runtime to discover what
+ features it supports. For example, an application might want to know if a
+ particular factory implementation supports the use of SAX events as a source,
+ or whether it can write out transformation results as a DOM. The factory API
+ queries with the getFeature() method. In the above code, we could add the
+ following code before the try-catch block:</p>
+<blockquote class="source">
+<pre>
+ if (!factory.getFeature(StreamSource.FEATURE) || !factory.getFeature(StreamResult.FEATURE)) {
+ System.err.println("Stream Source/Result not supported by TransformerFactory\nExiting....");
+ System.exit(1);
+ }</pre>
+</blockquote>
+
+ <p>Other elements in the TrAX API are configurable. A Transformer object can
+ be passed settings that override the default output settings and the settings
+ defined in the stylesheet for indentation, output document type, etc.</p>
+
+
+
+
+
+ <a name="design">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>XSLTC TrAX architecture</h3>
+
+ <p>XSLTC's architecture fits nicely in behind the TrAX interface. XSLTC's
+ compiler is put behind the <code>TransformerFactory</code> interface, the
+ translet class definition (either as a set of in-memory
+ <code>Class</code> objects or as a two-dimmensional array of bytecodes on
+ disk) is encapsulated in the <code>Templates</code> implementation and the
+ instanciated translet object is wrapped inside the <code>Transformer</code>
+ implementation. Figure 1 (below) shows this two-layered TrAX architecture:
+ </p>
+
+ <p>
+<img src="trax_translet_wrapping.gif" alt="TransletWrapping" />
+</p>
+ <p>
+<b>
+<i>Figure 1: Translet class definitions are wrapped inside Templates objects</i>
+</b>
+</p>
+
+ <p>The <code>TransformerFactory</code> implementation also implements the
+ <code>SAXTransformerFactory</code> and <code>ErrorListener</code>
+ interfaces from the TrAX API.</p>
+
+ <p>The TrAX implementation has intentionally been kept completely separate
+ from the XSLTC native code. This prevents users of XSLTC's native API from
+ having to include the TrAX code in an application. All the code that makes
+ up our TrAX implementation resides in this package:</p>
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.trax</pre>
+</blockquote>
+
+ <p>Message to all XSLTC developers: Keep it this way! Do not mix TrAX
+ and Native code!</p>
+
+
+
+
+
+ <a name="detailed_design">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>TrAX implementation details</h3>
+
+ <p>The main components of our TrAX implementation are:</p>
+
+ <ul>
+ <li>
+<a href="#transformer_factory">the TransformerFactory class</a>
+</li>
+ <li>
+<a href="#templates">the Templates class</a>
+</li>
+ <li>
+<a href="#transformer">the Transformer class</a>
+</li>
+ <li>
+<a href="#transformer">output properties handling</a>
+</li>
+ </ul>
+
+ <a name="factory_design">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>TransformerFactory implementation</h4>
+
+ <p>The methods that make up the basic <code>TransformerFactory</code>
+ iterface are: </p>
+<blockquote class="source">
+<pre>
+ public Templates newTemplates(Source source);
+ public Transformer newTransformer();
+ public ErrorListener getErrorListener();
+ public void setErrorListener(ErrorListener listener);
+ public Object getAttribute(String name);
+ public void setAttribute(String name, Object value);
+ public boolean getFeature(String name);
+ public URIResolver getURIResolver();
+ public void setURIResolver(URIResolver resolver);
+ public Source getAssociatedStylesheet(Source src, String media, String title, String charset);</pre>
+</blockquote>
+
+ <p>And for the <code>SAXTransformerFactory</code> interface:</p>
+<blockquote class="source">
+<pre>
+ public TemplatesHandler newTemplatesHandler();
+ public TransformerHandler newTransformerHandler();
+ public TransformerHandler newTransformerHandler(Source src);
+ public TransformerHandler newTransformerHandler(Templates templates);
+ public XMLFilter newXMLFilter(Source src);
+ public XMLFilter newXMLFilter(Templates templates);</pre>
+</blockquote>
+
+ <p>And for the <code>ErrorListener</code> interface:</p>
+<blockquote class="source">
+<pre>
+ public void error(TransformerException exception);
+ public void fatalError(TransformerException exception);
+ public void warning(TransformerException exception);</pre>
+</blockquote>
+
+ <h5>TransformerFactory basics</h5>
+ <p>The very core of XSLTC TrAX support for XSLTC is the implementation of
+ the basic <code>TransformerFactory</code> interface. This factory class is
+ more or less a wrapper around the the XSLTC compiler and creates
+ <code>Templates</code> objects in which compiled translet classes can
+ reside. These <code>Templates</code> objects can then be used to create
+ <code>Transformer</code> objects. In cases where the
+ <code>Transformer</code> is created directly by the factory we will use
+ the <code>Templates</code> class internally. In that way the transformation
+ will appear to be done in one step from the users point of view, while we
+ in reality use to steps. As described earler, this is not the best approach
+ when using XSLTC, as it causes the stylesheet to be compiled for each and
+ every transformation.</p>
+
+
+ <h5>TransformerFactory attribute settings</h5>
+ <p>The <code>getAttribute()</code> and <code>setAttribute()</code> methods
+ only recognise two attributes: <code>translet-name</code> and
+ <code>debug</code>. The latter is obvious - it forces XSLTC to output debug
+ information (dumps the stack in the very unlikely case of a failure). The
+ <code>translet-name</code> attribute can be used to set the default class
+ name for any nameless translet classes that the factory creates. A nameless
+ translet will, for instance, be created when the factory compiles a translet
+ for the identity transformation. There is a default name,
+ <code>GregorSamsa</code>, for nameless translets, so there is no absolute
+ need to set this attribute. (Gregor Samsa is the main character from Kafka's
+ "Metamorphosis" - transformations, metamorphosis - I am sure you
+ see the connection.)</p>
+
+
+ <h5>TransformerFactory stylesheet handling</h5>
+ <p>The compiler is can be passed a stylesheet through various methods in
+ the <code>TransformerFactory</code> interface. A stylesheet is passed in as
+ a <code>Source</code> object that containin either a DOM, a SAX parser or
+ a stream. The <code>getInputSource()</code> method handles all inputs and
+ converts them, if necessary, to SAX. The TrAX implementation contains an
+ adapter that will generate SAX events from a DOM, and this adapter is used
+ for DOM input. If the <code>Source</code> object contains a SAX parser, this
+ parser is just passed directly to the compiler. A SAX parse is instanciated
+ (using JAXP) if the <code>Source</code> object contains a stream.</p>
+
+
+ <h5>TransformerFactory URI resolver</h5>
+ <p>A TransformerFactory needs a <code>URIResolver</code> to locate documents
+ that are referenced in <code><xsl:import></code> and
+ <code><xsl:include></code> elements. XSLTC has an internal interface
+ that shares the same purpose. This internal interface is implemented by the
+ <code>TransformerFactory</code>:</p>
+<blockquote class="source">
+<pre>
+ public InputSource loadSource(String href, String context, XSLTC xsltc);</pre>
+</blockquote>
+ <p>This method will simply use any defined <code>URIResolver</code> and
+ proxy the call on to the URI resolver's <code>resolve()</code> method. This
+ method returns a <code>Source</code> object, which is converted to SAX
+ events and passed back to the compiler.</p>
+
+
+
+
+ <a name="template_design">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Templates design</h4>
+
+ <h5>Templates creation</h5>
+ <p>The <code>TransformerFactory</code> implementation invokes the XSLTC
+ compiler to generate the translet class and auxiliary classes. These classes
+ are stored inside our <code>Templates</code> implementation in a manner
+ which allows the <code>Templates</code> object to be serialized. By making
+ it possible to store <code>Templates</code> on stable storage we allow the
+ TrAX user to store/cache translet class(es), thus making room for XSLTC's
+ one-compilation-multiple-transformations approach. This was done by giving
+ the <code>Templates</code> implementation an array of byte-arrays that
+ contain the bytecodes for the translet class and its auxiliary classes. When
+ the user first requests a <code>Transformer</code> instance from the
+ <code>Templates</code> object for the first time we create one or more
+ <code>Class</code> objects from these byte arrays. Note that this is done
+ only once as long as the <code>Template</code> object resides in memory. The
+ <code>Templates</code> object then invokes the JVM's class loader with the
+ class definition(s) to instanciate the translet class(es). The translet
+ objects are then wraped inside a <code>Transformer</code> object, which is
+ returned to the client code:</p>
+<blockquote class="source">
+<pre>
+
+ // Contains the name of the main translet class
+ private String _transletName = null;
+
+ // Contains the actual class definition for the translet class and
+ // any auxiliary classes (representing node sort records, predicates, etc.)
+ private byte[][] _bytecodes = null;
+
+ /**
+ * Defines the translet class and auxiliary classes.
+ * Returns a reference to the Class object that defines the main class
+ */
+ private Class defineTransletClasses() {
+ TransletClassLoader loader = getTransletClassLoader();
+
+ try {
+ Class transletClass = null;
+ final int classCount = _bytecodes.length;
+ for (int i = 0; i < classCount; i++) {
+ Class clazz = loader.defineClass(_bytecodes[i]);
+ if (clazz.getName().equals(_transletName))
+ transletClass = clazz;
+ }
+ return transletClass; // Could still be 'null'
+ }
+ catch (ClassFormatError e) {
+ return null;
+ }
+ }</pre>
+</blockquote>
+
+
+ <h5>Translet class loader</h5>
+
+ <p>The <code>Templates</code> object will create the actual translet
+ <code>Class</code> object(s) the first time the
+ <code>newTransformer()</code> method is called. (The "first time" means the
+ first time either after the object was instanciated or the first time after
+ it has been read from storage using serialization.) These class(es) cannot
+ be created using the standard class loader since the method:</p>
+<blockquote class="source">
+<pre>
+ Class defineClass(String name, byte[] b, int off, int len);</pre>
+</blockquote>
+
+ <p>of the ClassLoader is protected. XSLTC uses its own class loader that
+ extends the standard class loader:</p>
+<blockquote class="source">
+<pre>
+ // Our own private class loader - builds Class definitions from bytecodes
+ private class TransletClassLoader extends ClassLoader {
+ public Class defineClass(byte[] b) {
+ return super.defineClass(null, b, 0, b.length);
+ }
+ }</pre>
+</blockquote>
+ <p>This class loader is instanciated inside a privileged code section:</p>
+<blockquote class="source">
+<pre>
+ TransletClassLoader loader =
+ (TransletClassLoader) AccessController.doPrivileged(
+ new PrivilegedAction() {
+ public Object run() {
+ return new TransletClassLoader();
+ }
+ }
+ );</pre>
+</blockquote>
+
+ <p>Then, when the newTransformer() method returns it passes back and
+ instance of XSLTC's <code>Transformer</code> implementation that contains
+ an instance of the main translet class. (One transformation may need several
+ Java classes - for sort-records, predicates, etc. - but there is always one
+ main translet class.)</p>
+
+
+
+ <h5>Class loader security issues</h5>
+
+ <p>When XSLTC is placed inside a JAR-file in the
+ <code>$JAVA_HOME/jre/lib/ext</code> it is loaded by the extensions class
+ loader and not the default (bootstrap) class loader. The extensions class
+ loader does not look for class files/definitions in the user's
+ <code>CLASSPATH</code>. This can cause two problems: A) XSLTC does not find
+ classes for external Java functions, and B) XSLTC does not find translet or
+ auxiliary classes when used through the native API.</p>
+
+ <p>Both of these problems are caused by XSLTC internally calling the
+ <code>Class.forName()</code> method. This method will use the current class
+ loader to locate the desired class (be it an external Java class or a
+ translet/aux class). This is prevented by forcing XSLTC to use the bootstrap
+ class loader, as illustrated below:</p>
+
+ <p>
+<img src="class_loader.gif" alt="ClassLoader" />
+</p>
+ <p>
+<b>
+<i>Figure 2: Avoiding the extensions class loader</i>
+</b>
+</p>
+
+ <p>These are the steps that XSLTC will go through to load a class:</p>
+
+ <ol>
+ <li>the application requests an instance of the transformer factory </li>
+ <li>the Java extensions mechanism locates XSLTC as the transformer
+ factory implementation using the extensions class loader</li>
+ <li>the extensions class loader loads XSLTC</li>
+ <li>XSLTC's compiler attempts to get a reference to an external Java
+ class, but the call to Class.forName() fails, as the extensions class
+ loader does not use the user's class path</li>
+ <li>XSLTC attempts to get a reference to the bootstrap class loader, and
+ requests it to load the external class</li>
+ <li>the bootstrap class loader loads the requested class</li>
+ </ol>
+
+ <p>Step 5) is only allowed if XSLTC has special permissions. But, remember
+ that this problem only occurs when XSLTC is put in the
+ <code>$JAVA_HOME/jre/lib/ext</code> directory, where it is given all
+ permissions (by the default security file).</p>
+
+
+
+
+
+ <a name="transformer_design">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Transformer detailed design</h4>
+
+ <p>The <code>Transformer</code> class is a simple proxy that passes
+ transformation settings on to its translet instance before it invokes the
+ translet's <code>doTransform()</code> method. The <code>Transformer</code>'s
+ <code>transform()</code> method maps directly to the translet's
+ <code>doTransform()</code> method.</p>
+
+ <h5>Transformer input and output handling</h5>
+ <p>The <code>Transformer</code> handles its input in a manner similar to
+ that of the <code>TransformerFactory</code>. It has two methods for
+ creating standard SAX input and output handlers for its input and output
+ files:</p>
+<blockquote class="source">
+<pre>
+ private DOMImpl getDOM(Source source, int mask);
+ private ContentHandler getOutputHandler(Result result);</pre>
+</blockquote>
+
+ <p>One aspect of the <code>getDOM</code> method is that it handles four
+ various types of <code>Source</code> objects. In addition to the standard
+ DOM, SAX and stream types, it also handles an extended
+ <code>XSLTCSource</code> input type. This input type is a lightweight
+ wrapper from XSLTC's internal DOM-like input tree. This allows the user
+ to create a cache or pool of XSLTC's native input data structures
+ containing the input XML document. The <code>XSLTCSource</code> class
+ is located in:</p>
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.trax.XSLTCSource</pre>
+</blockquote>
+
+
+ <h5>Transformer parameter settings</h5>
+ <p>XSLTC's native interface has get/set methods for stylesheet parameters,
+ identical to those of the TrAX API. The parameter handling methods of
+ the <code>Transformer</code> implementation are pure proxies.</p>
+
+
+ <h5>Transformer output settings</h5>
+ <p>The Transformer interface of TrAX has for methods for retrieving and
+ defining the transformation output document settings:</p>
+<blockquote class="source">
+<pre>
+ public Properties getOutputProperties();
+ public String getOutputProperty(String name);
+ public void setOutputProperties(Properties properties);
+ public void setOutputProperty(String name, String value);</pre>
+</blockquote>
+
+ <p>There are three levels of output settings. First there are the default
+ settings defined in the <a href="#">XSLT 1.0 spec</a>, then there
+ are the settings defined in the attributes of the <xsl:output>
+ element, and finally there are the settings passed in through the TrAX
+ get/setOutputProperty() methods.</p>
+
+ <p>
+<img src="trax_output_settings.gif" alt="Output settings" />
+</p>
+ <p>
+<b>
+<i>Figure 3: Passing output settings from TrAX to the translet</i>
+</b>
+</p>
+
+ <p>The AbstractTranslet class has a series of fields that contain the
+ default values for the output settings. The compiler/Output class will
+ compile code into the translet's constructor that updates these values
+ depending on the attributes in the <xsl:output> element. The
+ Transformer implementation keeps in instance of the java.util.Properties
+ class where it keeps all properties that are set by the
+ <code>setOutputProperty()</code> and the
+ <code>setOutputProperties()</code> methods. These settings are written to
+ the translet's output settings fields prior to initiating the
+ transformation.</p>
+
+
+
+ <h5>Transformer URI resolver</h5>
+ <p>The <code>uriResolver()</code> method of the Transformer interface is
+ used to set a locator for documents referenced by the document() function
+ in XSL. The native XSLTC API has a defined interface for a DocumentCache.
+ The functionality provided by XSLTC's internal <code>DocumentCache</code>
+ interface is somewhat complimentary to the <code>URIResolver</code>, and
+ can be used side-by-side. To acomplish this we needed to find out in which
+ ways the translet can load an external document:</p>
+
+ <p>
+<img src="uri_resolver.gif" alt="URIResolver" />
+</p>
+ <p>
+<b>
+<i>Figure 4: Using URIResolver and DocumentCache objects</i>
+</b>
+</p>
+
+ <p>From the diagram we see that these three ways are:</p>
+ <ul>
+ <li>LoadDocument -> .xml</li>
+ <li>LoadDocument -> DocumentCache -> .xml</li>
+ <li>LoadDocument -> URIResolver -> .xml</li>
+ <li>LoadDocument -> DocumentCache -> URIResolver -> .xml</li>
+ </ul>
+
+
+
+
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax_api.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax_api.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax_api.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax_api.html Fri May 16 16:11:33 2014
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: XSLTC TrAX API</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">XSLTC Design</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">XSLTC TrAX API</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="index.html">Overview</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_compiler.html">Compiler design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_whitespace_design.html">Whitespace</a>
+</li>
+<li>
+<a href="xsl_sort_design.html">xsl:sort</a>
+</li>
+<li>
+<a href="xsl_key_design.html">Keys</a>
+</li>
+<li>
+<a href="xsl_comment_design.html">Comment design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_lang_design.html">lang()</a>
+</li>
+<li>
+<a href="xsl_unparsed_design.html">Unparsed entities</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsl_if_design.html">If design</a>
+</li>
+<li>
+<a href="xsl_choose_design.html">Choose|When|Otherwise design</a>
+</li>
+<li>
+<a href="xsl_include_design.html">Include|Import design</a>
+</li>
+<li>
+<a href="xsl_variable_design.html">Variable|Param design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_runtime.html">Runtime</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_dom.html">Internal DOM</a>
+</li>
+<li>
+<a href="xsltc_namespace.html">Namespaces</a>
+</li></ul><hr /><ul>
+<li>
+<a href="xsltc_trax.html">Translet & TrAX</a>
+</li>
+<li>
+<a href="xsltc_predicates.html">XPath Predicates</a>
+</li>
+<li>
+<a href="xsltc_iterators.html">Xsltc Iterators</a>
+</li>
+<li>
+<a href="xsltc_native_api.html">Xsltc Native API</a>
+</li>
+<li>Xsltc TrAX API<br />
+</li>
+<li>
+<a href="xsltc_performance.html">Performance Hints</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>XSLTC TrAX API</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>The JAXP/TrAX API</h3>
+
+ <p>XSLTC is 100% compliant with the TrAX poriton of the
+ <a href="http://java.sun.com/xml/jaxp/index.html">JAXP API</a>. This
+ API is a standard extension to Java and there is not much point in describing
+ it in detail in this document.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>XSLTC's extensions to JAXP/TrAX</h3>
+
+ <p>The <code>Source</code> and <code>Result</code> classes within TrAX are
+ used to handle input and output documents. These classes can be extended to
+ encapsulate additional input types. XSLTC's TrAX implementation contains an
+ extension to the <code>Source</code> class:</p>
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.trax.XSLTCSource</pre>
+</blockquote>
+
+ <p>This extension class can be used to build XSLTC's internal
+ DOM and cache it for later usage. The following sample shows how to
+ use it with a <code>Transformer:</code>
+</p>
+<blockquote class="source">
+<pre>
+ public void run(String xmlfile, String xslfile) {
+
+ // Create an XSLTCSource for the input XML document
+ XSLTCSource source = new XSLTCSource(xmlfile);
+
+ // Build a StreamSource for the stylesheet
+ StreamSource stylesheet = new StreamSource(xslfile);
+
+ // Create a Transformer instance and process the input
+ Transformer transformer = factory.newTransformer(stylesheet);
+ transformer.transform(source, new StreamResult(System.out));
+ :
+ :
+ }</pre>
+</blockquote>
+
+ <p>If you do chose to implement a DOM cache, you should have your cache
+ implement the <code>javax.xml.transform.URIResolver</code> interface so
+ that documents loaded by the <code>document()</code> function are also read
+ from your cache.</p>
+
+
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_trax_api.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xalan.apache.org
For additional commands, e-mail: commits-help@xalan.apache.org