function-available


This function is used to test whether a particular function is available for use. It can be used to test the availability both of standard system functions and of extension functions.

For example, the expression «function-available ('concat') » returns true .

Changes in 2.0

An optional second argument has been added, giving the arity of the required function.

In XSLT 2.0, except when running in forwards-compatibility mode or backwards -compatibility mode, it is a static error if an XPath expression contains a call on a function that is not available. Therefore, the way in which function-available() is used needs to change: instead of calling it using a normal runtime conditional instruction ( <xsl:choose> or <xsl:if > ), it should be called in a compile-time conditional expression, using the [xsl:] use-when attribute.

Signature

Argument

Data Type

Meaning

name

xs:string

The name of the function being tested . The string must take the form of a lexical QName .

arity (optional)

xs:integer

The arity (number of arguments) of the function being tested.

Result

xs:boolean

true if the named function is available to be called, false otherwise .

Effect

The first argument must take the form of a lexical QName : that is, an XML name, with an optional namespace prefix that corresponds to a namespace declaration that is in scope at the point in the stylesheet where the function-available() function is called.

If there is no prefix, or if the namespace URI is the standard function namespace http://www.w3.org/2003/11/xpath-functions (this URI will change when the specification gets to Candidate Recommendation status), the call tests whether there is a system function with the specified name. The system functions are those defined in the XPath and XSLT Recommendations; vendors are not allowed to supply additional functions in this namespace, nor are they allowed to omit any. So an XSLT processor that conforms to XSLT version 2.0 will return true if the name is one of the function names in this chapter (for example «current » or «regex- group » ) or any of the names of the functions described in Chapter 10 of XPath 2.0 Programmer's Reference . This means you can test whether a new XSLT 2.0 function is supported in your XSLT processor by writing, for example:

  use-when="function-available('regex-group')"  

If the QName includes a non-null namespace (other than the standard function namespace), the XSLT processor returns true if there is a stylesheet function or extension function available with the given name. In general, if function-available() returns false then you are safe in assuming that a call on the function would fail, and if it returns true , then there will be some way of calling the function successfully.

If the second argument to the function is supplied, then function-available() returns true only if there is a function available with the specified name and the specified number of arguments. When the second argument is omitted, the result is true if there is some function with the required name, regardless of the number of arguments.

There is no way of finding out at runtime what the data types of the arguments should be, which means that knowing a function is available is not enough to ensure that any given call on the function will be successful.

The functions that are considered to be available are those in the static context of the XPath expression containing the call on function-available() . If function-available() is evaluated from the use-when attribute, this includes core XPath and XSLT functions, constructor functions for built-in types, and extension functions. If function-available() is evaluated during stylesheet execution, it also includes stylesheet functions (defined using <xsl:function> ) and constructor functions for types imported from a schema.

Usage

There are two ways of using function-available() : it can be used to achieve backwards compatibility when using standard functions defined after version 1.0 of the specification, and it can be used to test for the presence of vendor or third-party extensions.

The ability to test for the existence of stylesheet functions is not particularly useful, though it could in principle be used in one stylesheet module to test whether a function defined in another module has been imported, before calling it.

Testing for the Existence of System-Defined Functions

The ability to test whether a particular system-defined function is available was not especially useful with version 1.0 of the specification. It was designed to come into its own when later versions of the specification were published. If you want to use a function that is newly defined in version 2.0, then you can test to see whether it is available with a particular XSLT processor, before using it. If it is not available, you can use <xsl:if> to avoid executing it. Provided that you enable forwards-compatible mode by setting the version attribute on the <xsl:stylesheet> element to "2.0" , an XSLT 1.0 processor will not object to the presence of an expression in your stylesheet that calls an unknown function, unless the expression is actually executed.

For example, the function current-date () becomes available in XPath 2.0. You can test for its existence by writing:

  <xsl:if test="function-available('current-date')>  

For a fuller example, see the end of this section.

In theory, you could test whether a function such as current-date() is available by calling « system-property ('xsl-version') » and testing whether the result is equal to «2.0 » . But the reality is that there will be processors that have implemented some of the XPath 2.0 functions but not yet all of them. A processor isn't supposed to return «2.0 » as the value of «system-property ('xsl:version') » unless it is a fully conformant XSLT 2.0 processor; but if it isn't a fully conformant processor, then you can't be sure whether it follows the rules. So it's better to use the finer-grained check offered by function-available() .

Testing for Vendor or Third-Party Extensions

The second way of using function-available() is to test for vendor or third-party extensions. If you know that a particular extension function is present in some implementations and not others, you can use the function-available() test to see whether it is present, and use the new use-when attribute to handle the situation when it isn't.

The use-when attribute is a late addition to XSLT 2.0. It provides a way of conditionally including or excluding parts of a stylesheet at compile time, based on a compile-time condition. There are more details of this feature on page 122 in Chapter 3. The compile-time condition is an XPath expression, restricted to operate with a very limited context, which means that it can only access information known at compile time. It cannot, for example, access a source document, or refer to variables . But the context does include the set of extension functions that are available. This is illustrated in the example that follows.

Example 1: Testing for xx:node-set() Extensions

