docs/xalan/xalan-j/xsltc/xsl_include_design.html - xalan-site - Git at Google

 <?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: &lt;xsl:include&gt; / &lt;xsl:import&gt;</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">&lt;xsl:include&gt; / &lt;xsl:import&gt;</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>Include|Import design<br />
 </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>&lt;xsl:include&gt; / &lt;xsl:import&gt;</h2>

   <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h3>Contents</h3>
   <ul>
     <li>
 <a href="#functionality">Functionality</a>
 </li>
     <li>
 <a href="#implementation">Implementation</a>
 </li>
   </ul>


   <a name="functionality">‌</a>
   <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h3>Functionality</h3>

     <p>
 <code>&lt;xsl:include&gt;</code> allows you to include one stylesheet
     into another. The includ<b>ed</b> stylesheet's templates will have the same
     default priorities and import precedence as the includ<b>ing</b> stylesheet.
     <code>&lt;xsl:import&gt;</code> offers the same, but the import precedence
     of elements in an import<b>ed</b> stylesheet is always less than that of
     the import<b>ing</b> stylesheet.</p>


   <a name="implementation">‌</a>
   <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h3>Implementation</h3>

     <a name="include">‌</a>
     <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h4>&lt;xsl:include&gt;</h4>

     <p>This is the simplest case, so we will look at that first. The algorithm
     for including another stylesheet is roughly:</p>

     <ul>
       <li>get the including stylesheet from the XSLT parser</li>
       <li>get the value of the "href" attribute from the
         <code>&lt;xsl:include&gt;</code> element and check for circular
         includes/imports</li>
       <li>check if there is a defined <code>SourceLoader</code> set either
         through the native or the TrAX API</li>
       <li>get an <code>InputSource</code> for the document to include, either
         from the <code>SourceLoader</code> or from the document's URI</li>
       <li>parse the input document using the compiler's XSLT parser</li>
       <li>set the import precedence of the included stylesheet to the same as
         the import precedence of the including stylesheet</li>
       <li>get the top-level stylesheet from the XSLT parser</li>
       <li>move all variables, parameters, and top-level elements (include
         templates) from the included stylesheet to the top-level stylesheet
         (all elements will keep their import precedence even after being moved
         to the top-level stylesheet)</li>
     </ul>


     <a name="import">‌</a>
     <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h4>&lt;xsl:import&gt;</h4>

     <p>This is very similar to <code>&lt;xsl:include&gt;</code>, but import
     precedence has to be handled differently. Looking at the code you'll find
     this fragment:</p>
 <blockquote class="source">
 <pre>
     // Handle precedence for the including stylesheet
     final int currPrecedence = parser.getCurrentImportPrecedence();
     final int nextPrecedence = parser.getNextImportPrecedence();
     _imported.setImportPrecedence(currPrecedence);
     context.setImportPrecedence(nextPrecedence);</pre>
 </blockquote>

     <p>The important thing here is that the imported stylesheet has import
     precedence <b>less</b> than the importing stylesheet. So the imported
     stylesheet gets the current import precedence, while the current stylesheet
     gets the next available (unused) import precedence. The
     <code>Stylesheet</code> class has a method
     <code>setImportPrecedence()</code> that ensures that the import precedence
     is set not only for the stylesheet itself, but that it is also propagated
     down to any included/imported stylesheets:</p>
 <blockquote class="source">
 <pre>
     public void setImportPrecedence(final int precedence) {
 	// Set import precedence for this stylesheet
 	_importPrecedence = precedence;

 	// Set import precedence for all included stylesheets
 	final Enumeration elements = elements();
 	while (elements.hasMoreElements()) {
 	    SyntaxTreeNode child = (SyntaxTreeNode)elements.nextElement();
 	    if (child instanceof Include) {
 		Stylesheet included = ((Include)child).getIncludedStylesheet();
 		if (included != null) included.setImportPrecedence(precedence);
 	    }
 	}

 	// Set import precedence for the stylesheet that imported this one
 	if (_importedFrom != null) {
 	    if (_importedFrom.getImportPrecedence() &lt; precedence) {
 		final Parser parser = getParser();
 		final int nextPrecedence = parser.getNextImportPrecedence();
 		_importedFrom.setImportPrecedence(nextPrecedence);
 	    }
 	}
 	// Set import precedence for the stylesheet that included this one
 	else if (_includedFrom != null) {
 	    if (_includedFrom.getImportPrecedence() != precedence)
 		_includedFrom.setImportPrecedence(precedence);
 	}
     }</pre>
 </blockquote>

     <p>This method has been carefully cluttered together, and it works, and it
     should not be touched.</p>


     <a name="apply-imports">‌</a>
     <p align="right" size="2">
 <a href="#content">(top)</a>
 </p>
 <h4>&lt;xsl:apply-imports&gt;</h4>


 <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>
	<?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: <xsl:include> / <xsl:import></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"><xsl:include> / <xsl:import></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>Include\|Import design<br />
	</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><xsl:include> / <xsl:import></h2>

	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h3>Contents</h3>
	<ul>
	<li>
	<a href="#functionality">Functionality</a>
	</li>
	<li>
	<a href="#implementation">Implementation</a>
	</li>
	</ul>


	<a name="functionality">‌</a>
	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h3>Functionality</h3>

	<p>
	<code><xsl:include></code> allows you to include one stylesheet
	into another. The includ<b>ed</b> stylesheet's templates will have the same
	default priorities and import precedence as the includ<b>ing</b> stylesheet.
	<code><xsl:import></code> offers the same, but the import precedence
	of elements in an import<b>ed</b> stylesheet is always less than that of
	the import<b>ing</b> stylesheet.</p>



	<a name="implementation">‌</a>
	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h3>Implementation</h3>

	<a name="include">‌</a>
	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h4><xsl:include></h4>

	<p>This is the simplest case, so we will look at that first. The algorithm
	for including another stylesheet is roughly:</p>

	<ul>
	<li>get the including stylesheet from the XSLT parser</li>
	<li>get the value of the "href" attribute from the
	<code><xsl:include></code> element and check for circular
	includes/imports</li>
	<li>check if there is a defined <code>SourceLoader</code> set either
	through the native or the TrAX API</li>
	<li>get an <code>InputSource</code> for the document to include, either
	from the <code>SourceLoader</code> or from the document's URI</li>
	<li>parse the input document using the compiler's XSLT parser</li>
	<li>set the import precedence of the included stylesheet to the same as
	the import precedence of the including stylesheet</li>
	<li>get the top-level stylesheet from the XSLT parser</li>
	<li>move all variables, parameters, and top-level elements (include
	templates) from the included stylesheet to the top-level stylesheet
	(all elements will keep their import precedence even after being moved
	to the top-level stylesheet)</li>
	</ul>



	<a name="import">‌</a>
	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h4><xsl:import></h4>

	<p>This is very similar to <code><xsl:include></code>, but import
	precedence has to be handled differently. Looking at the code you'll find
	this fragment:</p>
	<blockquote class="source">
	<pre>
	// Handle precedence for the including stylesheet
	final int currPrecedence = parser.getCurrentImportPrecedence();
	final int nextPrecedence = parser.getNextImportPrecedence();
	_imported.setImportPrecedence(currPrecedence);
	context.setImportPrecedence(nextPrecedence);</pre>
	</blockquote>

	<p>The important thing here is that the imported stylesheet has import
	precedence <b>less</b> than the importing stylesheet. So the imported
	stylesheet gets the current import precedence, while the current stylesheet
	gets the next available (unused) import precedence. The
	<code>Stylesheet</code> class has a method
	<code>setImportPrecedence()</code> that ensures that the import precedence
	is set not only for the stylesheet itself, but that it is also propagated
	down to any included/imported stylesheets:</p>
	<blockquote class="source">
	<pre>
	public void setImportPrecedence(final int precedence) {
	// Set import precedence for this stylesheet
	_importPrecedence = precedence;

	// Set import precedence for all included stylesheets
	final Enumeration elements = elements();
	while (elements.hasMoreElements()) {
	SyntaxTreeNode child = (SyntaxTreeNode)elements.nextElement();
	if (child instanceof Include) {
	Stylesheet included = ((Include)child).getIncludedStylesheet();
	if (included != null) included.setImportPrecedence(precedence);
	}
	}

	// Set import precedence for the stylesheet that imported this one
	if (_importedFrom != null) {
	if (_importedFrom.getImportPrecedence() < precedence) {
	final Parser parser = getParser();
	final int nextPrecedence = parser.getNextImportPrecedence();
	_importedFrom.setImportPrecedence(nextPrecedence);
	}
	}
	// Set import precedence for the stylesheet that included this one
	else if (_includedFrom != null) {
	if (_includedFrom.getImportPrecedence() != precedence)
	_includedFrom.setImportPrecedence(precedence);
	}
	}</pre>
	</blockquote>

	<p>This method has been carefully cluttered together, and it works, and it
	should not be touched.</p>



	<a name="apply-imports">‌</a>
	<p align="right" size="2">
	<a href="#content">(top)</a>
	</p>
	<h4><xsl:apply-imports></h4>





	<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>