Converting Wrapped Java Objects
Saxon allows an extension function to return an arbitrary Java object. This will then be wrapped as an XPath item, so that it can be held in a variable and passed subsequently as an argument to another extension function. This second extension function will see the original Java object minus its wrapper, provided it is declared to expect the appropriate Java class.
A wrapped Java object always holds a non-null object value. The Java value null converts to the XPath empty sequence.
A wrapped Java object may be converted to another data type as follows.
It is converted to a string by calling its
It is atomized by calling its
It is converted to a number by converting it first to a string, and then applying the XPath number() conversion.
The effective boolean value of a wrapped Java object (like that of a node) is always true.
The type of a wrapped Java object may be declared in a variable declaration or function signature using a type name whose
namespace URI is "http://saxon.sf.net/java-type", and whose local name is the fully qualified name of the Java class, with any "$" signs
replaced by hyphens. For example, the
sql:connection extension function returns a value of type
Note that a call on a constructor function (using prefix:new()) always returns a wrapped Java object, regardless
of the class. But a call on a static method, instance-level method, or field will return a wrapped Java object only
if the result is a class that Saxon does not specifically recognize as one that it can convert to a regular
XPath value. Such classes include
List and so on.
In Saxon 9.4 and earlier releases, a wrapped Java object was considered to be an atomic value (in the XDM type
hierarchy, the type representing
java.lang.Object was a peer of primitive types such as
xs:boolean. In Saxon 9.5, this changed so that wrapped objects are a fourth
item(), at the same level in the type hierarchy as nodes, atomic values, and function items.
Atomizing a wrapped Java object now produces an instance of
xs:string containing the result of the
toString() method applied to the underlying object.