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 [15/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_namespace.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_namespace.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_namespace.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_namespace.html Fri May 16 16:11:33 2014
@@ -0,0 +1,832 @@
+<?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 and Namespaces</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 and Namespaces</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>Namespaces<br />
+</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 and Namespaces</h2>
+
+ <ul>
+ <li>
+<a href="#functionality">Functionality</a>
+</li>
+ <li>
+<a href="#overview">Namespace overview</a>
+</li>
+ <li>
+<a href="#NSA">The DOM & namespaces</a>
+</li>
+ <li>
+<a href="#NSB">Namespaces in the XSL stylesheet</a>
+</li>
+ <li>
+<a href="#NSC">Namespaces in the output document</a>
+</li>
+ </ul>
+ <a name="functionality">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Functionality</h3>
+
+ <p>Namespaces are used when an XML documents has elements have the same
+ name, but are from different contexts, and thus have different meanings
+ and interpretations. For instance, a <code><TITLE></code> element can
+ be a HTML title element in one part of the XML document, while it in other
+ parts of the document the <code><TITLE></code> element is used for
+ encapsulating the title of a play or a book. This sort of confusion is
+ very common when reading XML source from multiple documents, but can also
+ occur within a single document.</p>
+
+ <p>Namespaces have three very important properties: a name, a prefix (an
+ alias for its name) and a scope. Namespaces are declared as attributes of
+ almost any node in an XML document. The declaration looks like this:</p>
+
+<blockquote class="source">
+<pre>
+ <element xmlns:prefix="http://some.site/spec">....</element>
+</pre>
+</blockquote>
+
+ <p>The <code>"xmlns"</code> tells that this is a namespace declaration. The
+ scope of the namespace declaration is the element in which it is defined
+ and all the children of that element.The prefix is the local alias we use
+ for referencing the namespace, and the URL (it can be anything, really) is
+ the name/definition of the namespace. Note that even though the namespace
+ definition is normally an URL, it does not have to point to anything. It
+ is recommended that it points to a page that describes the elements in the
+ namespace, but it does not have to. The prefix can be just about anything
+ - or nothing (in which case it is the default namespace). Any prefix,
+ including the empty prefix for the default namespace, can be redefined to
+ refer to a different namespace at any time in an XML document. This is
+ more likely to happen to the default namespace than any other prefix. Here
+ is an example of this:</p>
+
+ <a name="xml_sample_1">â</a>
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+
+ <employees xmlns:postal="http://postal.ie/spec-1.0"
+ xmlns:email="http://www.w3c.org/some-spec-3.2">
+ <employee>
+ <name>Bob Worker</name>
+ <postal:address>
+ <postal:street>Nassau Street</postal:street>
+ <postal:city>Dublin 3</postal:city>
+ <postal:country>Ireland</postal:country>
+ </postal:address>
+ <email:address>bob.worker@hisjob.ie</email:address>
+ </employee>
+ </employees>
+</pre>
+</blockquote>
+
+ <p>This short document has two namespace declarations, one with the prefix
+ <code>"postal"</code> and another with the prefix <code>"email"</code>. The
+ prefixes are used to distinguish between elements for e-mail addresses and
+ regular postal addresses. In addition to these two namespaces there is also
+ an initial (unnamed) default namespace being used for the
+ <code><name></code> and <code><employee></code> tags. The scope of the
+ default namespace is in this case the whole document, while the scope of
+ the other two declared namespaces is the <code><employees></code>
+ element and its children.</p>
+
+ <p>By changing the default namespace we could have made the document a
+ little bit simpler and more readable:</p>
+
+ <a name="xml_sample_2">â</a>
+<blockquote class="source">
+<pre>
+ <?xml version="1.0"?>
+
+ <employees xmlns:email="http://www.w3c.org/some-spec-3.2">
+ <employee>
+ <name>Bob Worker</name>
+ <address xmlns="http://postal.ie/spec-1.0">
+ <street>Nassau Street</street>
+ <city>Dublin 3</city>
+ <country>Ireland</country>
+ </address>
+ <email:address>bob.worker@hisjob.ie</email:address>
+ </employee>
+ </employees>
+</pre>
+</blockquote>
+
+ <p>The default namespace is redefined for the <code><address></code> node
+ and its children, so there is no need to specify the street as
+ <code><postal:street></code> - just plain <code><street></code> is
+ sufficient. Note that this also applies to the <code><address></code>
+ where the namespace is first defined. This is in effect a redefinition of
+ the default namespace.</p>
+ <a name="overview">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Namespace overview</h3>
+
+ <p>Namespaces will have to be handled in three separate parts of the XSLT
+ compiler:</p>
+
+ <a name="all_namespaces">â</a>
+ <p>
+<img src="all_namespaces.gif" alt="all_namespaces.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 1: Namespace handlers in the XSLTC</i>
+</b>
+</p>
+
+ <p>The most obvious is the namespaces in the source XML document
+ (marked <a href="#NSA">"NS A"</a> in figure 1). These namespaces will be
+ handled by our DOM implementation class. The source XSL stylesheet also
+ has its own set of namespaces (<a href="NSB.html">"NS B"</a>) - one of which
+ is the XSL namespace. These namespaces will be handled at run-time and
+ whatever information that is needed to process there should be compiled
+ into the translet. There is also a set of namespaces that will be used in
+ the resulting document (<a href="NSC.html">"NS C"</a>). This is an
+ intersection of the first two. The output document should not contain any
+ more namespace declarations than necessary.</p>
+
+ <a name="NSA">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>The DOM & namespaces</h3>
+ <ul>
+ <li>
+<a href="#dom-namespace">DOM node types and namespace types</a>
+</li>
+ <li>
+<a href="#assign">Assigning namespace types to DOM nodes</a>
+</li>
+ </ul>
+ <a name="dom-namespace">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>DOM node types and namespace types</h4>
+
+ <p>Refer to the XSLTC <a href="xsltc_runtime.html">runtime
+ environment design</a> document for a description of node types before
+ proceeding. In short, each node in the our DOM implementation is
+ represented by a simple integer. By using this integer as an index into an
+ array called <code>_type[]</code> we can find the type of the node.</p>
+
+ <p>The type of the node is an integer representing the type of element the
+ node is. All elements <code><bob></code> will be given the same type,
+ all text nodes will be given the same type, and so on. By using the node
+ type as an index an array called <code>_namesArray[]</code> we can find the
+ name of the element type - in this case "bob". This code fragment shows
+ how you can, with our current implementation, find the name of a node:</p>
+
+<blockquote class="source">
+<pre>
+ int node = iterator.getNext(); // get next node
+ int type = _type[node]; // get node type
+ String name = _namesArray[type]; // get node name
+</pre>
+</blockquote>
+
+ <p>We want to keep the one-type-per-node arrangement, since that lets us
+ produce fairly efficient code. One type in the DOM maps to one type in
+ the compiled translet. What we could do to represent the namespace for
+ each node in the DOM is to add a <code>_namespaceType[]</code> array that holds
+ namespace types. Each node type maps to a namespace type, and each
+ namespace type maps to a namespace name (and a prefix with a limited
+ scope):</p>
+
+ <a name="type_mappings">â</a>
+ <p>
+<img src="type_mappings.gif" alt="type_mappings.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 2: Mapping between node types/names, namespace types/names</i>
+</b>
+</p>
+
+ <p>This code fragment shows how we could get the namespace name for a node:</p>
+
+<blockquote class="source">
+<pre>
+ int node = iterator.getNext(); // get next node
+ int type = _type[node]; // get node type
+ int nstype = _namespace[type]; // get namespace type
+ String name = _namesArray[type]; // get node element name
+ String namespace = _nsNamesArray[nstype]; // get node namespace name
+</pre>
+</blockquote>
+
+ <p>Note that namespace prefixes are not included here. Namespace prefixes
+ are local to the XML document and will be expanded to the full namespace
+ names when the nodes are put into the DOM. This, however, is not a trivial
+ matter.</p>
+ <a name="assign">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Assigning namespace types to DOM nodes</h4>
+
+ <p>We cannot simply have a single namespace prefix array similar to the
+ <code>_namespaceArray[]</code> array for mapping a namespace type to a single
+ prefix. This because prefixes can refer to different namespaces depending
+ on where in the document the prefixes are being used. In our last example's
+ <a href="xml_sample_2.html">XML fragment</a> the empty prefix <code>""</code>
+ initially referred to the default namespace (the one with no name - just
+ like a Clint Eastwood character). Later on in the document the empty
+ prefix is changed to refer to a namespace called
+ <code>"http://postal.ie/spec-1.0"</code>.</p>
+
+ <p>Namespace prefixes are only relevant at the time when the XML document
+ is parsed and the DOM is built. Once we have the DOM completed we only need
+ a table that maps each node type to a namespace type, and another array of
+ all the names of the different namespaces. So what we want to end up with
+ is something like this:</p>
+
+ <p>
+<img src="dom_namespace1.gif" alt="dom_namespace1.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 3: Each namespace references in the DOM gets one entry</i>
+</b>
+</p>
+
+ <p>The namespace table has one entry for each namespace, nomatter how many
+ prefixes were used ro reference this namespace in the DOM. To build this
+ array we need a temporary data structure used by the DOM builder. This
+ structure is a hashtable - where the various prefixes are used for the
+ hash values. The contents of each entry in the table will be a small stack
+ where previous meanings of each prefix will be stored:</p>
+
+ <p>
+<img src="dom_namespace2.gif" alt="dom_namespace2.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 4: Temporary data structure used by the DOM builder</i>
+</b>
+</p>
+
+ <p>When the first node is encountered we define a new namespace
+ <code>"foo"</code> and assign this namespace type/index 1 (the default
+ namespace <code>""</code> has index 0). At the same time we use the prefix
+ <code>"A"</code> for a lookup in the hashtable. This gives us
+ an integer stack used for the prefix <code>"A"</code>. We push the namespace
+ type 1 on this stack. From now on, until <code>"A"</code> is pop'ed off this
+ stack, the prefix <code>"A"</code> will map to namespace type 1, which
+ represents the namespace URI <code>"foo"</code>.</p>
+
+ <p>We then encounter the next node with a new namespace definition with
+ the same namespace prefix, we create a new namespace <code>"bar"</code> and
+ we put that in the namespace table under type 2. Again we use the prefix
+ <code>"A"</code> as an entry into the namespace prefix table and we get the
+ same integer stack. We now push namespace type 2 on the stack, so that
+ namespace prefix <code>"A"</code> maps to namespace URI <code>"bar"</code>. When
+ we have traversed this node's children we need to pop the integer off the
+ stack, so when we're back at the first node the prefix <code>"A"</code> again
+ will point to namespace type 0, which maps to <code>"foo"</code>. To keep
+ track of what nodes had what namespace declarations, we use a namespace
+ declaration stack:</p>
+
+ <p>
+<img src="dom_namespace3.gif" alt="dom_namespace3.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 5: Namespace declaration stack</i>
+</b>
+</p>
+
+ <p>Every namespace declaration is pushed on the namespace declaration
+ stack. This stack holds the node index for where the namespace was
+ declared, and a reference to the prefix stack for this declaration.
+ The <code>endElement()</code> method of the DOMBuilder class will need to
+ remove namespace declaration for the node that is closed. This is done
+ by first checking the namespace declaration stack for any namespaces
+ declared by this node. If any declarations are found these are un-declared
+ by poping the namespace prefixes off the respective prefix stack(s), and
+ then poping the entry/entries for this node off the namespace declaration
+ stack.</p>
+
+ <p>The <code>endDocument()</code> method will build an array that contains
+ all namespaces used in the source XML document - <code>_nsNamesArray[]</code>
+ - which holds the URIs of all refered namespaces. This method also builds
+ an array that maps all DOM node types to namespace types. This two arrays
+ are accessed through two new methods in the DOM interface:</p>
+
+<blockquote class="source">
+<pre>
+ public String getNamespaceName(int node);
+ public int getNamespaceType(int node);
+</pre>
+</blockquote>
+
+ <a name="NSB">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Namespaces in the XSL stylesheet</h3>
+ <ul>
+ <li>
+<a href="#store-access">Storing and accessing namespace information</a>
+</li>
+ <li>
+<a href="#mapdom-stylesheet">Mapping DOM namespaces to stylesheet namespaces</a>
+</li>
+ <li>
+<a href="#wildcards">Wildcards and namespaces</a>
+</li>
+ </ul>
+ <a name="store-access">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Storing and accessing namespace information</h4>
+ <p>The SymbolTable class has three datastructures that are used to hold
+ namespace information:</p>
+
+ <ul>
+ <li>
+ First there is the <code>_namespaces[]</code> Hashtable that maps the names
+ of in-scope namespace to their respective prefixes. Each key in the
+ Hashtable object has a stack. A new prefix is pushed on the stack for
+ each new declaration of a namespace.
+ </li>
+ <li>
+ Then there is the <code>_prefixes[]</code> Hashtable. This has the reverse
+ function of the <code>_namespaces[]</code> Hashtable - it maps from
+ prefixes to namespaces.
+ </li>
+ <li>
+ There is also a hashtable that is used for implementing the
+ <code><xsl:namespace-alias></code> element. The keys in this
+ hashtable is taken from the <code>stylesheet-prefix</code> attribute of
+ this element, and the resulting prefix (from the <code>result-prefix</code>
+ attribute) is used as the value for each key.
+ </li>
+ </ul>
+
+ <p>The SymbolTable class offers 4 methods for accessing these data
+ structures:</p>
+
+<blockquote class="source">
+<pre>
+ public void pushNamespace(String prefix, String uri);
+ public void popNamespace(String prefix);
+ public String lookupPrefix(String uri);
+ public String lookupNamespace(String prefix);
+</pre>
+</blockquote>
+
+ <p>These methods are wrapped by two methods in the Parser class (a Parser
+ object alwas has a SymbolTable object):</p>
+<blockquote class="source">
+<pre>
+ // This method pushes all namespaces declared within a single element
+ public void pushNamespaces(ElementEx element);
+ // This method pops all namespaces declared within a single element
+ public void popNamespaces(ElementEx element);
+</pre>
+</blockquote>
+
+ <p>The translet class has, just like the DOM, a <code>namesArray[]</code>
+ structure for holding the expanded QNames of all accessed elements. The
+ compiled translet fills this array in its constructor. When the translet
+ has built the DOM (a DOMImpl object), it passes the DOM to the a DOM
+ adapter (a DOMAdapter object) together with the names array. The DOM
+ adapter then maps the translet's types to the DOM's types.</p>
+ <a name="mapdom-stylesheet">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Mapping DOM namespaces and stylesheet namespaces</h4>
+
+ <p>Each entry in the DOM's <code>_namesArray[]</code> is expanded to contain
+ the full QName, so that instead of containing <code>prefix:localname</code> it
+ will now contain <code>namespace-uri:localname</code>. In this way the expanded
+ QName in the translet will match the exanded QName in the DOM. This assures
+ matches on full QNames, but does not do much for <code>match="A:*"</code> type
+ XPath patterns. This is where our main challenge lies.</p>
+ <a name="wildcards">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Wildcards and namespaces</h4>
+
+ <p>The original implementation of the XSLTC runtime environment would
+ only allow matches on "<code>*</code>" and "<code>@*</code>" patterns. This was
+ achieved by mapping all elements that could not be mapped to a translet
+ type to 3 (DOM.ELEMENT type), and similarly all unknown attributes to
+ type 4 (DOM.ATTRIBUTE type). The main <code>switch()</code> statement in
+ <code>applyTemplates()</code> would then have a separate "<code>case()</code>"
+ for each of these. (Under each <code>case()</code> you might have to check
+ for the node's parents in case you were matching on "<code>path/*</code>"-type
+ patterns.) This figure shows how that was done:</p>
+
+ <a name="match_namespace1">â</a>
+ <p>
+<img src="match_namespace1.gif" alt="match_namespace1.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 6: Previous pattern matching</i>
+</b>
+</p>
+
+ <p>The "Node test" box here represents the "<code>switch()</code>" statement.
+ The "Node parent test" box represent each "<code>case:</code>" for that
+ <code>switch()</code> statement. There is one <code>case:</code> for each know
+ translet node type. For each node type we have to check for any parent
+ patterns - for instance, for the pattern "<code>/foo/bar/baz</code>", we will
+ get a match with <code>case "baz"</code>, and we have to check that the parent
+ node is "<code>bar</code>" and that the grandparent is "<code>foo</code>" before
+ we can say that we have a hit. The "Element parent test" is the test that
+ is done all DOM nodes that do not directly match any translet types. This
+ is the test for "<code>*</code>" or "<code>foo/*</code>". Similarly we have a
+ "<code>case:</code>" for match on attributes ("<code>@*</code>").</p>
+
+ <p>What we now want to achieve is to insert a check for patterns on the
+ format "<code>ns:*</code>", "<code>foo/ns:*</code>" or "<code>ns:@*</code>", which
+ this figure illustrates:</p>
+
+ <a name="match_namespace2">â</a>
+ <p>
+<img src="match_namespace2.gif" alt="match_namespace2.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 7: Pattern matching with namespace tests</i>
+</b>
+</p>
+
+
+ <p>Each node in the DOM needs a namespace type as well as the QName type.
+ With this type we can match wildcard rules to any specific namespace.
+ So after any checks have been done on the whole QName of a node (the type),
+ we can match on the namespace type of the node. The main dispatch
+ <code>switch()</code> in <code>applyTemplates()</code> must be changed from this:</p>
+
+ <blockquote class="source">
+<pre>
+ public void applyTemplates(DOM dom, NodeIterator iterator,
+ TransletOutputHandler handler) {
+
+ // Get next node from iterator
+ while ((node = iterator.next()) != END) {
+ // Get internal node type
+ final int type = DOM.getType(node);
+ switch(type) {
+ case DOM.ROOT: // Match on "/" pattern
+ handleRootNode();
+ break;
+ case DOM.TEXT: // Handle text nodes
+ handleText();
+ break;
+ case DOM.ELEMENT: // Match on "*" pattern
+ handleWildcardElement();
+ break;
+ case DOM.ATTRIBUTE: // Handle on "@*" pattern
+ handleWildcardElement();
+ break;
+ case nodeType1: // Handle 1st known element type
+ compiledCodeForType1();
+ break;
+ :
+ :
+ :
+ case nodeTypeN: // Handle nth known element type
+ compiledCodeForTypeN();
+ break;
+ default:
+ NodeIterator newIterator = DOM.getChildren(node);
+ applyTemplates(DOM, newIterator, handler);
+ break;
+ }
+ }
+ return;
+ }
+</pre>
+</blockquote>
+
+ <p>To something like this:</p>
+
+ <blockquote class="source">
+<pre>
+ public void applyTemplates(DOM dom, NodeIterator iterator,
+ TransletOutputHandler handler) {
+
+ // Get next node from iterator
+ while ((node = iterator.next()) != END) {
+
+ // First run check on node type
+ final int type = DOM.getType(node);
+ switch(type) {
+ case DOM.ROOT: // Match on "/" pattern
+ handleRootNode();
+ continue;
+ case DOM.TEXT: // Handle text nodes
+ handleText();
+ continue;
+ case DOM.ELEMENT: // Not handled here!!!
+ break;
+ case DOM.ATTRIBUTE: // Not handled here!!!
+ break;
+ case nodeType1: // Handle 1st known element type
+ if (compiledCodeForType1() == match) continue;
+ break;
+ :
+ :
+ :
+ case nodeTypeN: // Handle nth known element type
+ if (compiledCodeForTypeN() == match) continue;
+ break;
+ default:
+ break;
+ }
+
+ // Then run check on namespace type
+ final int namespace = DOM.getNamespace(type);
+ switch(namespace) {
+ case 0: // Handle nodes matching 1st known namespace
+ if (handleThisNamespace() == match) continue;
+ break;
+ case 1: // Handle nodes matching 2nd known namespace
+ if (handleOtherNamespace() == match) continue;
+ break;
+ }
+
+ // Finally check on element/attribute wildcard
+ if (type == DOM.ELEMENT) {
+ if (handleWildcardElement() == match)
+ continue;
+ else {
+ // The default action for elements
+ NodeIterator newIterator = DOM.getChildren(node);
+ applyTemplates(DOM, newIterator, handler);
+ }
+ }
+ else if (type == DOM.ATTRIBUTE) {
+ handleWildcardAttribute();
+ continue;
+ }
+ }
+ }
+</pre>
+</blockquote>
+
+ <p>First note that the default action (iterate on children) does not hold for
+ attributes, since attribute nodes do not have children. Then note that the way
+ the three levels of tests are ordered is consistent with the way patterns
+ should be prioritised:</p>
+
+ <ul>
+
+ <li>
+<b>Match on element/attribute types:</b>
+</li>
+ <ul>
+ <li>
+<code>match="/"</code> - match on the root node</li>
+ <li>
+<code>match="B"</code> - match on any B element</li>
+ <li>
+<code>match="A/B"</code> - match on B elements with A parent</li>
+ <li>
+<code>match="A | B"</code> - match on B or A element</li>
+ <li>
+<code>match="foo:B"</code> - match on B element within "foo" namespace</li>
+ </ul>
+ <li>
+<b>Match on namespace:</b>
+</li>
+ <ul>
+ <li>
+<code>match="foo:*"</code> - match on any element within "foo" namespace</li>
+ <li>
+<code>match="foo:@*"</code> - match on any attribute within "foo" namespace</li>
+ <li>
+<code>match="A/foo:*"</code> - match on any element within "foo" namespace with A parent</li>
+ <li>
+<code>match="A/foo:@*"</code> - match on any attribute within "foo" namespace with A parent</li>
+ </ul>
+
+ <li>
+<b>Match on wildcard:</b> </li>
+ <ul>
+ <li>
+<code>match="*"</code> - match on any element</li>
+ <li>
+<code>match="@*"</code> - match on any attribute</li>
+ <li>
+<code>match="A/*"</code> - match on any element with A parent</li>
+ <li>
+<code>match="A/@*"</code> - match on any attribute with A parent</li>
+ </ul>
+
+ </ul>
+
+ <a name="NSC">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Namespaces in the output document</h3>
+
+ <p>These are the categories of namespaces that end up in the output
+ document:</p>
+
+ <ul>
+ <li>
+ Namespaces used in literal elements/attributes in the stylesheet. These
+ namespaces should be declared <b>once</b> before use in the output
+ document. These elements are copied to the output document independent
+ of namespaces in the input XML document. However, the namespaces can
+ be declared using the same prefix, such that a namespace used by a
+ literal result element can overshadow a namespace from the DOM.
+ </li>
+ <li>
+ Namespaces from elements in the stylesheet that match elements in the
+ DOM. No namespaces from the DOM should be copied to the output document
+ unless they are actually referenced in the stylesheet. No namespaces
+ from the stylesheet should be copied to the output document unless the
+ elements in which they are references match elements in the DOM.
+ </li>
+ </ul>
+
+ <a name="output_namespaces1">â</a>
+ <p>
+<img src="output_namespaces1.gif" alt="output_namespaces1.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 8: Namespace declaration in the output document</i>
+</b>
+</p>
+
+ <p>Any literal element that ends up in the output document must declare all
+ namespaces that were declared in the <code><xsl:stylesheet<</code>
+ element. Exceptions are namespaces that are listed in this element's
+ <code>exclude-result-prefixes</code> or <code>extension-element-prefixes</code>
+ attributes. These namespaces should only be declared if they are referenced
+ in the output.</p>
+
+ <p>Literal elements should only declare namespaces when necessary. A
+ literal element should only declare a namespace in the case where it
+ references a namespace using prefix that is not in scope for this
+ namespace. The output handler will take care of this problem. All namespace
+ declarations are put in the output document using the output handler's
+ <code>declarenamespace()</code> method. This method will monitor all namespace
+ declarations and make sure that no unnecessary declarations are output.
+ The datastructures used for this are similar to those used to track
+ namespaces in the XSL stylesheet:</p>
+
+ <a name="output_namespaces2">â</a>
+ <p>
+<img src="output_namespaces2.gif" alt="output_namespaces2.gif" />
+</p>
+ <p>
+<b>
+<i>Figure 9: Handling Namespace declarations in the output document</i>
+</b>
+</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_namespace.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_native_api.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_native_api.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_native_api.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_native_api.html Fri May 16 16:11:33 2014
@@ -0,0 +1,555 @@
+<?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 Native API Documentation</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 Native API Documentation</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>Xsltc Native API<br />
+</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 Native API Documentation</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>XSLTC Compiler API</h3>
+
+ <p>XSLTC's native API is represented by the
+ <code>org.apache.xalan.xsltc.compiler.XSLTC</code> class. Any application
+ using XSLTC's native API should only have to access methods in this class
+ in order to compile a stylesheet (or a set or stylesheets) into one or
+ more Java classes. The <code>XSLTC</code> has an empty constructor. The
+ class needs to be initialized before each compilation by a call to:</p>
+<blockquote class="source">
+<pre>
+ public void init();
+</pre>
+</blockquote>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Compile methods</h4>
+ <p>There is a set of methods for compiling one or more stylesheets into a
+ set of Java classes. The stylesheet can be specified either as a
+ <code>URL</code>, <code>InputStream</code>, <code>InputSource</code> or
+ a <code>Vector</code> containing a set of <code>URL</code>s pointing to
+ stylesheets:</p>
+<blockquote class="source">
+<pre>
+ public boolean compile(URL url);
+ public boolean compile(URL url, String transletName);
+ public boolean compile(InputStream stream, String transletName);
+ public boolean compile(InputSource input, String transletName);
+ public boolean compile(Vector stylesheets);</pre>
+</blockquote>
+
+ <p>The default behaviour is to output the compiled Java class(es) to one or
+ more Java classes in the current working directory. The name of the main
+ translet class will be obtained from (in order of priority):</p>
+
+ <ul>
+ <li>that specified in the <code>compile()</code> method</li>
+ <li>if none is specified (if the parameter is 'null') the name will be
+ generated from the filename specified by the input URL/file/stream</li>
+ <li>the default translet name (set by <code>setClassName()</code>)</li>
+ <li>the built-in default class name <code>"GregorSamsa"</code>
+</li>
+ </ul>
+
+ <p>Additional Java classes will be generated for complex stylesheets. These
+ classes represent elements such as predicates, sort-records, etc. in the
+ stylesheet. Additional classes share the same root name as the main translet
+ class, with a suffix containing a '$'-sign and a sequence number. The result
+ of a single compilation of a complex stylesheet could be:</p>
+<blockquote class="source">
+<pre>
+ GregorSamsa.java
+ GregorSamsa$0.java
+ GregorSamsa$1.java
+ GregorSamsa$2.java
+ GregorSamsa$3.java</pre>
+</blockquote>
+
+ <p>It is not always desireable having these classes dumped to files in the
+ current working directory. There is one <code>compile()</code> method that
+ will return the Java class definitions as bytecodes. The bytecodes are
+ returned in a two-dimmensional <code>byte</code> array. Each byte-array
+ contains the bytecodes for one Java class:</p>
+<blockquote class="source">
+<pre>
+ public byte[][] compile(String name, InputSource input);</pre>
+</blockquote>
+
+ <p>Alternatively, one can first compile the stylesheet into one or more
+ Java class files, and then also retrieve the bytecodes from the compiler:</p>
+<blockquote class="source">
+<pre>
+ public byte[][] getBytecodes();</pre>
+</blockquote>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Output settings</h4>
+
+ <p>The default (root) name for the generated Java classes can be set and
+ retrieved by calls to these methods:</p>
+<blockquote class="source">
+<pre>
+ public void setClassName(String className);
+ public String getClassName();</pre>
+</blockquote>
+
+ <p>One can also specify a package to place the classes in:</p>
+<blockquote class="source">
+<pre>
+ public void setPackageName(String package);</pre>
+</blockquote>
+
+ <p>The generated classes can also be wrapped inside a single Java archive
+ (JAR-file):</p>
+<blockquote class="source">
+<pre>
+ public void setJarFileName(String jarFileName);
+ public String getJarFileName();</pre>
+</blockquote>
+
+ <p>The result file(s) need not be output in the current working directory.
+ Specify the directory to output to by calling:</p>
+<blockquote class="source">
+<pre>
+ public boolean setDestDirectory(String directory);</pre>
+</blockquote>
+
+
+
+ <a name="document-locator">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Input document locator interface</h4>
+
+ <p>XSLTC's compiler has an interface that a client application can implement
+ to provide XSL input from alternative sources. Implementing and using this
+ interface is necessary when the top-level stylesheet contains one or more
+ <code><xsl:include></code> and <code><xsl:import></code>
+ elements that reference stylesheets that cannot be read using standard
+ <code>File</code> or <code>URL</code> classes. The interface that a client
+ must implement is <code>org.apache.xalan.xsltc.compiler.SourceLoader</code>,
+ and its only method is:</p>
+<blockquote class="source">
+<pre>
+ public InputSource loadSource(String href, String context, XSLTC xsltc);</pre>
+</blockquote>
+
+ <p>The compiler class, <code>XSLTC</code>, has a method for specifying the
+ implementation of this interface:</p>
+<blockquote class="source">
+<pre>
+ public void setSourceLoader(SourceLoader loader);</pre>
+</blockquote>
+
+ <p>This interface shares the same purpose as the <code>URIResolver</code>
+ interface in the JAXP/TrAX API.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Debug settings</h4>
+
+ <p>XSLTC can be forced to output debug messages and stack dumps:</p>
+<blockquote class="source">
+<pre>
+ public void setDebug(boolean debug);
+ public boolean debug();</pre>
+</blockquote>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Error handling</h4>
+
+ <p>All <code>compile()</code> methods return 'true' if the compilation
+ succeeded. The compiler could in such case still generate warning messages.
+ These message could be retrieved a <code>Vector</code> of strings or
+ output directlry to stderr:</p>
+<blockquote class="source">
+<pre>
+ public Vector getWarnings();
+ public void printWarnings();</pre>
+</blockquote>
+
+ <p>All <code>compile()</code> methods will return 'false' if any serious
+ errors prevented the compiler from generating any Java classes. Error
+ messages are handled similar to warning messages:</p>
+<blockquote class="source">
+<pre>
+ public Vector getErrors();
+ public void printErrors();</pre>
+</blockquote>
+
+ <p>Note that warning messages are not returned/output by these two methods.
+ A client application should pass both warning and error messages
+ to its user.</p>
+
+
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>XSLTC Transform API</h3>
+
+ <p>The steps described in this chapter are covered in these sample
+ source code files:</p>
+
+ <ul>
+ <li>
+<code>org.apache.xalan.xsltc.cmdline.Transform</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledApplet/TransformApplet.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledBrazil/TransformHandler.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledEJB/TransformBean.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledEJB/TransformHome.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledEJB/TransformRemote.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledEJB/TransformServlet.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledServlet/CompileServlet.java</code>
+</li>
+ <li>
+<code>xml-xalan/java/samples/CompiledServlet/TransformServlet.java</code>
+</li>
+ </ul>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Transformation input handling</h4>
+
+ <p>The main input document must be parsed using a SAX handler. The main SAX
+ events (<code>ContentHandler</code>) and lexical declarations
+ (<code>LexicalHandler</code>) are handled by the internal DOM builder.
+ The classes that make up the internal DOM are:</p>
+<blockquote class="source">
+<pre>
+ org.apache.xalan.xsltc.DOM; - DOM interface
+ org.apache.xalan.xsltc.dom.DOMImpl; - DOM implementation
+ org.apache.xalan.xsltc.dom.DOMAdapter; - DOM-to-translet mapper
+ org.apache.xalan.xsltc.dom.MultiDOM; - DOM multiplexer
+ org.apache.xalan.xsltc.dom.DOMBuilder; - DOM builder interface</pre>
+</blockquote>
+
+ <p>The <code>DOMBuilder</code> interface is a wrapper for the standard SAX
+ <code>ContentHandler</code> and <code>LexicalHandler</code> interfaces.
+ The <code>DOMBuilder</code> contains both these interfaces, and it is
+ implemented by an inner class of the <code>DOMImpl</code> class. To build
+ the internal DOM, one has to go through these steps:</p>
+<blockquote class="source">
+<pre>
+ // Create a SAX parser and get the XMLReader object it uses
+ final SAXParserFactory factory = SAXParserFactory.newInstance();
+ try {
+ factory.setFeature(Constants.NAMESPACE_FEATURE,true);
+ }
+ catch (Exception e) {
+ factory.setNamespaceAware(true);
+ }
+ final SAXParser parser = factory.newSAXParser();
+ final XMLReader reader = parser.getXMLReader();
+
+ // Set the DOM's DOM builder as the XMLReader's SAX2 ContentHandler
+ final DOMImpl dom = new DOMImpl();
+ DOMBuilder builder = dom.getBuilder();
+ reader.setContentHandler(builder);
+
+ // Set the DOM's DOM builder as the XMLReader's SAX2 LexicalHandler
+ try {
+ String prop = "http://xml.org/sax/properties/lexical-handler";
+ reader.setProperty(prop, builder);
+ }
+ catch (SAXException e) {
+ // Can be quitely ignored...
+ }
+
+ // Pass the document URI or file-name to the DOM
+ dom.setDocumentURI(uri);
+ // Parse the input document to populate the DOM
+ reader.parse(uri);</pre>
+</blockquote>
+
+ <p>The input XML document may contain of reference a DTD. A DTD must be
+ processed by XSLTC in order to support the <code>id()</code> and
+ <code>unparsed-entity-uri()</code> functions.
+ The <code>org.apache.xalan.xsltc.dom.DTDMonitor</code> class can handle
+ DTD declarations and aggregate them for use by a translet. Create your
+ <code>DTDMonitor</code> instance by passing it a reference to your SAX
+ parser:</p>
+<blockquote class="source">
+<pre>
+ // Create a DTD monitor and pass it to the XMLReader object
+ final DTDMonitor dtd = new DTDMonitor(reader);</pre>
+</blockquote>
+
+ <p>This call ensures that an index is built for all <code>ID</code>
+ attributes described in the DTD:</p>
+<blockquote class="source">
+<pre>
+ // If there are any elements with ID attributes, build an index
+ dtd.buildIdIndex(dom, 0, _translet);</pre>
+</blockquote>
+
+ <p>And this call ensures that the translet is passed all unparsed entities
+ described in the DTD:</p>
+<blockquote class="source">
+<pre>
+ translet.setDTDMonitor(dtd);</pre>
+</blockquote>
+
+ <p>We'll tell you how to create the translet instance in the next section.</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>The translet instance</h4>
+
+ <p>All compiled translets inherit from the <code>AbstractTranslet</code>
+ class, so it is safe to cast your tranlet instance to that class:</p>
+<blockquote class="source">
+<pre>
+ Class transletClass = Class.forName(transletName);
+ AbstractTranslet translet = (AbstractTranslet)transletClass.newInstance();</pre>
+</blockquote>
+
+ <p>Note that the translet instance is not reusable, so you would
+ benefit from keeping the reference to the translet class.</p>
+
+ <p>Once you have your translet instance you can start playing around with
+ it. First you want to pass parameters to it:</p>
+<blockquote class="source">
+<pre>
+ // Pass global parameters
+ translet.addParameter("my-param", "my-value");</pre>
+</blockquote>
+
+ <p>You also want to remember to pass your DTD handler to the translet.
+ (See previous section.)</p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Preparing the output handler</h4>
+
+ <p>The compiled translet does not contain all the functionality needed to
+ format the output document. This is handled by our output post-processor
+ <code>org.apache.xalan.xsltc.runtime.TextOutput</code>. This class needs
+ to be instanciated with three parameters; a SAX <code>ContentHandler</code>,
+ a <code>LexicalHandler</code> and a string containing the desired output
+ encoding. The user should normally provide the two handlers, and the
+ output encoding can be obtained from a field in the translet:</p>
+<blockquote class="source">
+<pre>
+ // Get the output encoding (from any <xsl:output> element
+ String encoding = translet._encoding;
+
+ // Create a translet output handler and plug in the SAX handlers
+ TextOutput textOutput = new TextOutput(myContentHandler, myLexicalHandlere, encoding);</pre>
+</blockquote>
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Transformation</h4>
+
+ <p>With the internal DOM built, the DTD monitor in place, and the output
+ handler set up, we're ready to run the actual transformation:</p>
+<blockquote class="source">
+<pre>
+ // Transform and pass output to the translet output handler
+ translet.transform(dom, textOutput);</pre>
+</blockquote>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>The DOM cache interface</h4>
+
+ <p>Parsing the input document and building the internal DOM is a fairly
+ expensive operation, and it is often desireable to build a cache holding
+ frequently accessed internal DOMs. An application using XSLTC's native
+ API can accomplish this by implementing the
+ <code>org.apache.xalan.xsltc.DOMCache</code> interface. The application will
+ still have to call the translet's <code>transform()</code> method with a
+ DOM from the cache. But, the translet may have to load additional documents
+ if the original stylesheet contained calls to the <code>document()</code>
+ function. The translet can be instructed to read DOMs from a cache by
+ calling this method:</p>
+<blockquote class="source">
+<pre>
+ public void setDOMCache(DOMCache cache);
+ public DOMCache getDOMCache();</pre>
+</blockquote>
+
+
+
+
+
+<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_native_api.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_overview.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_overview.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_overview.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_overview.html Fri May 16 16:11:33 2014
@@ -0,0 +1,151 @@
+<?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 stylesheet compiler overview</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 stylesheet compiler overview</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>
+<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 stylesheet compiler overview</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Using the Command-Line Utility</h3>
+
+
+<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_overview.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_performance.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_performance.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_performance.html (added)
+++ xalan/java/branches/WebSite/xalan-j/xsltc/xsltc_performance.html Fri May 16 16:11:33 2014
@@ -0,0 +1,460 @@
+<?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 Performance</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 Performance</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>
+<a href="xsltc_trax_api.html">Xsltc TrAX API</a>
+</li>
+<li>Performance Hints<br />
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>XSLTC Performance</h2>
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Introduction</h3>
+
+ <p>
+<b>XSLT is not a programming language!</b> Just so you remember.
+ XSLT is a declarative language and can be used by you to describe
+ <b>what</b> you want put in your output document and
+ <b>what</b> you want this output to look like. It does not describe
+ <b>how</b> these tasks should be carried. That is the job of the XSLT
+ processor. This document is <b>not</b> a "<b>
+<i>programmer's guide to XSLT</i>
+</b>"
+ and should not be considered as such. All XSLT processors have their
+ properties and ways of handling XSL elements and XPath properties. This
+ document will give you some insight into the XSLTC internals, so that you
+ can channel your stylesheets through XSLTC's shortest and most efficient
+ code paths.</p>
+
+ <p>XSLTC's performance has always been one of its key selling points.
+ (I should probably find a better term here, since we're giving XSLTC away
+ for free.) But, there are some specific patterns and expressions that are
+ not handled much better than with other interpretive XSLT processors, and
+ this document is an attempt to pinpoint these and to outline alternatives.
+ </p>
+
+
+
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Contents</h3>
+ <ul>
+ <li>
+<a href="#pred">Avoid using predicates in '*' patterns</a>
+</li>
+ <li>
+<a href="#idkey">Avoid using id/key-patterns</a>
+</li>
+ <li>
+<a href="#union">Avoid union expressions where possible</a>
+</li>
+ <li>
+<a href="#sort">Sort stored node-sets once</a>
+</li>
+ <li>
+<a href="#cache">Cache input documents</a>
+</li>
+ <li>
+<a href="#trax">TrAX vs. native API</a>
+</li>
+ </ul>
+
+
+ <a name="pred">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Avoid using predicates in wildcard patterns</h3>
+
+ <p>XSLTC gains its speed from the simple dispatch loop in the translet's
+ <code>applyTemplates()</code> method. This method uses a simple
+ <code>switch()</code> statement to choose the desired template based on
+ the current node's node type (an integer). By adding a pattern with a
+ wildcard (no type) and a predicate, XSLTC is forced to evaluate the
+ predicate for every single node.</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="*[2]"></pre>
+</blockquote>
+
+ <p>The above pattern should be avoided by selecting the desired node when
+ using <code><xsl:apply-templates></code>. Use named templates or
+ modes to make sure you trigger the correct template:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="/">
+ <xsl:apply-templates select="bar"/>
+ </xsl:template>
+
+ <xsl:template match="*[2]"/>
+
+ <xsl:template match="*"/></pre>
+</blockquote>
+
+ <p>can be replaced by:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="/">
+ <xsl:apply-templates select="bar"/>
+ <xsl:apply-templates select="bar[2]" mode="second"/>
+ </xsl:template>
+
+ <xsl:template match="*" mode="second"/>
+
+ <xsl:template match="*"/></pre>
+</blockquote>
+
+ <p>This change will only improve performance if the stylesheet is fairly
+ large and has a good few templates (10 or more). Also note that the order
+ of the output is changed by this approach, so if the order is significant
+ you'll have to stick to the original stylesheet.</p>
+
+ <p>
+<b>Important note:</b> The type of pattern referred to as a
+ type-less pattern, as it does not match any specific node type. Such
+ patterns do in general degrade the performance of XSLTC. Type-less patterns
+ must be evaluated for every single node in the input document - causing a
+ general performance degradation.</p>
+
+
+
+ <a name="idkey">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Avoid using id/key-patterns</h3>
+
+ <p>Id and key patterns can be used to trigger a template if the current
+ node has a specific id or has a specific value in a key's index:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="id('some-value')"/>
+
+ <xsl:template match="key('key-name', 'some-value')"/></pre>
+</blockquote>
+
+ <p>Looking up a value/node-pair in an index does not require much processing
+ time at all. But, this is also a type-less pattern and can match any type
+ of node. This degrades XSLTC's performance, just like wildcard patterns
+ with predicates (see above paragraph).</p>
+
+
+
+ <a name="union">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Avoid union expressions where possible</h3>
+
+ <p>Union expressions provide an all-in-one-go easy way of applying templates
+ to sets of nodes:</p>
+<blockquote class="source">
+<pre>
+ <xsl:apply-templates select="foo|bar|baz"/></pre>
+</blockquote>
+
+ <p>The union iterator that is used to implement union expressions is
+ unfortunately not very efficient. If node order is not of importance, then
+ one can benefit from breaking the union up in several elements:</p>
+<blockquote class="source">
+<pre>
+ <xsl:apply-templates select="foo"/>
+ <xsl:apply-templates select="bar"/>
+ <xsl:apply-templates select="baz"/></pre>
+</blockquote>
+
+ <p>But, remeber that this will give you all <code><foo></code>
+ elements first, then all <code><bar></code> elements, and so on.
+ This is not always desirable. You may want to handle these elements in
+ the order in which they appear in the input document.</p>
+
+ <p>
+<b>Important note:</b> This does <b>not</b> apply to union patterns.
+ Using unions in patterns actually makes smaller and more efficient code,
+ as only one copy of the templete body has to be compiled. Use:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="foo|bar|baz"/></pre>
+</blockquote>
+
+ <p>instead of:</p>
+<blockquote class="source">
+<pre>
+ <xsl:template match="foo"/>
+ <xsl:template match="bar"/>
+ <xsl:template match="baz"/></pre>
+</blockquote>
+
+
+
+ <a name="sort">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Sort stored node-sets once</h3>
+
+ <p>This item is very obvious, but nevertheless easy to forget in some
+ complicated cases. If you put a result-tree fragment inside a variable, and
+ you want the nodes in a specific, sorted order, then sort the nodes as you
+ create the variable and not when you use it. Instead of:</p>
+<blockquote class="source">
+<pre>
+
+ <xsl:variable name="bars">
+ <xsl:copy-of select="//foo/bar"/>
+ </xsl:variable>
+
+ <xsl:template match="/">
+ <xsl:text>List of bar's in sorted order:&#xa;</xsl:text>
+ <xsl:for-each select="$bars-sorted">
+ <xsl:value-of select="@name"/>
+ <xsl:text>&#xa;</xsl:text>
+ </xsl:for-each>
+ </xsl:template></pre>
+</blockquote>
+
+ <p>A better way, and with most XSLT processors the only legal way, is to
+ sort the result tree when creating it:</p>
+<blockquote class="source">
+<pre>
+
+ <xsl:variable name="bars">
+ <xsl:for-each select="//foo/bar">
+ <xsl:sort select="@name"/>
+ <xsl:copy-of select="."/>
+ </xsl:for-each>
+ </xsl:variable>
+
+ <xsl:template match="/">
+ <xsl:text>List of bar's in sorted order:&#xa;</xsl:text>
+ <xsl:for-each select="$bars">
+ <xsl:value-of select="@name"/>
+ <xsl:text>&#xa;</xsl:text>
+ </xsl:for-each>
+ </xsl:template></pre>
+</blockquote>
+
+ <p>It is very common to sort node-sets returned by the id() and key()
+ functions. Instead of doing this sorting over and over again, one should
+ use a variable and store the node set in the desired sort order, and read
+ the node set from the variable whenever used.</p>
+
+
+
+ <a name="cache">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Cache the input document</h3>
+
+ <p>All XSLT processors use an internal DOM-like structure, and XSLTC is no
+ exception. The internal DOM is tailored for the XSLTC design and can be
+ navigated efficiently by the translet. Building the internal DOM is a
+ rather slow process, and does very many cases take more time than the
+ actual transformation. This is a general rule, and does not only apply to
+ XSLTC. It is advisable, and common in most large-scale XSLT-based
+ applications, to create a cache for the input documents. Not only does this
+ prevent CPU- and memory-intensive DOM creation, but it also prevents several
+ translets from having their own private copies of common input documents.
+ Both XSLTC's internal API and TrAX implementation provide ways of
+ implementing a decent input document cache:</p>
+
+ <ul>
+ <li>See <a href="#trax-cache">below</a> for a description of how
+ to do this using the TrAX interface.</li>
+
+ <li>The <a href="xsltc_native_api.html#document-locator">native API
+ documentation</a> contains a section on using the internal
+ <code>org.apache.xalan.xsltc.compiler.SourceLoader</code> interface.</li>
+ </ul>
+
+
+ <a name="trax">â</a>
+ <p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>TrAX vs. native API</h3>
+
+ <h5>TrAX performance benefits</h5>
+
+ <p>If XSLTC's two-step approach to XSLT processing suits your application
+ then there is no reason why you should not use the TrAX API. The API fits
+ very nicely in with XSLTC internals and processing model. In fact, you may
+ even benefit from using TrAX in cases where your stylesheet is compiled
+ into a large ammount of auxiliary classes. The most obvious benefit is that
+ the translet class and auxiliary classes are all bundled inside the
+ <code>Templates</code> object. Performance can also be improved due to the
+ fact that XSLTC chaches all auxiliary classes inside <code>Templates</code>
+ code, preventing the class loader from being invoked more than necessary.
+ This is just theory and no tests have been done, but you should see a
+ performance improvement when using XSLTC and TrAX in such cases.</p>
+
+
+
+ <h5>Treat Templates objects as compiled translets</h5>
+
+ <p>When using TrAX, the <code>Templates</code> object should be considered
+ the result of a compilation. With XSLTC this is the actual case - the
+ <code>Templates</code> object contains the translet Java class(es). With
+ other XSLT processors the <code>Templates</code> directly or indirectly
+ contains data-structures represent all or parts of the input stylesheet.
+ The bottom line is: Create your <code>Templates</code> object once, cache
+ and re-use it as often as possible.</p>
+
+
+
+ <a name="trax-cache">â</a>
+ <h5>Input document caching</h5>
+
+ <p>An extension to the TrAX API allows input documents to be cached. The
+ extensions is a sub-class to the TrAX <code>Source</code> class, which can
+ be used to wrap XSLTC's internal DOM structures. This is described in
+ detail in the <a href="xsltc_trax_api.html">XSLTC TrAX API reference</a>.
+ </p>
+
+ <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_performance.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xalan.apache.org
For additional commands, e-mail: commits-help@xalan.apache.org