The XSLT 2.0 working draft allows you to use a temporary tree (the value constructed when an <xsl:variable> element is not empty) in any context where a node can be used. This feature was not available in XSLT 1.0, which handled temporary trees as a distinct data type, known as a result tree fragment. Many vendors filled the gap by allowing a temporary tree to be converted to a node-set using an extension function (for example xt:node-set() or msxml:node-set() ). If you want to write a stylesheet that is as portable as possible, you need to write code that discovers which of these facilities is available.

The following stylesheet ( node-set-available.xsl ) contains a named template that takes a temporary tree as a parameter, and calls <xsl:apply-templates> to process its root node in a particular mode. When running with an XSLT 2.0 processor, it does this simply by passing the tree to <xsl:apply-templates> directly; in other cases, it tries to determine whether one of the proprietary node-set() extension functions is available, and uses that.

  <xsl:stylesheet   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   version="2.0">   <xsl:template name="process-tree-fragment"   xmlns:msxml="urn:schemas-microsoft-com:xslt"   xmlns:xt="http://www.jclark.com/xt"   xmlns:saxon6=" http://icl.com/saxon">   <xsl:param name="fragment" / >   <xsl:choose>   <xsl:when test="number(system-property('xsl:version')) &gt; 1,0">   <xsl:apply-templates mode="process-fragment"   select=" $fragment" / >   </xsl:when>   <xsl:otherwise use-when="system-property(' xsl:version') eq '1..0'">   <xsl:choose> <xsl:when 'test="function-avilable(    1    msxml:node-set ')'">   <xsl8apply-templates mode=    ;    "process"-fragment"   select="msxml:node-set($fragment)"/>   </xsl:when>   <xsl:when test="function-available('xt:node-set') ">   <xsl:apply-templates mode="process-fragment"   select="xt:node-set($fragment)"/>   </xsl:when>   <xsl:when test="function-available('saxon6:node-set') ">   <xsl:apply-templates mode="process-fragment"   selects= "saxon6:node-set($fragment)"/>   </xsl:when>   <xsl:otherwise>   <xsl:message terminate="yes">   Cannot convert result tree fragment to node-set   </xsl:message>   </xsl:otherwise>   </xsl:otherwise>   </xsl:choose>   </xsl:otherwise>   </xsl:choose>   </xsl:template>   </xsl:stylesheet>  

This named template can be called as follows, to process all the nodes in the result tree fragment.

  <xsl:call-template name="process-tree-fragment">   <xsl:with-param name="fragment" select="$supplied-fragment"/>   </xsl:call-template>  

The logic here is slightly tortuous. You need to look at it in two different ways: as an XSLT 1.0 stylesheet, and as a 2.0 stylesheet.

As a 1.0 stylesheet, the outer <xsl:choose> takes the <xsl:otherwise> branch, because the processor version is "1.0." The use-when attribute on the <xsl:otherwise> element is ignored: the XSLT 1.0 processor will be operating in forwards-compatible mode, because the stylesheet specifies «version= "2.0" » , and in forwards-compatible mode, unknown attributes on XSLT elements are ignored. The 1.0 processor then takes one of the branches of the inner <xsl:choose> , depending on which of the xx:node-set() extension functions is available.

As an XSLT 2.0 stylesheet, the outer <xsl:choose> takes the <xsl:when> branch. It completely ignores the <xsl:otherwise> branch, by virtue of the use-when condition. The use-when condition is necessary, because an XSLT 2.0 processor would otherwise report a static (compile time) error when it sees an XPath expression that calls an unknown function such as saxon6:node-set() , even though the function is not actually evaluated at runtime.

When this example is run with an XSLT 2.0 processor, it doesn't actually invoke the function-available() function-which arguably makes it a poor choice of example for this section. The next example attempts to remedy this.

Example 2: Testing Availability of a Java Method

In this example, we'll assume that the stylesheet is always going to run under a particular XSLT 2.0 processor, but that it might run under different Java VMs. We'll suppose the existence of an XSLT 2.0 processor that can run under both JDK 1.3 and JDK 1.4, and we'll suppose that we want to use the Java method «Charset.isAvailable() » in the java.nio.charset package, which is new in JDK 1.4. Under JDK 1.3, we'll behave as if the extension function returned false .

We achieve this by writing two versions of a variable declaration. Only one of them is compiled, based on the value of the use-when attribute.

  <xsl:variable name="charset-ok"   as="xs:boolean"   select="Charset:isAvailable('EUC-JP')"   xmlns:Charset="java:java.nio.charset.Charset"   use-when="function-available('Charset:isAvailable', 1)"/>   <xsl:variable name="charset-ok"   as="xs:boolean"   select="false() "   xmlns:Charset="java:java.nio.charset.Charset"   use-when="not(function-available('Charset:isAvailable', 1))"/>  

See Also

element-available() on page 542.




XSLT 2.0 Programmer's Reference
NetBeansв„ў IDE Field Guide: Developing Desktop, Web, Enterprise, and Mobile Applications (2nd Edition)
ISBN: 764569090
EAN: 2147483647
Year: 2003
Pages: 324

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net