




































|
|
|
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. |
|
|
Where it makes sense, we are placing the new Xalan
extensions in the org.apache.xalan.lib.Extensions class and we
have defined a namespace for this class:
http://xml.apache.org/xalan
If you are calling Xalan-Java-supplied extensions, we
recommend that you define this namespace in your stylesheet
element, 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 Redirect extension (org.apache.xalan.xslt.extensions.Redirect)
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.
Each of these elements includes 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.
|
|
|
Implemented in org.apache.xalan.lib.Extensions,
nodeset
(result-tree-fragment) casts a result tree
fragment into a node-set.
 |
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. |
|
|
|
Implemented in org.apache.xalan.lib.Extensions, distinct
(node-set) returns a node-set containing nodes with distinct
string values. If more than one node in the node-set contains
the same text node value, distinct only returns the first of
these nodes that it
finds. |
|
|
Implemented in org.apache.xalan.lib.Extensions,
hasSameNodes(node-set1,
node-set2) returns true if both node-set1 and
node-set2 contain exactly the same set of
nodes. |
|
|
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). | |
|
|
|
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.
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. |
|
|
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. |
|
|
To be done. Provides efficient grouping of items
with a common value. |
|
|
To be done. Returns a string that represents the
Schema or DTD type. |
|
|
To be done. Takes a string as input, and returns a
long value representing the
date. |
|
|
To be done. Takes a date string, and formats it
according to a
specification. |
|
|
To be done. Performs a grep function and returns the
substring. |
|
|
To be done. Tokenizes a string, treats each token as
a DOM Text node, and executes the
sub-template. |
| |