



































|
 |
Unless otherwise
specified, the Xalan-Java extensions library discussed in this
section refers to the Xalan-Java Interpretive processor. See Extensions for XSLTC for more
information. |
|
|
Extension
elements and functions provide a powerful mechanism for extending
and simplifying what you can do with an XLST processor like Xalan.
With input and contributions from the XML open-source developer
community, we are working on placing the most useful extensions in
an extensions library distributed with Xalan-Java. If you have
ideas and/or contributions you would like to make, please email us
at the Xalan Development
Mailing List.
|
|
|
Xalan-Java
supports the EXSLT initiative to
provide a set of standard extension functions and elements to XSLT
users. Xalan-Java includes implementations for the following EXSLT
extension modules:
All EXSLT
extensions use namespaces specified in the EXSLT specification. For
example, to use the EXSLT math functions, specify a namespace URI
as follows:
xmlns:math="http://exslt.org/math"
Anyone who
would like to help by implementating other EXSLT extensions is more
than welcome. Please email us at the Xalan Development Mailing
List.
|
|
|
The Xalan
extensions are implemented in one of the classes under
org.apache.xalan.lib. The main extension class is
org.apache.xalan.lib.Extensions. Some extension functions (e.g.
intersection, difference, etc.) used to be in this class are now
moved to the corresponding EXSLT modules. All Xalan
extensions use namespace URIs starting with:
http://xml.apache.org/xalan
If you are
calling Xalan-Java-supplied extensions, we recommend that you
define the corresponding namespace in your stylesheet, and call the
extension using the namespace prefix that you have associated with
that namespace. That way, if we later reorganize how the
Xalan-Java-supplied extensions are stored, you won't have to modify
your stylesheet.
For an
example that uses this namespace, see Example with the nodeset
extension function.
|
|
|
A standard
XSL transformation involves an XSL stylesheet, an XML source tree,
and the transformation result tree. The transformation sends the
entire result to a single
org.apache.trax.Result object.
The
namespace for the
Redirect extension is:
http://xml.apache.org/xalan/redirect
It
supplies three extension elements that you can use to redirect
portions of your transformation output to multiple files:
<open>, <write>, and <close>. If you use the
<write> element alone, the extension opens a file, writes to
it, and closes the file immediately. If you want explicit control
over the opening and closing of files, use <write> in
conjunction with the <open> and <close>
elements.
The
<open> and <write> elements include a file attribute
and/or a select attribute to designate the output file. The file
attribute takes a string, so you can use it to directly specify the
output file name. The select attribute takes an XPath expression,
so you can use it to dynamically generate the output file name. If
you include both attributes, the Redirect extension first evaluates
the select attribute, and falls back to the file attribute if the
select attribute expression does not return a valid file
name.
The
<open> and <write> elements also support an append
attribute. If the append attribute is set to true or yes, then the
result is appended to the output file.
|
|
|
Implemented in
org.apache.xalan.lib.Extensions,
nodeset
(result-tree-fragment) casts a result tree fragment
into a node-set.
To use the
nodeset extension, you can either use the nodeset function in the
namespace xmlns:xalan="http://xml.apache.org"
or the EXSLT extension
function node-set in the namespace
xmlns:common="http://exslt.org/common" .
 |
When you bind a
variable to a template, rather than to the value generated by a
select expression, the data type of the variable is result tree
fragment. For more information, see Result
Tree Fragments. |
|
|
|
org.apache.xalan.lib.NodeInfo provides extension elements that
you can use to get information about the location of nodes in the
source document:
|
|
Implemented in
org.apache.xalan.lib.NodeInfo, systemId() returns the
system ID for the current node, and systemId(node-set) returns
the system ID of the first node in the node-set.
|
|
|
To be done. Implemented in
org.apache.xalan.lib.NodeInfo, publicId() will return the
public ID for the current node, and publicId(node-set) will
return the public ID of the first node in the node-set.
|
|
|
Implemented in
org.apache.xalan.lib.NodeInfo, lineNumber() returns the
line number in the source document for the current node, and
lineNumber(node-set)
returns the line number in the source document for the first node
in the node-set.
 |
This function returns
-1 if the line number is not known (for example, the source is a
DOM Document). |
|
|
|
Implemented in
org.apache.xalan.lib.NodeInfo, columnNumber() returns the
column number in the source document for the current node, and
columnNumber(node-set)
returns the column number in the source document for the first node
in the node-set.
 |
