You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by mo...@apache.org on 2002/01/06 16:52:00 UTC
cvs commit: xml-xalan/java/xdocs/style/stylesheets designdoc2html.xsl
morten 02/01/06 07:52:00
Modified: java/xdocs/sources/xsltc index.xml xsl_comment_design.xml
xsl_key_design.xml xsl_lang_design.xml
xsl_sort_design.xml xsl_unparsed_design.xml
xsl_whitespace_design.xml xsltc_compiler.xml
xsltc_dom.xml xsltc_iterators.xml
xsltc_namespace.xml xsltc_native_api.xml
xsltc_predicates.xml xsltc_runtime.xml
xsltc_trax.xml xsltc_trax_api.xml
java/xdocs/style/stylesheets designdoc2html.xsl
Log:
An update for XSLTC's design documents. Updated the designdoc2html
stylesheet to allow for a few more styling elements.
PR: none
Submitted by: morten@xml.apache.org
Reviewed by: morten@xml.apache.org
Revision Changes Path
1.10 +28 -17 xml-xalan/java/xdocs/sources/xsltc/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/index.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.xml 19 Dec 2001 15:25:41 -0000 1.9
+++ index.xml 6 Jan 2002 15:52:00 -0000 1.10
@@ -59,12 +59,13 @@
<s1 title="XSLTC Documentation">
- <s2 title="XSLTC User Documentation">
+ <p><img src="xmllogo.gif"/></p>
+ <s2 title="User Documentation">
<p>The following user documentation is currently available:</p>
-
<ul>
- <li>XSLTC <jump href="README">Installation and Requirements</jump> 'README' (not updated)</li>
+ <li>XSLTC <jump href="README">Installation and Requirements</jump>
+ 'README' (not updated)</li>
<li>Command-line <jump href="README.xsltc">compiler</jump> and
<jump href="README.xslt">runtime</jump> 'README'</li>
<li><link idref="xsltc_native_api">XSLTC Native API reference</link></li>
@@ -73,10 +74,8 @@
</ul>
</s2>
- <s2 title="XSLTC Design Documents">
-
+ <s2 title="Design Documents">
<p>The following design documents are currently available:</p>
-
<ul>
<li><link anchor="overall">XSLTC overall design</link></li>
<li><link anchor="compiler">XSLTC compiler design</link></li>
@@ -95,8 +94,8 @@
<p><ref>Figure 1: Architectural overview of XSLTC</ref></p>
<p>A client application can use XSLTC either through its
- <link anchor="user_native">native API</link> or through or implementation
- of the <link anchor="user_trax">TrAX API</link>. The
+ <link idref="xsltc_native_api">native API</link> or through or
+ implementation of the <link idref="xsltc_trax_api">TrAX API</link>. The
<link anchor="compiler">compiler</link> generates one or more Java classes
(we have chosen to call them 'translets').
The <link anchor="runtime">runtime library</link> contains classes that
@@ -120,20 +119,29 @@
design documents for some XSL elements and XPath expressions, patterns
and functions:</p>
+ <small-table>
+ <tr><td>
<s4 title="XSL elements">
<ul>
<li><link idref="xsl_sort_design"><xsl:sort></link></li>
<li><link idref="xsl_key_design"><xsl:key></link></li>
- <li>
- <link idref="xsl_whitespace_design"><xsl:preserve-space>/<xsl:strip-space></link>
- </li>
- <li>
- <link idref="xsl_comment_design"><xsl:comment>/<xsl:message></link>
- </li>
+ <li><link idref="xsl_whitespace_design"><xsl:preserve-space></link></li>
+ <li><link idref="xsl_whitespace_design"><xsl:strip-space></link></li>
+ <li><link idref="xsl_comment_design"><xsl:comment></link></li>
+ <li><link idref="xsl_comment_design"><xsl:message></link></li>
+ <li><link idref="xsl_if_design"><xsl:if></link></li>
+ <li><link idref="xsl_choose_design"><xsl:choose></link></li>
+ <li><link idref="xsl_variable_design"><xsl:variable></link></li>
+ <li><link idref="xsl_variable_design"><xsl:param></link></li>
+ <li><link idref="xsl_include_design"><xsl:include></link></li>
+ <li><link idref="xsl_include_design"><xsl:import></link></li>
+ <li><link idref="xsl_apply_imp_design"><xsl:apply-imports></link></li>
</ul>
</s4>
+ </td><td>
+
<s4 title="XPath functions">
<ul>
<li><link idref="xsl_key_design">key()</link></li>
@@ -142,19 +150,22 @@
</ul>
</s4>
-
<s4 title="XPath expressons">
<ul>
<li><link idref="xsltc_predicates">Predicates</link></li>
</ul>
</s4>
-
<s4 title="XPath patterns">
<ul>
- <li>StepPattern</li>
+ <li><jump href="xsltc_predicates.html#step-pattern">StepPattern</jump></li>
+ <li><jump href="xsl_key_design.html#patterns">IdPattern</jump></li>
+ <li><jump href="xsl_key_design.html#patterns">KeyPattern</jump></li>
</ul>
</s4>
+
+ </td></tr>
+ </small-table>
</s3>
1.2 +2 -0 xml-xalan/java/xdocs/sources/xsltc/xsl_comment_design.xml
Index: xsl_comment_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_comment_design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsl_comment_design.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsl_comment_design.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,6 +57,8 @@
* <http://www.apache.org/>.
-->
<s1 title="<xsl:comment> / <xsl:message>">
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="implementation">Implementation</link></li>
1.2 +182 -99 xml-xalan/java/xdocs/sources/xsltc/xsl_key_design.xml
Index: xsl_key_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_key_design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsl_key_design.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsl_key_design.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -56,11 +56,16 @@
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
- <s1 title="<xsl:key> / key() / KeyPattern">
+ <s1 title="<xsl:key> / key() / IdKeyPattern">
+ <p><img src="xmllogo.gif"/></p>
+
+ <s2 title="Contents">
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="implementation">Implementation</link></li>
</ul>
+ </s2>
+
<anchor name="functionality"/>
<s2 title="Functionality">
@@ -82,133 +87,211 @@
</li>
</ul>
- <p>A named index can be accessed using either the <code>key()</code> function or
- a KeyPattern. Both these methods address the index using its defined name
+ <p>A named index can be accessed using either the <code>key()</code> function
+ or a KeyPattern. Both these methods address the index using its defined name
(the "name" attribute above) and a parameter defining one or more lookup
values for the index. The function or pattern returns a node set containing
all nodes in the index whose key value match the parameter's value(s):</p>
<source>
<xsl:key name="book-author" match="book" use="author"/>
- :
- :
+ :
+ :
<xsl:for-each select="key('book-author', 'Mikhail Bulgakov')">
<xsl:value-of select="author"/>
<xsl:text>: </xsl:text>
<xsl:value-of select="author"/>
<xsl:text>&#xa;</xsl:text>
- </xsl:for-each>
- </source>
+ </xsl:for-each></source>
<p>The KeyPattern can be used within an index definition to create unions
- and intersections of node sets:</p>
+ and intersections of node sets:</p><source>
+ <xsl:key name="cultcies" match="farmer | fisherman" use="name"/></source>
-<source>
- <xsl:key name="cultcies" match="farmer | fisherman" use="name"/>
-</source>
-
- <p>This could of course be done using regular <code><xsl:for-each></code>
+ <p>This could have been done using regular <code><xsl:for-each></code>
and <code><xsl:select></code> elements. However, if your stylesheet
accesses the same selection of nodes over and over again, the transformation
will be much more efficient using pre-indexed keys as shown above.</p>
- </s2><anchor name="implementation"/>
- <s2 title="Implementation">
- <p>AbstractTranslet has a global hashtable that holds an index for each named
- key in the stylesheet (hashing on the "name" attribute of xsl:key).
- AbstractTranslet has a couple of public methods for inserting and retrieving
- data from this hashtable:</p>
-
-<source>
- public void buildKeyIndex(String name, int nodeID, String value);
- public KeyIndex KeyIndex getKeyIndex(String name);
-</source>
-
- <p>The Key class compiles code that traverses the input DOM and extracts
- nodes that match some given parameters (the <code>"match"</code> attribute of the
- <code><xsl:key></code> element). A new element is inserted into the named
- key's index. The nodes' DOM index and the value translated from the
- <code>"use"</code> attribute of the <code><xsl:key></code> element are stored
- in the new entry in the index.</p>
-
- <p>The index itself is implemented in the <code>KeyIndex</code> class.
- The index has an hashtable with all the values from the matching nodes (the
- part of the node used to generate this value is the one specified in the
- <code>"use"</code> attribute). For every matching value there is a Vector
- holding a list of all node indexes for which this value gives a match:</p>
-
- <p><img src="key_relations.gif" alt="key_relations.gif"/></p>
- <p><ref>Figure 1: Indexing tables</ref></p>
-
- <p>The <code>KeyIndex</code> class implements the <code>NodeIterator</code>
- interface, so that it can be returned directly by the implementation of the
- <code>key()</code> function. This is how the index generated by
- <code><xsl:key></code> and the node-set returned by the <code>key()</code> and
- KeyPattern are tied together. You can see how this is done in the
- <code>translate()</code> method of the <code>KeyCall</code> class.</p>
+ </s2>
+
+ <anchor name="implementation"/>
+ <s2 title="Implementation">
- <p>The <code>key()</code> function can be called in two ways:</p>
+ <anchor name="indexing"/>
+ <s3 title="Indexing">
-<source>
- key('key-name','value')
- key('key-name','node-set')
-</source>
+ <p>The <code>AbstractTranslet</code> class has a global hashtable that holds
+ an index for each named key in the stylesheet (hashing on the "name"
+ attribute of <code><xsl:key></code>). <code>AbstractTranslet</code>
+ has a couple of public methods for inserting and retrieving data from this
+ hashtable:</p><source>
+ public void buildKeyIndex(String keyName, int nodeID, String value);
+ public KeyIndex KeyIndex getKeyIndex(String keyName);</source>
+
+ <p>The <code>Key</code> class compiles code that traverses the input DOM and
+ extracts nodes that match some given parameters (the <code>"match"</code>
+ attribute of the <code><xsl:key></code> element). A new element is
+ inserted into the named key's index. The nodes' DOM index and the value
+ translated from the <code>"use"</code> attribute of the
+ <code><xsl:key></code> element are stored in the new entry in the
+ index.</p>
+
+ <p>Something similar is done for indexing IDs. This index is generated from
+ the <code>ID</code> and <code>IDREF</code> fields in the input document's
+ DTD. This means that the code for generating this index cannot be generated
+ at compile-time, which again means that the code has to be generic enough
+ to handle all DTDs. The class that handles this is the
+ <code>org.apache.xalan.xsltc.dom.DTDMonitor</code> class. This class
+ implements the <code>org.xml.sax.XMLReader</code> and
+ <code>org.xml.sax.DTDHandler</code> interfaces. A client application using
+ the native API must instanciate a <code>DTDMonitor</code> and pass it to the
+ translet code - if, and only if, it wants IDs indexed (one can improve
+ performance by omitting this step). This is descrived in the
+ <link idref="xsltc_native_api">XSLTC Native API reference</link>. The
+ <code>DTDMonitor</code> class will use the same indexing as the code
+ generated by the <code>Key</code> class. The index for ID's is called
+ "##id". We assume that no stylesheets will contain a key with this name.</p>
+
+ <p>The index itself is implemented in the
+ <code>org.apache.xalan.xsltc.dom.KeyIndex</code> class. The index has an
+ hashtable with all the values from the matching nodes (the part of the node
+ used to generate this value is the one specified in the <code>"use"</code>
+ attribute). For every matching value there is a bit-array (implemented in
+ the <code>org.apache.xalan.xsltc.BitArray</code> class), holding a list of
+ all node indexes for which this value gives a match:</p>
+ <p><img src="key_relations.gif" alt="key_relations.gif"/></p>
+ <p><ref>Figure 1: Indexing tables</ref></p>
+
+ <p>The <code>KeyIndex</code> class implements the <code>NodeIterator</code>
+ interface, so that it can be returned directly by the implementation of the
+ <code>key()</code> function. This is how the index generated by
+ <code><xsl:key></code> and the node-set returned by the
+ <code>key()</code> and KeyPattern are tied together. You can see how this is
+ done in the <code>translate()</code> method of the <code>KeyCall</code>
+ class.</p>
- <p>The first parameter is always the name of the key. We use this value to
- lookup our index from the _keyIndexes hashtable in AbstractTranslet:</p>
+ <p>The <code>key()</code> function can be called in two ways:</p><source>
+ key('key-name','value')
+ key('key-name','node-set')</source>
-<source>
+ <p>The first parameter is always the name of the key. We use this value to
+ lookup our index from the _keyIndexes hashtable in AbstractTranslet:</p>
+ <source>
il.append(classGen.aloadThis());
_name.translate(classGen, methodGen);
- il.append(new INVOKEVIRTUAL(getKeyIndex));
-</source>
+ il.append(new INVOKEVIRTUAL(getKeyIndex));</source>
- <p>This compiles into a call to
- <code>AbstractTranslet.getKeyIndex(String name)</code>, and it leaves a
- <code>KeyIndex</code> object on the stack. What we then need to do it to
- initialise the <code>KeyIndex</code> to give us nodes with the requested value.
- This is done by leaving the <code>KeyIndex</code> object on the stack and pushing
- the <code>"value"</code> parameter to <code>key()</code>, before calling
- <code>lookup()</code> on the index:</p>
-
-<source>
+ <p>This compiles into a call to
+ <code>AbstractTranslet.getKeyIndex(String name)</code>, and it leaves a
+ <code>KeyIndex</code> object on the stack. What we then need to do it to
+ initialise the <code>KeyIndex</code> to give us nodes with the requested
+ value. This is done by leaving the <code>KeyIndex</code> object on the stack
+ and pushing the <code>"value"</code> parameter to <code>key()</code>, before
+ calling <code>lookup()</code> on the index:</p><source>
il.append(DUP); // duplicate the KeyIndex obejct before return
_value.translate(classGen, methodGen);
- il.append(new INVOKEVIRTUAL(lookup));
-</source>
+ il.append(new INVOKEVIRTUAL(lookup));</source>
- <p>This compiles into a call to <code>KeyIndex.lookup(String value)</code>. This
- will initialise the <code>KeyIndex</code> object to return nodes that match the
- given value, so the <code>KeyIndex</code> object can be left on the stack when
- we return. This because the <code>KeyIndex</code> object implements the
- <code>NodeIterator</code> interface.</p>
-
- <p>This matter is a bit more complex when the second parameter of
- <code>key()</code> is a node-set. In this case we need to traverse the nodes in
- the set and do a lookup for each node in the set. What I do is this:</p>
+ <p>This compiles into a call to <code>KeyIndex.lookup(String value)</code>.
+ This will initialise the <code>KeyIndex</code> object to return nodes that
+ match the given value, so the <code>KeyIndex</code> object can be left on
+ the stack when we return. This because the <code>KeyIndex</code> object
+ implements the <code>NodeIterator</code> interface.</p>
+
+ <p>This matter is a bit more complex when the second parameter of
+ <code>key()</code> is a node-set. In this case we need to traverse the nodes
+ in the set and do a lookup for each node in the set. What I do is this:</p>
+
+ <ul>
+ <li>
+ construct a <code>KeyIndex</code> object that will hold the
+ return node-set
+ </li>
+ <li>
+ find the named <code>KeyIndex</code> object from the hashtable in
+ AbstractTranslet
+ </li>
+ <li>
+ get an iterator for the node-set and do the folowing loop:</li>
+ <ul>
+ <li>get string value for current node</li>
+ <li>do lookup in KeyIndex object for the named index</li>
+ <li>merge the resulting node-set into the return node-set</li>
+ </ul>
+ <li>
+ leave the return node-set on stack when done
+ </li>
+ </ul>
+
+ </s3>
+
+ <anchor name="improvements"/>
+ <s3 title="Possible indexing improvements">
+
+ <p>The indexing implementation can be very, very memeory exhaustive as there
+ is one <code>BitArray</code> allocated for each value for every index. This
+ is particulary bad for the index used for IDs ('##id'), where a single value
+ should only map to one, single node. This means that a whole
+ <code>BitArray</code> is used just to contain one node. The
+ <code>KeyIndex</code> class should be updated to hold the first node for a
+ value in an <code>Integer</code> object, and then replace that with a
+ <code>BitArray</code> or a <code>Vector</code> only is a second node is
+ added to the value. Here is an outline for <code>KeyIndex</code>:</p>
+ <source>
+
+ public void add(Object value, int node) {
+ Object container;
+ if ((container = (BitArray)_index.get(value)) == null) {
+ _index.put(value, new Integer(node));
+ }
+ else {
+ // Check if there is _one_ node for this value
+ if (container instanceof Integer) {
+ int first = ((Integer)container
+ _nodes = new BitArray(_arraySize);
+ _nodes.setMask(node & 0xff000000);
+ _nodes.setBit(first & 0x00ffffff);
+ _nodes.setBit(node & 0x00ffffff);
+ _index.put(value, _nodes);
+ }
+ // Otherwise add node to axisting bit array
+ else {
+ _nodex = (BitArray)container;
+ _nodes.setBit(node & 0x00ffffff);
+ }
+ }
+ }</source>
+
+ <p>Other methods inside the <code>KeyIndex</code> should be updated to
+ reflect this.</p>
+
+ </s3>
+
+ <anchor name="patterns"/>
+ <s3 title="Id and Key patterns">
+
+ <p>As already mentioned, the challenge with the <code>id()</code> and
+ <code>key()</code> patterns is that they have no specific node type.
+ Patterns are normally grouped based on their pattern's "kernel" node type.
+ This is done in the <code>org.apache.xalan.xsltc.compiler.Mode</code> class.
+ The <code>Mode</code> class has a method, <code>flatternAlaternative</code>,
+ that does this grouping, and all templates with a common kernel node type
+ will be inserted into a "test sequence". A test sequence is a set templates
+ with the same kernel node type. The <code>TestSeq</code> class generates
+ code that will figure out which pattern, amongst several patterns with the
+ same kernel node type, that matches a certain node. This is used by the
+ <code>Mode</code> class when generating the <code>applyTemplates</code>
+ method in the translet. A test sequence is also generated for all templates
+ whose pattern does not have a kernel node type. This is the case for all
+ Id and KeyPatterns. This test sequence, if necessary, is put before the
+ big <code>switch()</code> in the <code>applyTemplates()</code> mehtod. This
+ test has to be done for every single node that is traversed, causing the
+ transformation to slow down siginificantly. This is why we do <u>not</u>
+ recommend using this type of patterns with XSLTC.</p>
- <ul>
- <li>
- construct a <code>KeyIndex</code> object that will hold the return node-set
- </li>
- <li>
- find the named <code>KeyIndex</code> object from the hashtable in
- AbstractTranslet
- </li>
- <li>
- get an iterator for the node-set and do the folowing loop:</li>
- <ul>
- <li>get string value for current node</li>
- <li>do lookup in KeyIndex object for the named index</li>
- <li>merge the resulting node-set into the return node-set</li>
- </ul>
- <li>
- leave the return node-set on stack when done
- </li>
- </ul>
+ </s3>
- <p>The only work that remains is to update the <code>merge()</code> method of
- the <code>KeyIndex</code> class so that it eliminates duplicate nodes in the
- resulting node-set.</p>
</s2>
+
</s1>
1.2 +2 -0 xml-xalan/java/xdocs/sources/xsltc/xsl_lang_design.xml
Index: xsl_lang_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_lang_design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsl_lang_design.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsl_lang_design.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,6 +57,8 @@
* <http://www.apache.org/>.
-->
<s1 title="lang() function">
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="implementation">Implementation</link></li>
1.2 +15 -12 xml-xalan/java/xdocs/sources/xsltc/xsl_sort_design.xml
Index: xsl_sort_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_sort_design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsl_sort_design.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsl_sort_design.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,23 +57,26 @@
* <http://www.apache.org/>.
-->
<s1 title="<xsl:sort>">
+
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="sort-class">The Sort class</link></li>
- <li><link anchor="sortingiterator-class">The SortingIterator class</link></li>
- <li><link anchor="nodesortrecord-class">The NodeSortRecord class</link></li>
- <li><link anchor="nodesortrecordfactory-class">The NodeSortRecordFactory class</link></li>
+ <li><link anchor="iterator">The SortingIterator class</link></li>
+ <li><link anchor="sortrecord">The NodeSortRecord class</link></li>
+ <li><link anchor="recordfactory">The NodeSortRecordFactory class</link></li>
</ul>
<anchor name="functionality"/>
<s2 title="Functionality">
- <p>The <code><xsl:sort></code> element is used to define a sort key which
- specifies the order in which nodes selected by either
- <code><xsl:apply-templates></code> or <code><xsl:for-each></code> are
- processed. The nodes can be sorted either in numerical or alphabetic order,
- and the alphabetic order may vary depeinding on the language in use. The
- nodes can be sorted either in ascending or descending order.</p>
+ <p>The <code><xsl:sort></code> element is used to define a sort key
+ which specifies the order in which nodes selected by either
+ <code><xsl:apply-templates></code> or <code><xsl:for-each></code>
+ are processed. The nodes can be sorted either in numerical or alphabetic
+ order, and the alphabetic order may vary depeinding on the language in use.
+ The nodes can be sorted either in ascending or descending order.</p>
</s2><anchor name="sort-class"/>
<s2 title="The Sort class">
@@ -97,7 +100,7 @@
specific order to the code handling the <code><xsl:apply-templates></code>
or <code><xsl:for-each></code> element.</p>
- </s2><anchor name="sortingiterator-class"/>
+ </s2><anchor name="iterator"/>
<s2 title="The SortingIterator class">
<p>The SortingIterator class is responsible for sorting nodes encapsulated in
@@ -113,7 +116,7 @@
object and sorts them using quicksort and calling <code>compareTo()</code> on
pairs of NodeSortRecord objects.</p>
- </s2><anchor name="nodesortrecord-class"/>
+ </s2><anchor name="sortrecord"/>
<s2 title="The NodeSortRecord class">
<p>The static methods in the Sort class generates a class inheriting from
@@ -199,7 +202,7 @@
called when needed. The value for a node's secondary sort key is never
retrieved if the node can be uniquely identified by its primary key.</p>
- </s2><anchor name="nodesortrecordfactory-class"/>
+ </s2><anchor name="recordfactory"/>
<s2 title="The NodeSortRecordFactory class">
<p>After the static methods of the Sort class has generated the new class for
1.2 +2 -0 xml-xalan/java/xdocs/sources/xsltc/xsl_unparsed_design.xml
Index: xsl_unparsed_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_unparsed_design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsl_unparsed_design.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsl_unparsed_design.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,6 +57,8 @@
* <http://www.apache.org/>.
-->
<s1 title="unparsed-entity-uri()">
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="implementation">Implementation</link></li>
1.3 +3 -0 xml-xalan/java/xdocs/sources/xsltc/xsl_whitespace_design.xml
Index: xsl_whitespace_design.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsl_whitespace_design.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xsl_whitespace_design.xml 14 May 2001 16:07:30 -0000 1.2
+++ xsl_whitespace_design.xml 6 Jan 2002 15:52:00 -0000 1.3
@@ -57,6 +57,9 @@
* <http://www.apache.org/>.
-->
<s1 title="<xsl:strip/preserve-space>">
+
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="identify">Identifying strippable whitespace nodes</link></li>
1.5 +3 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_compiler.xml
Index: xsltc_compiler.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_compiler.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- xsltc_compiler.xml 19 Dec 2001 15:38:09 -0000 1.4
+++ xsltc_compiler.xml 6 Jan 2002 15:52:00 -0000 1.5
@@ -58,6 +58,9 @@
-->
<s1 title="XSLTC Compiler Design">
+
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="overview">Compiler Overview</link></li>
<li><link anchor="ast">Building the Abstract Syntax Tree</link></li>
1.2 +15 -12 xml-xalan/java/xdocs/sources/xsltc/xsltc_dom.xml
Index: xsltc_dom.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_dom.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsltc_dom.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsltc_dom.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,6 +57,9 @@
* <http://www.apache.org/>.
-->
<s1 title="XSLTC Internal DOM">
+
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">General functionlaity</link></li>
<li><link anchor="components">Components of the internal DOM</link></li>
@@ -83,7 +86,7 @@
<ul>
<li><em>org.apache.xalan.xsltc.dom.DOMImpl</em><br/><br/>
This is the main DOM class. An instance of this class contains the nodes
- of a <em>single</em> XML document.<br/>br/>
+ of a <em>single</em> XML document.<br/><br/>
</li>
<li><em>org.apache.xalan.xsltc.dom.MultiDOM</em><br/><br/>
This class is best described as a DOM multiplexer. XSLTC was initially
@@ -92,14 +95,14 @@
<code>document()</code> function in mind. This class will allow a translet
to access multiple DOMs through the original DOM interface.<br/><br/>
</li>
- <li><em>org.apache.xalan.xsltc.dom.DOMAdapter</em><br/>br/>
+ <li><em>org.apache.xalan.xsltc.dom.DOMAdapter</em><br/><br/>
The DOM adapter is a mediator between a DOMImpl or a MultiDOM object and
a single translet. A DOMAdapter object contains mappings and reverse
mappings between node types in the DOM(s) and node types in the translet.
This mediator is needed to allow several translets access to a single DOM.
- <br/>br/>
+ <br/><br/>
</li>
- <li><em>org.apache.xalan.xsltc.dom.DocumentCache</em><br/>br/>
+ <li><em>org.apache.xalan.xsltc.dom.DocumentCache</em><br/><br/>
A sample DOM cache (implementing DOMCache) that is used with our sample
transformation applications.
</li>
@@ -348,18 +351,18 @@
<p>A node in the DOM is identified by an integer. The first 8 bits of this
integer are used to identify the DOM in which the node belongs, while the
lower 24 bits are used to identify the node within the DOM:</p>
- <table>
+ <small-table leave-me-alone="yes" border="2">
<tr>
- <td>31-24</td>
- <td>23-16</td>
- <td>16-8</td>
- <td>7-0</td>
+ <td align="center" width="50">31-24</td>
+ <td align="center" width="50">23-16</td>
+ <td align="center" width="50">16-8</td>
+ <td align="center" width="50">7-0</td>
</tr>
<tr>
- <td>DOM id</td>
- <td colspan="3">node id</td>
+ <td align="center">DOM id</td>
+ <td colspan="3" align="center">node id</td>
</tr>
- </table>
+ </small-table>
<p>The DOM multiplexer has an array of DOMAdapter objects. The topmost 8
bits of the identifier is used to find the correct DOM from the array. Then
1.5 +2 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_iterators.xml
Index: xsltc_iterators.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_iterators.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- xsltc_iterators.xml 19 Dec 2001 16:21:09 -0000 1.4
+++ xsltc_iterators.xml 6 Jan 2002 15:52:00 -0000 1.5
@@ -59,6 +59,8 @@
<s1 title="XSLTC node iterators">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="Contents">
<p>This document describes the function of XSLTC's node iterators. It also
1.2 +3 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_namespace.xml
Index: xsltc_namespace.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_namespace.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsltc_namespace.xml 4 May 2001 20:20:43 -0000 1.1
+++ xsltc_namespace.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -57,6 +57,9 @@
-->
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<s1 title="XSLTC and Namespaces">
+
+ <p><img src="xmllogo.gif"/></p>
+
<ul>
<li><link anchor="functionality">Functionality</link></li>
<li><link anchor="overview">Namespace overview</link></li>
1.3 +3 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_native_api.xml
Index: xsltc_native_api.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_native_api.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xsltc_native_api.xml 20 Dec 2001 17:46:49 -0000 1.2
+++ xsltc_native_api.xml 6 Jan 2002 15:52:00 -0000 1.3
@@ -59,6 +59,8 @@
<s1 title="XSLTC Native API Documentation">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="XSLTC Compiler API">
<p>XSLTC's native API is represented by the
@@ -140,6 +142,7 @@
</s3>
+ <anchor name="document-locator"/>
<s3 title="Input document locator interface">
<p>XSLTC's compiler has an interface that a client application can implement
1.3 +168 -13 xml-xalan/java/xdocs/sources/xsltc/xsltc_predicates.xml
Index: xsltc_predicates.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_predicates.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xsltc_predicates.xml 19 Dec 2001 16:12:22 -0000 1.2
+++ xsltc_predicates.xml 6 Jan 2002 15:52:00 -0000 1.3
@@ -59,6 +59,8 @@
<s1 title="XSLTC Predicate Handling">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="Definition">
<p>According to Michael Kay's "XSLT Programmer's Reference" page
@@ -80,16 +82,16 @@
<?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">
+ <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">
+ <bar name="Peter's Pub"/>
+ <bar name="Grogan's"/>
+ <bar name="Hogans's"/>
+ <bar name="Brogan's"/>
</foo>
</doc></source>
@@ -166,9 +168,9 @@
<s3 title="Single predicate expressions">
<p>Expressions containing just a single predicate have no intermediate step
- and there is no need for any extra iterator. The original iterator
- representing the step the predicate is applied to is used. We call this
- category SIMPLE_CONTEXT.</p>
+ 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>
</s3>
@@ -201,6 +203,7 @@
</s3>
+ <anchor name="exception"/>
<s3 title="Expressions containing one position predicate">
<p>There is one expection from the GENERAL_CONTEXT category. If the
@@ -221,8 +224,160 @@
<s2 title="Design details">
- <s3 title="Predicates in Step expressions"></s3>
- <s3 title="Predicates in StepPatterns"></s3>
+ <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>
+
+ <s3 title="Predicates and Step expressions">
+
+ <p>The basic behaviour for a predicate is to compile a <i>filter</i>. 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><source>
+ public interface CurrentNodeListFilter {
+ public abstract boolean test(int node, int position, int last, int current,
+ AbstractTranslet translet, NodeIterator iter);
+ }</source>
+
+ <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><source>
+ public CurrentNodeListIterator(NodeIterator source,
+ CurrentNodeListFilter filter,
+ int currentNode,
+ AbstractTranslet translet) {
+ this(source, !source.isReverse(), filter, currentNode, translet);
+ }</source>
+
+ <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>
+
+ </s3>
+
+ <s3 title="Optimisations in Step expressions">
+
+ <s4 title="Node-value iterators">
+
+ <p>Some simple predicates that test for node values are handled by the
+ <code>NodeValueIterator</code> class at runtime. These are:</p><source>
+ A: foo[@attr = <value>]
+ B: foo[bar = <value>]
+ C: foo/bar[. = <value>]</source>
+
+ <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 <i><value></i> is an
+ expression that is compiled and passed to the iterator as a string. It
+ does <u><i>not</i></u> 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>
+
+ </s4>
+
+ <s4 title="Nth descendant iterators">
+
+ <p>The <code>Step</code> class is also optimised for position-predicates
+ that are applied to descendant iterators:</p><source>
+ <xsl:for-each select="//bar[3]"></source>
+
+ <p>Such step/predicate combinations are handled by the internal DOM's
+ inner class <code>NthDescendantIterator</code>.</p>
+
+ </s4>
+
+ <s4 title="Nth position iterators">
+
+ <p>Similarly, the <code>Step</code> class is optimised for
+ position-predicates that are applied to basic steps:</p><source>
+ <xsl:for-each select="bar[3]"></source>
+
+ <p>Such step/predicate combinations are handled by the internal DOM's
+ inner class <code>NthPositionIterator</code>.</p>
+
+ </s4>
+
+ <s4 title="Node test">
+
+ <p>The predicate class contains a method that tells you if it is a boolean
+ test:</p><source>
+ public boolean isBooleanTest();</source>
+
+ <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>
+
+ </s4>
+
+ </s3>
+
+ <anchor name="step-patterns"/>
+ <s3 title="Predicates and StepPatterns">
+
+ <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>
+
+ <s4 title="Basic pattern handling">
+
+ <p>All patterns are grouped (by the <code>Mode</code> class) according to
+ their <i>kernel</i>-node type. The kernel node-type is node-type of the
+ <u>last</u> step in a pattern:</p><source>
+ <xsl:template match="foo/bar/baz"> ... <xsl:template></source>
+
+ <p>In this case the type for elements <code><baz></code> is the
+ kernel type. This step is <u>not</u> 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 <i>reduced</i> to:</p><source>
+ match="foo/bar"</source>
+
+ <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><source>
+ <xsl:template match="foo/*/baz"> ... <xsl:template>
+ <xsl:template match="foo/*@[2]"> ... <xsl:template></source>
+
+ <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>
+
+ </s4>
+
+ <s4 title="Patterns with predicates">
+
+ <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
+ <link anchor="exception">Expressions containing one position predicate</link> 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>
+
+ </s4>
+
+ </s3>
</s2>
1.5 +2 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_runtime.xml
Index: xsltc_runtime.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_runtime.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- xsltc_runtime.xml 19 Dec 2001 15:40:50 -0000 1.4
+++ xsltc_runtime.xml 6 Jan 2002 15:52:00 -0000 1.5
@@ -59,6 +59,8 @@
<s1 title="XSLTC runtime environment">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="Contents">
<p>This document describes the design and overall architecture of XSLTC's
1.7 +6 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_trax.xml
Index: xsltc_trax.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_trax.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- xsltc_trax.xml 19 Dec 2001 15:46:49 -0000 1.6
+++ xsltc_trax.xml 6 Jan 2002 15:52:00 -0000 1.7
@@ -59,7 +59,13 @@
-->
<s1 title="The Translet API and TrAX">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="Contents">
+
+ <p>Note: This document describes the design of XSLTC's TrAX implementation.
+ The XSLTC <link idref="xsltc_trax_api">TrAX API user documentation</link>
+ is kept in a separate document.</p>
<p>The structure of this document is, and should be kept, as follows:</p>
1.2 +7 -0 xml-xalan/java/xdocs/sources/xsltc/xsltc_trax_api.xml
Index: xsltc_trax_api.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xsltc/xsltc_trax_api.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xsltc_trax_api.xml 17 Dec 2001 16:06:28 -0000 1.1
+++ xsltc_trax_api.xml 6 Jan 2002 15:52:00 -0000 1.2
@@ -59,6 +59,8 @@
<s1 title="XSLTC TrAX API">
+ <p><img src="xmllogo.gif"/></p>
+
<s2 title="The JAXP/TrAX API">
<p>XSLTC is 100% compliant with the TrAX poriton of the
@@ -109,6 +111,11 @@
:
:
}</source>
+
+ <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>
</s2>
1.3 +40 -1 xml-xalan/java/xdocs/style/stylesheets/designdoc2html.xsl
Index: designdoc2html.xsl
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/style/stylesheets/designdoc2html.xsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- designdoc2html.xsl 18 Dec 2001 14:53:48 -0000 1.2
+++ designdoc2html.xsl 6 Jan 2002 15:52:00 -0000 1.3
@@ -18,7 +18,7 @@
<body text="#000000" link="#0000ff" vlink="#0000aa" alink="#ff0000"
topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
bgcolor="#ffffff">
- <xsl:variable name="topimage" select="string(./p/img/@src)"/>
+ <xsl:variable name="topimage" select="./p/img/@src"/>
<h1><a href="http://xml.apache.org"><img src="images/{$topimage}"/></a>  
<xsl:value-of select="@title"/></h1><hr/>
<xsl:apply-templates/>
@@ -70,6 +70,18 @@
</table>
</xsl:template>
+ <xsl:template match="u">
+ <u><xsl:apply-templates/></u>
+ </xsl:template>
+
+ <xsl:template match="i">
+ <i><xsl:apply-templates/></i>
+ </xsl:template>
+
+ <xsl:template match="b">
+ <b><xsl:apply-templates/></b>
+ </xsl:template>
+
<xsl:template match="ul">
<ul><xsl:apply-templates/></ul>
</xsl:template>
@@ -103,6 +115,33 @@
<xsl:template match="source">
<p><font size="-1"><pre><xsl:apply-templates/></pre></font></p>
</xsl:template>
+
+ <xsl:template match="small-table">
+ <center>
+ <xsl:choose>
+ <xsl:when test="@leave-me-alone = 'yes'">
+ <table>
+ <xsl:copy-of select="@*"/>
+ <xsl:copy-of select="*"/>
+ </table>
+ </xsl:when>
+ <xsl:otherwise>
+ <table width="90%" border="0" cellspacing="2">
+ <xsl:apply-templates mode="small-table"/>
+ </table>
+ </xsl:otherwise>
+ </xsl:choose>
+ </center>
+ </xsl:template>
+
+ <xsl:template match="tr" mode="small-table">
+ <tr><xsl:apply-templates mode="small-table"/></tr>
+ </xsl:template>
+
+ <xsl:template match="td" mode="small-table">
+ <td valign="top"><font size="-1"><xsl:apply-templates/></font></td>
+ </xsl:template>
+
<xsl:template match="table">
<table width="100%" border="0" cellspacing="2" cellpadding="2">
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org