mkwan 2002/11/04 11:15:25
Modified: java/xdocs/sources xalan-jlocal.xml xalan-jsite.xml
java/xdocs/sources/xalan commandline.xml extensionslib.xml
Added: java/xdocs/sources/xalan commandline_xsltc.xml
extensions_xsltc.xml
Log:
Added two new documents: Extensions for XSLTC and XSLTC options in the
Process command line. Added the "XSLTC Exts" item to the main panel.
Revision Changes Path
1.23 +2 -0 xml-xalan/java/xdocs/sources/xalan-jlocal.xml
Index: xalan-jlocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jlocal.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- xalan-jlocal.xml 11 Jun 2002 15:09:33 -0000 1.22
+++ xalan-jlocal.xml 4 Nov 2002 19:15:25 -0000 1.23
@@ -80,11 +80,13 @@
<separator/>
<document id="extensions" label="Extensions"
source="xalan/extensions.xml"/>
<document id="extensionslib" label="Extensions Library"
source="xalan/extensionslib.xml"/>
+ <document id="extensions_xsltc" label="XSLTC Exts"
source="xalan/extensions_xsltc.xml"/>
<separator/>
<document id="readme" label="Release Notes" source="xalan/readme.xml"/>
<hidden id="history" source="xalan/history.xml"/>
<hidden id="xsltc_constraints" source="xalan/xsltc_constraints.xml"/>
<hidden id="xsltc_history" source="xalan/xsltc_history.xml"/>
+ <hidden id="commandline_xsltc" source="xalan/commandline_xsltc.xml"/>
<separator/>
<external href="design/design2_0_0.html" label="Xalan 2 Design"/>
<external href="xsltc/index.html" label="XSLTC Design"/>
1.48 +2 -0 xml-xalan/java/xdocs/sources/xalan-jsite.xml
Index: xalan-jsite.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jsite.xml,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- xalan-jsite.xml 31 Oct 2002 15:05:32 -0000 1.47
+++ xalan-jsite.xml 4 Nov 2002 19:15:25 -0000 1.48
@@ -83,12 +83,14 @@
<separator/>
<document id="extensions" label="Extensions"
source="xalan/extensions.xml"/>
<document id="extensionslib" label="Extensions Library"
source="xalan/extensionslib.xml"/>
+ <document id="extensions_xsltc" label="XSLTC Exts"
source="xalan/extensions_xsltc.xml"/>
<separator/>
<document id="readme" label="Release Notes" source="xalan/readme.xml"/>
<document id="builds" label="Xalan-Java Builds" source="xalan/builds.xml"/>
<hidden id="history" source="xalan/history.xml"/>
<hidden id="xsltc_constraints" source="xalan/xsltc_constraints.xml"/>
<hidden id="xsltc_history" source="xalan/xsltc_history.xml"/>
+ <hidden id="commandline_xsltc" source="xalan/commandline_xsltc.xml"/>
<separator/>
<external href="design/design2_0_0.html" label="Xalan 2 Design"/>
<external href="xsltc/index.html" label="XSLTC Design"/>
1.21 +46 -23 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- commandline.xml 31 Jan 2002 15:55:22 -0000 1.20
+++ commandline.xml 4 Nov 2002 19:15:25 -0000 1.21
@@ -60,6 +60,9 @@
<s1 title="Command-Line Utility">
+<ul>
+<li><link idref="commandline_xsltc">Command line options for
XSLTC</link></li>
+</ul>
<s2 title="Using the Command-Line Utility">
<p>To perform a transformation, you can call &xslt4j; from the command
line (or script),
@@ -70,8 +73,9 @@
<ol>
<li>Download &xslt4j;.<br/><br/></li>
<li><link idref="getstarted" anchor="classpath">Set the Java
classpath</link> to include xalan.jar, xml-apis.jar, and
- &xml4j-jar; -- or another conformant XML Parser -- see <link
idref="usagepatterns" anchor="plug">Plugging in
- the Transformer and XML parser</link>).<br/><br/></li>
+ &xml4j-jar; -- or another conformant XML Parser -- (see <link
idref="usagepatterns" anchor="plug">Plugging in
+ the Transformer and XML parser</link>). Also include xsltc.jar in the
classpath if you want to use
+ the XSLTC related options.<br/><br/></li>
<li>Call java and the Process class with the appropriate flags and
arguments (described below). The following command line, for example,
includes the -IN, -XSL,
and -OUT flags with their accompanying arguments -- the XML source
document, the XSL
@@ -79,35 +83,54 @@
<code>java org.apache.xalan.xslt.Process -IN foo.xml -XSL foo.xsl -OUT
foo.out</code>
</li></ol>
<p>The command line utility can take the following flags and arguments
(the flags are case insensitive):</p>
- <source>-IN inputXMLURL
+ <source>
+ Common Options
+
+-XSLTC (use XSLTC for transformation)
+-IN inputXMLURL
-XSL XSLTransformationURL
-OUT outputFileName
-V (Version info)
--QC (Quiet Pattern Conflicts Warnings)
+-EDUMP [optional filename] (Do stackdump on error.)
+-XML (Use XML formatter and add XML header.)
+-TEXT (Use simple Text formatter.)
+-HTML (Use HTML formatter.)
+-PARAM name expression (Set a stylesheet parameter)
+-MEDIA mediaType (use media attribute to find stylesheet associated with a
document)
+-FLAVOR flavorName (Explicitly use s2s=SAX or d2d=DOM to do transform)
+-DIAG (Print overall milliseconds transform took)
+-URIRESOLVER full class name (URIResolver to be used to resolve URIs)
+-ENTITYRESOLVER full class name (EntityResolver to be used to resolve
entities)
+-CONTENTHANDLER full class name (ContentHandler to be used to serialize
output)
+
+ Options for the Xalan interpreter
+-QC (Quiet Pattern Conflicts Warnings)
-TT (Trace the templates as they are being called)
--TG (Trace each result tree generation event)
+-TG (Trace each generation event)
-TS (Trace each selection event)
-TTC (Trace the template children as they are being processed)
--EDUMP [optional]FileName (Do stackdump on error)
--XML (Use XML formatter and add XML header)
--TEXT (Use simple Text formatter)
--HTML (Use HTML formatter)
--PARAM name value (Set a stylesheet parameter)
--DIAG (Print number of milliseconds transform operation took)
--FLAVOR flavorName (Transform with SAX for s2s or DOM for d2d)
--URIRESOLVER fullClassName (Use a custom URIResolver)
--ENTITYRESOLVER fullClassName (Use a custom EntityResolver)
--CONTENTHANDLER fullClassName (Use a custom ContentHandler)
--INCREMENTAL (Request incremental transform by setting
- http://xml.apache.org/xalan/features/incremental to true)
--NOOPTIMIZE (Request no optizimation of stylesheet processing
- by setting http://xml.apache.org/xalan/features/optimize to
- false)
--RL recursionLimit (Set numeric limit on depht of stylesheet
- recursion)
--L (Turn on source_location attribute)
+-TCLASS (TraceListener class for trace extensions)
+-L (use line numbers for source document)
+-INCREMENTAL (request incremental DTM construction by setting
+ http://xml.apache.org/xalan/features/incremental to true)
+-NOOPTIMIMIZE (request no stylesheet optimization proccessing by setting
+ http://xml.apache.org/xalan/features/optimize to false)
+-RL recursionlimit (assert numeric limit on stylesheet recursion depth)
+
+ Options for the Xalan compiler (XSLTC)
+
+-XO [optional transletName] (assign the name to the generated translet)
+-XD destinationDirectory (specify a destination directory for translet)
+-XJ jarfile (package translet classes into a jar file of name
<jarfile>)
+-XP package (specify a package name prefix for all generated translet
classes)
+-XN (enable template inlining)
+-XX (turn on additional debugging message output)
+-XT (use translet to transform if possible)
</source>
+ <p>Use <code>-XSLTC</code> if you want to transform with XSLTC. Please
refer to
+ <link idref="commandline_xsltc">this document</link> for a detailed
description on
+ the XSLTC related options.</p>
<p>Use <code>-IN</code> to specify the XML source document.</p>
<p>Use <code>-XSL</code> to specify the XSL stylesheet file.</p>
<p>Use <code>-TEXT</code> if you want the output to include only
element values (not element tags with element names and
1.27 +1 -0 xml-xalan/java/xdocs/sources/xalan/extensionslib.xml
Index: extensionslib.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/extensionslib.xml,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- extensionslib.xml 28 Oct 2002 20:46:31 -0000 1.26
+++ extensionslib.xml 4 Nov 2002 19:15:25 -0000 1.27
@@ -68,6 +68,7 @@
<li><link anchor="pipedocument">PipeDocument</link></li>
<li><link anchor="evaluate">evaluate</link></li>
<li><link anchor="tokenize">tokenize</link></li>
+<li><link idref="extensions_xsltc">Extensions for XSLTC</link></li>
<li>Examples: <link anchor="ex-redirect">Redirect</link>, <link
anchor="ex-nodeset">nodeset</link>, <link anchor="ex-sql">SQL
library</link></li>
</ul><anchor name="intro"/>
<s2 title= "Introduction">
1.1 xml-xalan/java/xdocs/sources/xalan/commandline_xsltc.xml
Index: commandline_xsltc.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Command line options for XSLTC">
<ul>
<li><link anchor="options">Options</link></li>
<li><link anchor="examples">Examples</link></li>
<li><link anchor="faq">Simple FAQs</link></li>
<li><link anchor="trax">Using the new options from TrAX</link></li>
</ul>
<anchor name="options"/>
<s2 title="Options">
<p>The <code>org.apache.xalan.xslt.Process</code> command line now supports
XSLTC for transformation. You can use
the new <code>-XSLTC</code> option to enable the XSLTC support. The xsltc.jar
file must be on your CLASSPATH
in order to use the <code>-XSLTC</code> option.</p>
<p>The following existing options can be used with -XSLTC:</p>
<p><code>-IN, -XSL, -OUT, -V, -EDUMP, -XML, -TEXT, -HTML, -PARAM, <br/>
-MEDIA, -FLAVOR, -DIAG, -URIRESOLVER, -ENTITYRESOLVER,<br/>
-CONTENTHANDLER</code></p>
<p>The following existing options do not work with <code>-XSLTC</code>. If
any of them is used with <code>-XSLTC</code>,
a message is printed and the option is ignored.</p>
<p><code>-QC, -TT, -TG, -TS, -TTC, -TCLASS, -L, -INCREMENTAL, <br/>
-NOOPTIMIMIZE, -RL</code></p>
<p>We also have a new set of options for <code>-XSLTC</code>. They are all
two letter options. The first
letter is X and the second letter is the same as the corresponding option in
the XSLTC command line
<code>org.apache.xalan.xsltc.cmdline.Compile</code>.</p>
<p>These new options can only be used with <code>-XSLTC</code>. If any of
them is used with the Xalan
interpreter, a message is printed and the option is ignored.</p>
<p>Here is the list of the new options:</p>
<ul>
<li><code>-XO [optional translet_name]</code><br/>
Assign the name to the generated translet. If the translet_name is omitted,
the translet is
generated using the default name (same as the xsl).</li>
<li><code>-XD destination_directory</code><br/>
Specify a destination directory for translet. The generated translet
classes will be put
under the specified destination directory.</li>
<li><code>-XJ jar_name</code><br/>
Package translet classes into a jar file of name <jar_name></li>
<li><code>-XP package_name</code><br/>
Specify a package name prefix for all generated translet classes</li>
<li><code>-XN</code><br/>
Enables template inlining</li>
<li><code>-XX</code><br/>
Turns on additional debugging message output</li>
<li><code>-XT</code><br/>
Use translet to transform if possible</li>
</ul>
</s2>
<anchor name="examples"/>
<s2 title="Examples">
<p>You can just add the <code>-XSLTC</code> option to your existing option
list so that it will do the same
thing as before, but using XSLTC.</p>
<p>Here is a simple example on how to use XSLTC:</p>
<p>> <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl
-xsltc</code></p>
<p>XSLTC compiles the stylesheet on the fly and uses the bytecode in memory
to transform the input xml.
No translet class is generated in this simple usage pattern.</p>
<p>If you want to generate translet classes from the stylesheet, you can use
the <code>-XO</code> option:</p>
<p>> <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl
-xsltc -xo</code></p>
<p>This example still uses the stylesheet for transformation, but it also
generates the
translet class "test.class".</p>
<p>You can use the <code>-XJ, -XP</code> or <code>-XD</code> options to
further customize the translet generation behavior. Translets
will be generated if any of the options <code>-XO, -XJ</code> or
<code>-XT</code> is used.</p>
<p>> <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl
-xsltc -xo newTranslet -xd temp -xp org.apache.test -xj translets.jar</code></p>
<p>The above command line uses the xsl for transformation. It also generates
translet classes in
the name of <code>newTranslet</code>, using a package prefix of
<code>org.apache.test</code>, and packages the translets
into the jar file <code>translets.jar</code> under the <code>temp</code>
directory.</p>
<p>All of the examples above use the stylesheet to do the transformation. If
the translets are
already generated, you can use the <code>-XT</code> option to specify that
you want to use the existing translets for transformation.
The <code>-XT</code> option has a makefile like feature in that it will
compare the timestamps of the translet
and the stylesheet. If the translet is newer, it is used for the
transformation, otherwise the stylesheet is
used and the translet is regenerated.</p>
<p>The translet is loaded from the specified destination directory or the
current directory, using
the specified translet name or the xsl base name, depending on whether the
<code>-XD</code> or
<code>-XO</code> option is used. The options <code>-XO, -XD, -XP</code> and
<code>-XJ</code>
can be used with the <code>-XT</code> option to tell XSLTC how to find the
translet classes. The translets
are directly read in as bytecode. You do not need to add the translet
directory or the jar file to your
classpath.</p>
<p>Example:</p>
<p>> <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl
-xsltc -xt -xj translets.jar -xd temp</code></p>
<p>This command line will search for the translet <code>test.class</code>
inside the jar file <code>temp/translets.jar</code>. If it is
found and newer than test.xsl, it is used for the transformation; otherwise
the xsl is used and the
translet is generated and packaged in the same jar.</p>
<p>Here is how the makefile feature for the <code>-XT</code> option works:</p>
<ol>
<li>If the xsl does not exist, use the translet</li>
<li>If the translet does not exist, use the xsl and generate a new
translet</li>
<li>If both exist and the translet is newer, use the translet for
transformation</li>
<li>If both exist and the xsl is newer, use the xsl for transformation and
regenerate the translet</li>
</ol>
</s2>
<anchor name="faq"/>
<s2 title="Simple FAQs">
<p><em>Q:</em> If I use the <code>-XT</code> option, how can I tell if it is
using the translet or the stylesheet for transformation?</p>
<p><em>A:</em> Use the <code>-XX</code> option. When XSLTC uses the translet
for transformation, you will see a debug
message like "Tranform using translet ..." or "Tranform using translet ...
from jar file ...".</p>
<p><em>Q:</em> I want to use a translet for transformation, and I don't have
the stylesheet.</p>
<p><em>A:</em> Suppose the translet class is
<code>c:\translets\myTranslet.class</code>, you can use the following command
line:</p>
<p>> <code>java org.apache.xalan.xslt.Process -in test.xml -xsltc -xt -xo
myTranslet -xd c:\translets</code></p>
<p>If you use <code>-XT</code> option, the <code>-XSL</code> option can be
omitted. You have to specify the translet name
using the <code>-XO</code> option because there is no default translet name
in this situation.</p>
<p><em>Q:</em> I only want to compile the stylesheet. I don't want to do a
transformation.</p>
<p><em>A:</em> TrAX has no notion of compiling a stylesheet. However, you can
achieve the same effect by
running a dummy transformation and tell XSLTC to save the translet class.
Example:</p>
<p>> <code>java org.apache.xalan.xslt.Process -xsl test.xsl -xo</code></p>
<p>This command runs a transformation on an empty input and generates the
translet <code>test.class</code>.</p>
</s2>
<anchor name="trax"/>
<s2 title="Using the new options from TrAX">
<p>If you use the TrAX interface for XSLTC, you could not tell it to use
translets before. It always compiled
the xsl on the fly and used the bytecode im memory for transformation. Now
you can use some of
the new attributes in XSLTC's <code>TransformerFactoryImpl</code> class to
customize the translet behaviors from TrAX.</p>
<p>Here is the list of attributes in
<code>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</code> and their
corresponding Process command line options:</p>
<table>
<tr>
<td><em>Attributes</em></td>
<td><em>Process command line options</em></td>
<td><em>Default values</em></td>
</tr>
<tr>
<td>translet-name</td>
<td>-XO</td>
<td>GregorSamsa</td>
</tr>
<tr>
<td>destination-directory</td>
<td>-XD</td>
<td>null</td>
</tr>
<tr>
<td>package-name</td>
<td>-XP</td>
<td>null</td>
</tr>
<tr>
<td>jar-name</td>
<td>-XJ</td>
<td>null</td>
</tr>
<tr>
<td>generate-translet</td>
<td></td>
<td>false</td>
</tr>
<tr>
<td>auto-translet</td>
<td>-XT</td>
<td>false</td>
</tr>
<tr>
<td>enable-inlining</td>
<td>-XN</td>
<td>false</td>
</tr>
<tr>
<td>debug</td>
<td>-XX</td>
<td>false</td>
</tr>
</table>
<p>You can set the attributes using the TrAX interface
<code>TransformerFactory.setAttribute(String name, Object value)</code>.
The four attributes <code>translet-name, destination-directory, package-name
and jar-name</code> are transient.
They only apply to the next <code>newTemplates()</code> or
<code>newTransformer()</code> call. Their values are reset to
the default after the call.</p>
<p>The following example shows you how to do the same thing from TrAX for the
question 2 in the FAQ.</p>
<source>
// set the system property javax.xml.transform.TransformerFactory in order to
use XSLTC
String key = "javax.xml.transform.TransformerFactory";
String value = "org.apache.xalan.xsltc.trax.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);
TransformerFactory tfactory = null;
try {
tfactory = TransformerFactory.newInstance();
}
catch (TransformerFactoryConfigurationError pfe) { pfe.printStackTrace(); }
// set the translet name
tfactory.setAttribute("translet-name", "myTranslet");
// set the destination directory
tfactory.setAttribute("destination-directory", "c:\\translets");
// use the translet for transformation if possible
tfactory.setAttribute("auto-translet", "true");
// You can create a Templates object from an empty Source if the translet is
specified.
Templates templates = tfactory.newTemplates(new StreamSource());
</source>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/extensions_xsltc.xml
Index: extensions_xsltc.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Extensions for XSLTC">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="constraints">Constraints</link></li>
<li><link anchor="java_ext">Java extension</link></li>
<li><link anchor="exslt_ext">EXSLT extensions</link></li>
<li><link anchor="nodeset_ext">nodeset</link></li>
<li><link anchor="redirect_ext">output/redirect</link></li>
</ul>
<anchor name="intro"/>
<s2 title="Introduction">
<p>XSLTC supports the use of extension functions implemented in external
Java classes. It also
supports the <link anchor="nodeset_ext">nodeset</link>, <link
anchor="redirect_ext">output/redirect</link>
and <link anchor="exslt_ext">EXSLT</link> extension functions. Extension
support in XSLTC is
still under development. It is currently not as complete as the extension
support in the
interpretive Xalan. There are constraints in some areas.</p>
</s2>
<anchor name="constraints"/>
<s2 title="Constraints">
<p>In addition to the constraints listed below for each particular
extension, extension support
in XSLTC also has the following limitations:</p>
<ol>
<li><link idref="extensions" anchor="ext-elements">Extension element</link>
is not supported.
The extension element mechanism is closely related to the internal
implementation of the XSLT processor.
The current extension element mechansim is designed for the interpretive
Xalan. It does not work with XSLTC.</li>
<li>The <link idref="extensions" anchor="supported-lang">xalan:component
and xalan:script</link> extension elements are not supported at the moment.
This has
the implication that you cannot use scripting languages (e.g. javascript)
with XSLTC.</li>
<li><link idref="extensionslib" anchor="sql">The SQL extension</link> is
not supported in XSLTC at the moment.</li>
</ol>
</s2>
<anchor name="java_ext"/>
<s2 title="Java extension">
<p>Java extension is supported in XSLTC. Constructors, static and instance
methods are all supported.
You can use any of the <link idref="extensions"
anchor="ext-func-calls">three namespace formats</link>
(Java, package and class) in your stylesheet.
</p>
<p>The official namespace for the Java extension is
<code>http://xml.apache.org/xalan/java</code>. The old XSLTC Java namespace
<code>http://xml.apache.org/xalan/xsltc/java</code> and the old Xalan
namespace <code>http://xml.apache.org/xslt/java</code>
are also supported for backward compatibility.</p>
<p>All usage syntax for Xalan also applies to XSLTC with only one
exception: XSLTC does not support the notion of default object
in <link idref="extensions" anchor="ext-func-calls">class format
namespace</link>.
When using instance methods, you should always specify the class instance
as the first argument
to the extension function.</p>
<p>The following example shows you how to call constructors, static, and
nonstatic functions,
using different namespace formats:</p>
<source><xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:date="http://xml.apache.org/xalan/java/java.util.Date"
xmlns:java_lang="http://xml.apache.org/xalan/java/java.lang"
exclude-result-prefixes="date java_lang">
<!--
* test: construction of Date object using a parameter calculated
* by a static call to the java.lang.Math object. Then call
* a non-static method (getTime()) on the newly created Date
* object. Demonstrates calling constructors, static functions
* (Math.max) and non-static functions (getTime()).
*
* Output:
* <?xml version="1.0" encoding="UTF-8"?>
* Date of object: Sat Nov 30 17:32:41 EST 2002
* Time of object: 1038695561000
*
-->
<xsl:template match="/">
<!-- create Date object with calculated parameter -->
<xsl:variable name="dateObject"
select="date:new(
java_lang:Math.max(1027695561000,1038695561000)
)"/>
Date of object: <xsl:value-of select="$dateObject"/>
Time of object: <xsl:value-of
select="date:getTime($dateObject)"/>
</xsl:template>
</xsl:stylesheet>
</source>
<note>Always use the abbreviated syntax for Java extension, because the
xalan:component/xalan:script
constructs are not supported in XSLTC.</note>
</s2>
<anchor name="exslt_ext"/>
<s2 title="EXSLT extensions">
<p>The following EXSLT extension modules are supported in XSLTC:</p>
<ul>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltCommon.html">EXSLT common
functions</jump></li>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltMath.html">EXSLT math
functions</jump></li>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltSets.html">EXSLT set
functions</jump></li>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltDatetime.html">EXSLT
date-and-time functions</jump></li>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltStrings.html">EXSLT
string functions</jump></li>
</ul>
<p>The functions in the <jump
href="apidocs/org/apache/xalan/lib/ExsltDynamic.html">dynamic</jump> module
(e.g. evaluate) are not supported because of the XSLTC design limitation.
Work is currently underway on <jump
href="http://www.exslt.org/func/elements/function/index.html";>user
defined EXSLT functions (with the function and result elements)</jump>.</p>
<p>The <code>nodeset</code> and <code>objectType</code> extension functions
in the <jump href="apidocs/org/apache/xalan/lib/ExsltCommon.html">common</jump>
module are implemented natively in XSLTC. For all other EXSLT extension
functions,
XSLTC uses the same implementation as Xalan. The implementation classes are
under <code>org.apache.xalan.lib</code>.
Depending on the packaging, these classes can be in a separate jar file
(e.g. xalan.jar) from
the XSLTC classes. In this case you need to add the jar file containing the
EXSLT classes to your
classpath in order to use EXSLT extensions in XSLTC.</p>
</s2>
<anchor name="nodeset_ext"/>
<s2 title="nodeset">
<p>XSLTC also supports the nodeset() extension function for transforming an
RTF (result
tree fragment) into a node set.</p>
<p>The nodeset extension can be used as an XSLTC extension function in
the namespace
<code>http://xml.apache.org/xalan/xsltc</code>, a Xalan extension
function in the namespace
<code>http://xml.apache.org/xalan</code>, an EXSLT extension function in
the namespace
<code>http://exslt.org/common</code> or as a standard XPATH function.
When it is used as
an EXSLT extension function, you need to refer to the nodeset extension
function as
<code>node-set</code>.</p>
<p>The following exmaple shows you how to use the nodeset extension
function in different namespaces:</p>
<source><xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xsltc-extension="http://xml.apache.org/xalan/xsltc"
xmlns:xalan="http://xml.apache.org/xalan"
xmlns:exslt="http://exslt.org/common"
version="1.0">
<xsl:template match="/">
<xsl:variable name="rtf">
<docelem>
<elem1>elem1</elem1>
<elem2>elem2</elem2>
</docelem>
</xsl:variable>
<!-- Use nodeset as an XSLTC extension function -->
<xsl:value-of
select="xsltc-extension:nodeset($rtf)/docelem/elem1"/>
<!-- Use nodeset as a Xalan extension function -->
<xsl:value-of select="xalan:nodeset($rtf)/docelem/elem1"/>
<!-- Use nodeset as an EXSLT extension function -->
<xsl:value-of
select="exslt:node-set($rtf)/docelem/elem1"/>
<!-- Use nodeset as standard function -->
<xsl:value-of select="nodeset($rtf)/docelem/elem1"/>
</xsl:template>
</xsl:stylesheet>
</source><br/>
<note>The preferred solution is to use the EXSLT node-set function so that it
can work
with multiple XSLT processors.</note>
</s2>
<anchor name="redirect_ext"/>
<s2 title="output/redirect">
<p>XSLTC supports the output extension element for redirecting the output
to one
or more files. The output extension element is also aliased to the write
extension element
in the namespace <code>http://xml.apache.org/xalan/redirect</code>.
Therefore you can use
it in the same way as the <link idref="extensionslib"
anchor="redirect">redirect</link> extension in Xalan.</p>
<p>You can use the file and append attributes with the output/redirect
extension. The value of the file
attribute is an attribute value template. If the value of the append
attribute is true or yes, the
output is appended to the file rather than overwriting the file.</p>
<p>The following example shows you how to use the output/redirect
extension:</p>
<source> <xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xsltc="http://xml.apache.org/xalan/xsltc"
xmlns:redirect="http://xml.apache.org/xalan/redirect"
xsl:version="1.0">
<xsl:template match="/">
<xsl:text>This goes to standard output</xsl:text>
<xsltc:output file="blob.xml">
<xsl:text>This ends up in the file 'blob.xml'</xsl:text>
</xsltc:output>
<redirect:write file="blob.xml" append="true">
<xsl:text>This is appended to the file
'blob.xml'</xsl:text>
</redirect:write>
</xsl:template>
</xsl:stylesheet></source>
</s2>
</s1>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
