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]
