Saxon Documentation

Full Contents

About Saxon

Changes in this Release

Notices

Using XSLT 2.0

Using XQuery

Handling Source Documents

XML Schema Processing

XPath API for Java

Saxon on .NET

Extensibility
	Introduction
	Writing extension functions in Java
»	Converting Arguments to Java Extension Functions
	Converting the Result of a Java Extension Function
	Writing extension functions for .NET
	Converting Arguments to .NET Extension Functions
	Converting the Result of a .NET Extension Function
	Writing XSLT extension instructions
	Customizing Serialization
	Implementing a collating sequence
	Localizing numbers and dates
	Adding an output encoding
	Writing a URI Resolver for Input Files
	Writing a URI Resolver for Output Files

Saxon Extensions

Sample Saxon Applications

The Saxon SQL Extension

XSLT Elements

XPath 2.0 Expression Syntax

Function Library

Standards Conformance

Converting Atomic Values and Sequences

The following conversions are supported between the static type of the supplied value of the argument, and the declared Java class of the argument. The mappings are given in order of preference; a class that appears earlier in the list has smaller "conversion distance" than one appearing later. These priorities are used to decide which method to call when the class has several methods of the same name. Simple classes (such as boolean) are acceptable wherever the corresponding wrapper class (Boolean) is allowed. Class names shown in italics are Saxon-specific classes.

If the static type of the supplied value allows a sequence of more than one item, then Saxon looks for a method that expects a SequenceIterator, a SequenceValue, a Collection or an array in that order. (The first two classes are Saxon-specific). In all these cases except the last the item type of the supplied value plays no role.

Nodes in the supplied sequence are atomized only if the Java method requires an atomic type such as an integer or string. If the method requires a Collection, then the contents of the sequence will be supplied as is. The objects in the List will typically be Saxon Item objects. (Saxon does not yet recognize the generic types in JDK 1.5, which allow the item type of a collection to be declared). If atomization is required, you can force it by calling the data() function.

If the required type is an array, Saxon will attempt to create an array of the required type. This will not always succeed, for example if the array has type X[] where X is an interface rather than a concrete class. If it is an array of items or nodes, the nodes in the supplied sequence will be inserted into the array directly; if it is an array of a type such as integer or double, the sequence will first be atomized.

If the supplied value is a singleton (a sequence of one item) then the type of that item is decisive. If it is a sequence of length zero or more than one, then the general rules for a sequence are applied, and the types of the items within the sequence are irrelevant.

If the supplied value contains more than item and only a single item is expected, an error is reported. There is no implicit extraction of the first value (as happened in earlier releases).

If the supplied value is an empty sequence, then if the required type is a collection or array type, an empty collection or array is passed; otherwise a null value is passed. However, if the required type is a primitive Java type such as int or bool, then passing an empty sequence will result in a type error.

Supplied type	Required type
boolean	BooleanValue, Boolean
dateTime	DateTimeValue, Date
date	DateValue, Date
decimal	DecimalValue, BigDecimal, Double, Float
double	DoubleValue, Double
duration	DurationValue
float	FloatValue, Float, Double
integer, long, int	IntegerValue, BigInteger, BigDecimal, Long, Integer, Double, Float
short	IntegerValue, BigInteger, BigDecimal, Long, Integer, Short, Double, Float
byte	IntegerValue, BigInteger, BigDecimal, Long, Integer, Short, Byte, Double, Float
string	StringValue, (String, CharSequence)
anyURI	AnyURIValue, java.net.URI, java.net.URL, (String, CharSequence)
QName	QNameValue, javax.xml.namespace.QName
node	SingletonNode, NodeList, (Element, Attr, Document, DocumentFragment, Comment, Text, ProcessingInstruction, CharacterData), Node, Boolean, Byte, Character, Double, Float, Integer, Long, Short, (String, CharSequence), Object
sequence	SequenceIterator, SequenceValue, List, NodeList, NodeInfo, Node, (String, CharSequence), Boolean, Byte, Character, Double, Float, Integer, Long, Short, Object

Saxon tries to select the appropriate method based on the static type of the arguments to the function call. If there are several candidate methods, and there is insufficient information available to decide which is most appropriate, an error is reported. The remedy is to cast the arguments to a more specific type.

A required type of one of the Java primitive types such as int or bool is treated as equivalent to the corresponding boxed type (Integer or Boolean), except that with the boxed types, an empty sequence can be supplied in the function call and is translated to a Java null value as the actual argument.