This function returns
-1 if the column number is not known (for example, the source is a
DOM Document). |
|
|
|
|
The
namespace for the SQL extension is:
http://xml.apache.org/xalan/sql
The SQL
extension provides extension functions for connecting to a JDBC
data source, executing a query, and working incrementally through a
"streamable" result set. Streaming (reuse of a single row node to
traverse the result set) is the default mode of operation. If you
want unlimited access to the entire result set, you can cache the
query result set (1 row node for each row in the result
set).
If you
use streaming mode (the default), you can only access row elements
one at a time moving forward through the result set. The use of
XPath expressions in your stylesheet, for example, that attempt to
return nodes from the result set in any other manner may produce
unpredictable results.
 |
Many features of the
SQL library, including support for connection pools, parameterized
queries, caching, and added support for extracting connection
information and query parameters from XML source documents exist
thanks to John Gentilin (johnglinux@eyecatching.com), who has also
added a number of SQL library
samples. |
org.apache.xalan.lib.sql.XConnection provides a number of
extension functions that you can use in your stylesheet.
- new() --
Use one of the XConnection constructors to connect to a data
source, and return an XConnection object. You can use one of the
constructors creates a connection pool from which stylesheets can
obtain connections to a datasource. To support connection pools,
SQL library includes a ConnectionPool interface and a
implementation: DefaultConnectionPool. You can also provide your
own ConnectionPool implementation.
- query()
-- Use the XConnection object query() method to return a
"streamable" result set in the form of a row-set node. Work your
way through the row-set one row at a time. The same row element is
used over and over again, so you can begin "transforming" the
row-set before the entire result set has been returned.
- pquery(),
addParameter(), addParameterFromElement(), clearParameters() -- Use
the XConnection pquery() method in conjunction with these other
methods to set up and execute parameterized queries.
- Use
enableStreamingMode() to use a single row node to "stream" through
the result set, and disableStreamingMode() to cache the query
result set.
- close()
-- Use the XConnection object close() method to terminate the
connection.
The
query() and pquery() extension functions return a Document node
that contains (as needed) an array of column-header elements, a
single row element that is used repeatedly, and an array of col
elements. Each column-header element (one per column in the
row-set) contains an attribute (ColumnAttribute) for each of the
column descriptors in the ResultSetMetaData object. Each col
element contains a text node with a textual representation of the
value for that column in the current row.
|
|
|
Implemented in
org.apache.xalan.lib.PipeDocument,
the pipeDocument extension element pipes an XML document through a
series of one or more transformations. The output of each
transformation is piped to the next transformation. The final
transofrmation creates a target file.
The
namespace for the pipeDocument extension is:
http://xml.apache.org/xalan/PipeDocument
Suppose,
for example,you have a stylesheet that is processing a "book"
document with elements designating the documents to be transformed.
This primary stylesheet generates a table of contents for the book.
For each source document it uses a pipeDocument extension element
to pipe the document through a series of one or more
transformations.
|
|
|
Implemented in
org.apache.xalan.lib.Extensions,
evaluate
(xpath-expression) function returns the result of
evaluating the xpath-expression in the current XPath expression
context (automatically passed in by the extension
mechanism).
Use the
evaluation extension function when the value of the expression is
not known until run time.
 |
Although you can still
use the evaluate extension function in the main Extensions class,
the preferred solution is to use the same function in the EXSLT
dynamic package. This will make your stylesheet more portable
across XSLT processors that support EXSLT
extensions. |
|
|
|
Implemented in
org.apache.xalan.lib.Extensions,
tokenize (tokenize-string,
delimiters)
or
tokenize
(tokenize-string) function returns a node-set
containing one text node for each token in the
tokenize-string.
The
delimiters determine which characters are used to divide the
tokenize-string into individual tokens. If you do not include the
delimiters argument, the function uses tab (	), linefeed
(
), return (
), and space ( ) as
delimiters. if tokenize-string is an empty string or contains only
delimiters, the result is an empty node-set.
 |
Although you can still
use the tokenize extension function in the main Extensions class,
the preferred solution is to use the same function in the EXSLT
strings package. This will make your stylesheet more portable
across XSLT processors that support EXSLT
extensions. |
|
|
|