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 &amp; 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 &amp; 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>&lt;TITLE&gt;</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>&lt;TITLE&gt;</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>
+    &lt;element xmlns:prefix="http://some.site/spec"&gt;....&lt;/element&gt;
+</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>
+    &lt;?xml version="1.0"?&gt;
+    
+    &lt;employees xmlns:postal="http://postal.ie/spec-1.0"
+               xmlns:email="http://www.w3c.org/some-spec-3.2"&gt;
+        &lt;employee&gt;
+            &lt;name&gt;Bob Worker&lt;/name&gt;
+            &lt;postal:address&gt;
+                &lt;postal:street&gt;Nassau Street&lt;/postal:street&gt;
+                &lt;postal:city&gt;Dublin 3&lt;/postal:city&gt;
+                &lt;postal:country&gt;Ireland&lt;/postal:country&gt;
+            &lt;/postal:address&gt;
+            &lt;email:address&gt;bob.worker@hisjob.ie&lt;/email:address&gt;
+        &lt;/employee&gt;
+    &lt;/employees&gt;
+</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>&lt;name&gt;</code> and <code>&lt;employee&gt;</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>&lt;employees&gt;</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>
+    &lt;?xml version="1.0"?&gt;
+    
+    &lt;employees xmlns:email="http://www.w3c.org/some-spec-3.2"&gt;
+        &lt;employee&gt;
+            &lt;name&gt;Bob Worker&lt;/name&gt;
+            &lt;address xmlns="http://postal.ie/spec-1.0"&gt;
+                &lt;street&gt;Nassau Street&lt;/street&gt;
+                &lt;city&gt;Dublin 3&lt;/city&gt;
+                &lt;country&gt;Ireland&lt;/country&gt;
+            &lt;/address&gt;
+            &lt;email:address&gt;bob.worker@hisjob.ie&lt;/email:address&gt;
+        &lt;/employee&gt;
+    &lt;/employees&gt;
+</pre>
+</blockquote>
+
+    <p>The default namespace is redefined for the <code>&lt;address&gt;</code> node
+    and its children, so there is no need to specify the street as
+    <code>&lt;postal:street&gt;</code> - just plain <code>&lt;street&gt;</code> is
+    sufficient. Note that this also applies to the <code>&lt;address&gt;</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 &amp; 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>&lt;bob&gt;</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>&lt;xsl:namespace-alias&gt;</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>&lt;xsl:stylesheet&lt;</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 &amp; 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>&lt;xsl:include&gt;</code> and <code>&lt;xsl:import&gt;</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 &lt;xsl:output&gt; 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 &amp; 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 &amp; 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>
+    &lt;xsl:template match="*[2]"&gt;</pre>
+</blockquote>
+
+    <p>The above pattern should be avoided by selecting the desired node when
+    using <code>&lt;xsl:apply-templates&gt;</code>. Use named templates or
+    modes to make sure you trigger the correct template:</p>
+<blockquote class="source">
+<pre>
+    &lt;xsl:template match="/"&gt;
+      &lt;xsl:apply-templates select="bar"/&gt;
+    &lt;/xsl:template&gt;
+
+    &lt;xsl:template match="*[2]"/&gt;
+
+    &lt;xsl:template match="*"/&gt;</pre>
+</blockquote>
+
+    <p>can be replaced by:</p>
+<blockquote class="source">
+<pre>
+    &lt;xsl:template match="/"&gt;
+      &lt;xsl:apply-templates select="bar"/&gt;
+      &lt;xsl:apply-templates select="bar[2]" mode="second"/&gt;
+    &lt;/xsl:template&gt;
+
+    &lt;xsl:template match="*" mode="second"/&gt;
+
+    &lt;xsl:template match="*"/&gt;</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>
+    &lt;xsl:template match="id('some-value')"/&gt;
+
+    &lt;xsl:template match="key('key-name', 'some-value')"/&gt;</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>
+    &lt;xsl:apply-templates select="foo|bar|baz"/&gt;</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>
+    &lt;xsl:apply-templates select="foo"/&gt;
+    &lt;xsl:apply-templates select="bar"/&gt;
+    &lt;xsl:apply-templates select="baz"/&gt;</pre>
+</blockquote>
+
+    <p>But, remeber that this will give you all <code>&lt;foo&gt;</code>
+    elements first, then all <code>&lt;bar&gt;</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>
+    &lt;xsl:template match="foo|bar|baz"/&gt;</pre>
+</blockquote>
+
+    <p>instead of:</p>
+<blockquote class="source">
+<pre>
+    &lt;xsl:template match="foo"/&gt;
+    &lt;xsl:template match="bar"/&gt;
+    &lt;xsl:template match="baz"/&gt;</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>
+
+    &lt;xsl:variable name="bars"&gt;
+      &lt;xsl:copy-of select="//foo/bar"/&gt;
+    &lt;/xsl:variable&gt;
+
+    &lt;xsl:template match="/"&gt;
+      &lt;xsl:text&gt;List of bar's in sorted order:&amp;#xa;&lt;/xsl:text&gt;
+      &lt;xsl:for-each select="$bars-sorted"&gt;
+        &lt;xsl:value-of select="@name"/&gt;
+        &lt;xsl:text&gt;&amp;#xa;&lt;/xsl:text&gt;
+      &lt;/xsl:for-each&gt;
+    &lt;/xsl:template&gt;</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>
+
+    &lt;xsl:variable name="bars"&gt;
+      &lt;xsl:for-each select="//foo/bar"&gt;
+        &lt;xsl:sort select="@name"/&gt;
+        &lt;xsl:copy-of select="."/&gt;
+      &lt;/xsl:for-each&gt;
+    &lt;/xsl:variable&gt;
+
+    &lt;xsl:template match="/"&gt;
+      &lt;xsl:text&gt;List of bar's in sorted order:&amp;#xa;&lt;/xsl:text&gt;
+      &lt;xsl:for-each select="$bars"&gt;
+        &lt;xsl:value-of select="@name"/&gt;
+        &lt;xsl:text&gt;&amp;#xa;&lt;/xsl:text&gt;
+      &lt;/xsl:for-each&gt;
+    &lt;/xsl:template&gt;</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