net.sf.saxon.functions
Class Extensions

java.lang.Object
  net.sf.saxon.functions.Extensions

public class Extensions
extends Object

This class implements functions that are supplied as standard with SAXON, but which are not defined in the XSLT or XPath specifications.

To invoke these functions, use a function call of the form prefix:name() where name is the method name, and prefix maps to a URI such as http://saxon.sf.net/net.sf.saxon.functions.Extensions (only the part of the URI after the last slash is important).

Method Summary

static SequenceIterator	after(XPathContext context, SequenceIterator ns1, SequenceIterator ns2) Find all the nodes in ns1 that are after the first node in ns2.
static byte[]	base64BinaryToOctets(Base64BinaryValue in) Convert a base64Binary value to a sequence of integers representing the octets contained in the value
static String	base64BinaryToString(XPathContext context, Base64BinaryValue in, String encoding) Convert a base64Binary value to a String, assuming a particular encoding
static XQueryExpression	compileQuery(XPathContext context, String query) Compile a string containing a source query transformations
static Templates	compileStylesheet(XPathContext context, DocumentInfo doc) Compile a document containing a stylesheet module into a stylesheet that can be used to perform transformations
static BigDecimal	decimalDivide(BigDecimal arg1, BigDecimal arg2, int scale) Perform decimal division to a user-specified precision
static boolean	deepEqual(XPathContext context, SequenceIterator arg1, SequenceIterator arg2, String collation, String flags) Perform a parameterized deep-equals() test
static DocumentInfo	discardDocument(XPathContext context, DocumentInfo doc) Remove a document from the document pool.
static DateTimeValue	fileLastModified(XPathContext context, String fileURI) This function determines the file modification time.
static String	generateId(NodeInfo node) The function saxon:generate-id() is equivalent to the standard XSLT function generate-id().
static Configuration	getConfiguration(XPathContext c) Return the Configuration object
static XPathContext	getContext(XPathContext c) Return the XPathContext object
static Controller	getController(XPathContext c) Return the Controller object
static String	getPseudoAttribute(XPathContext c, String name) Get a pseudo-attribute of a processing instruction.
static boolean	hasSameNodes(SequenceIterator p1, SequenceIterator p2) Determine whether two node-sets contain the same nodes
static byte[]	hexBinaryToOctets(HexBinaryValue in) Convert a hexBinary value to a sequence of integers representing the octets contained in the value
static String	hexBinaryToString(XPathContext context, HexBinaryValue in, String encoding) Convert a hexBinary value to a String, assuming a particular encoding
static Value	highest(SequenceIterator nsv) Get the node with maximum numeric value of the string-value of each of a set of nodes
static SequenceIterator	highest(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) Get the maximum numeric value of a stored expression over a set of nodes
static DateTimeValue	lastModified(XPathContext c) This function implements the last-modified() function without any argument.
static DateTimeValue	lastModified(XPathContext context, NodeInfo node) This function implements the last-modified(node) function with one argument which must be a node.
static SequenceIterator	leading(XPathContext context, SequenceIterator in, Evaluate.PreparedExpression pexp) Get the items that satisfy the given expression, up to and excluding the first one (in sequence order) that doesn't satisfy the expression.
static int	lineNumber(NodeInfo node) Return the line number of the specified node.
static int	lineNumber(XPathContext c) Return the line number of the context node.
static Value	lowest(SequenceIterator nsv) Get the node with minimum numeric value of the string-value of each of a set of nodes
static SequenceIterator	lowest(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) Get the node with minimum numeric value of the string-value of each of a set of nodes
static NodeInfo	namespaceNode(XPathContext context, String prefix, String uri) Create a parentless namespace node.
static Base64BinaryValue	octetsToBase64Binary(byte[] in) Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a base64Binary value
static HexBinaryValue	octetsToHexBinary(byte[] in) Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary value
static String	path(XPathContext c) Return an XPath expression that identifies the current node
static void	pauseTracing(XPathContext c) Switch tracing off.
static SequenceIterator	query(XPathContext context, XQueryExpression query) Run a previously-compiled query.
static SequenceIterator	query(XPathContext context, XQueryExpression query, Item source) Run a previously-compiled query
static SequenceIterator	query(XPathContext context, XQueryExpression query, Item source, SequenceIterator params) Run a previously-compiled query, supplying parameters to the transformation.
static void	resumeTracing(XPathContext c) Resume tracing.
static SequenceIterator	sort(XPathContext context, SequenceIterator input) Sort a sequence of nodes or atomic values, using the atomic value itself, or the atomized value of the node, as the sort key.
static SequenceIterator	sort(XPathContext context, SequenceIterator input, Evaluate.PreparedExpression sortKeyExpression) Sort a sequence of nodes or atomic values, using a given expression to calculate the sort key.
static Base64BinaryValue	stringToBase64Binary(String in, String encoding) Convert a string to a base64Binary value in a given encoding
static HexBinaryValue	stringToHexBinary(String in, String encoding) Convert a string to a hexBinary value in a given encoding
static List	stringToUtf8(String in) Get the UTF-8 encoding of a string
static String	systemId(XPathContext c) Return the system identifier of the context node
static DocumentInfo	transform(XPathContext context, Templates templates, NodeInfo source) Run a transformation to convert an input tree to an output document
static DocumentInfo	transform(XPathContext context, Templates templates, NodeInfo source, SequenceIterator params) Run a transformation to convert an input tree to an output document, supplying parameters to the transformation.
static QNameValue	typeAnnotation(XPathContext context, Item item) Display the value of the type annotation of a node or an atomic value
static boolean	validCharacter(XPathContext c, int in) Test whether a given integer is the codepoint of a valid XML character

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

pauseTracing

public static void pauseTracing(XPathContext c)

Switch tracing off. Only works if tracing was enabled at compile time.

Parameters:

c - the XPath dynamic context

resumeTracing

public static void resumeTracing(XPathContext c)

Resume tracing. Only works if tracing was originally enabled but is currently paused.

Parameters:

c - the XPath dynamic context

systemId

public static String systemId(XPathContext c)
                       throws XPathException

Return the system identifier of the context node

Parameters:

c - the XPath dynamic context

Returns:

the system ID

Throws:

XPathException

generateId

public static String generateId(NodeInfo node)

The function saxon:generate-id() is equivalent to the standard XSLT function generate-id(). It is provided as an extension function to make it available in non-XSLT environments, for example in XQuery.

Parameters:

node - the node whose identifier is required

Returns:

as ASCII alphanumeric string that uniquely identifies this node

lineNumber

public static int lineNumber(XPathContext c)

Return the line number of the context node.

Parameters:

c - the XPath dynamic context

Returns:

the line number, or -1 if not available

lineNumber

public static int lineNumber(NodeInfo node)

Return the line number of the specified node.

Parameters:

node - the node whose line number is required

Returns:

the line number of the node. This is only available if line numbering was switched on.

discardDocument

public static DocumentInfo discardDocument(XPathContext context,
                                           DocumentInfo doc)

Remove a document from the document pool. The effect is that the document becomes eligible for garbage collection, allowing memory to be released when processing of the document has finished. The downside is that a subsequent call on document() with the same URI causes the document to be reloaded and reparsed, and the new nodes will have different node identity from the old.

Parameters:

context - the evaluation context (supplied implicitly by the call mechanism)

doc - the document to be released from the document pool

Returns:

the document that was released. This allows a call such as select="saxon:discard-document(document('a.xml'))"

hasSameNodes

public static boolean hasSameNodes(SequenceIterator p1,
                                   SequenceIterator p2)
                            throws XPathException

Determine whether two node-sets contain the same nodes

Parameters:

p1 - The first node-set. The iterator must be correctly ordered.

p2 - The second node-set. The iterator must be correctly ordered.

Returns:

true if p1 and p2 contain the same set of nodes

Throws:

XPathException

sort

public static SequenceIterator sort(XPathContext context,
                                    SequenceIterator input)

Sort a sequence of nodes or atomic values, using the atomic value itself, or the atomized value of the node, as the sort key. The values must all be comparable. Strings are compared using codepoint collation. When nodes are atomized, the result must not be a sequence containing more than one item.

Parameters:

context - the XPath dynamic context

input - the sequence to be sorted

Returns:

an iterator over the sorted sequence

sort

public static SequenceIterator sort(XPathContext context,
                                    SequenceIterator input,
                                    Evaluate.PreparedExpression sortKeyExpression)

Sort a sequence of nodes or atomic values, using a given expression to calculate the sort key. as the sort key. The values must all be comparable. Strings are compared using codepoint collation. When nodes are atomized, the result must not be a sequence containing more than one item.

Parameters:

context - the XPath dynamic context

input - the sequence to be sorted

sortKeyExpression - the expression used to compute the sort keys

Returns:

an iterator over the sorted sequence

highest

public static Value highest(SequenceIterator nsv)
                     throws XPathException

Get the node with maximum numeric value of the string-value of each of a set of nodes

Parameters:

nsv - the input sequence

Returns:

the node with the maximum numeric value

Throws:

XPathException

highest

public static SequenceIterator highest(XPathContext context,
                                       SequenceIterator nsv,
                                       Evaluate.PreparedExpression pexpression)
                                throws XPathException

Get the maximum numeric value of a stored expression over a set of nodes

Parameters:

context - the XPath dynamic evaluation context

nsv - the input sequence

pexpression - the expression whose maximum is to be computed

Returns:

an iterator over the items in the input sequence for which the expression takes its maximum value

Throws:

XPathException

lowest

public static Value lowest(SequenceIterator nsv)
                    throws XPathException

Get the node with minimum numeric value of the string-value of each of a set of nodes

Parameters:

nsv - the input sequence

Returns:

the node with the minimum numeric value

Throws:

XPathException

lowest

public static SequenceIterator lowest(XPathContext context,
                                      SequenceIterator nsv,
                                      Evaluate.PreparedExpression pexpression)
                               throws XPathException

Get the node with minimum numeric value of the string-value of each of a set of nodes

Parameters:

context - the XPath dynamic evaluation context

nsv - the input sequence

pexpression - the expression whose minimum is to be computed

Returns:

an iterator over the items in the input sequence for which the expression takes its minimum value

Throws:

XPathException

leading

public static SequenceIterator leading(XPathContext context,
                                       SequenceIterator in,
                                       Evaluate.PreparedExpression pexp)

Get the items that satisfy the given expression, up to and excluding the first one (in sequence order) that doesn't satisfy the expression.

Parameters:

context - the XPath dynamic evaluation context

in - the input sequence

pexp - the expression against which items are to be tested

Returns:

an iterator over the items in the input sequence up to and excluding the first one that doesn't satisfy the expression

after

public static SequenceIterator after(XPathContext context,
                                     SequenceIterator ns1,
                                     SequenceIterator ns2)
                              throws XPathException

Find all the nodes in ns1 that are after the first node in ns2. Return ns1 if ns2 is empty,

Parameters:

context - the dynamic evaluation context

ns1 - the first operand

ns2 - the second operand

Returns:

an iterator over the nodes in ns1 that are after the first node in ns2

Throws:

XPathException

path

public static String path(XPathContext c)
                   throws XPathException

Return an XPath expression that identifies the current node

Parameters:

c - the XPath dynamic context

Returns:

a path expression giving a path from the root of the tree to the context node

Throws:

XPathException

typeAnnotation

public static QNameValue typeAnnotation(XPathContext context,
                                        Item item)

Display the value of the type annotation of a node or an atomic value

Parameters:

context - the XPath dynamic context

item - the node or atomic value whose type annotation is required

Returns:

the type annotation or type label as a QName

getContext

public static XPathContext getContext(XPathContext c)

Return the XPathContext object

Parameters:

c - the context object

Returns:

the context object (this looks crazy, but it works given that the function is called from an XPath environment where the context is supplied as an implicit argument)

getController

public static Controller getController(XPathContext c)

Return the Controller object

Parameters:

c - the XPath dynamic context

Returns:

the Controller

getConfiguration

public static Configuration getConfiguration(XPathContext c)

Return the Configuration object

Parameters:

c - the XPath dynamic context

Returns:

the Saxon configuration

getPseudoAttribute

public static String getPseudoAttribute(XPathContext c,
                                        String name)
                                 throws XPathException

Get a pseudo-attribute of a processing instruction. Return an empty string if the pseudo-attribute is not present. Character references and built-in entity references are expanded

Parameters:

c - the XPath dynamic context. The context item should be a processing instruction, though it doesn't matter if it isn't: the function will look at the string-value of the context item whatever it is.

name - the name of the required pseudo-attribute

Returns:

the value of the pseudo-attribute if it is present

Throws:

XPathException

decimalDivide

public static BigDecimal decimalDivide(BigDecimal arg1,
                                       BigDecimal arg2,
                                       int scale)

Perform decimal division to a user-specified precision

Parameters:

arg1 - the numerator

arg2 - the denominator

scale - the required number of digits in the result of the division

Returns:

the result of the division

stringToUtf8

public static List stringToUtf8(String in)

Get the UTF-8 encoding of a string

Parameters:

in - the supplied string

Returns:

a sequence of integers, each in the range 0-255, representing the octets of the UTF-8 encoding of the given string

octetsToBase64Binary

public static Base64BinaryValue octetsToBase64Binary(byte[] in)

Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a base64Binary value

Parameters:

in - the input array of bytes (octets)

Returns:

the corresponding base64Binary value

octetsToHexBinary

public static HexBinaryValue octetsToHexBinary(byte[] in)

Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary value

Parameters:

in - the input array of bytes (octets)

Returns:

the corresponding HexBinary value

base64BinaryToOctets

public static byte[] base64BinaryToOctets(Base64BinaryValue in)

Convert a base64Binary value to a sequence of integers representing the octets contained in the value

Parameters:

in - the supplied base64Binary value

Returns:

the corresponding array of integers, representing the octet values

hexBinaryToOctets

public static byte[] hexBinaryToOctets(HexBinaryValue in)

Convert a hexBinary value to a sequence of integers representing the octets contained in the value

Parameters:

in - the input hexBinary value

Returns:

the corresponding array of integers, representing the octet values

base64BinaryToString

public static String base64BinaryToString(XPathContext context,
                                          Base64BinaryValue in,
                                          String encoding)
                                   throws Exception

Convert a base64Binary value to a String, assuming a particular encoding

Parameters:

context - the XPath dynamic context

in - the supplied base64Binary value

encoding - the character encoding

Returns:

the string that results from treating the base64binary value as a sequence of octets that encode a string in the given encoding

Throws:

Exception

stringToBase64Binary

public static Base64BinaryValue stringToBase64Binary(String in,
                                                     String encoding)
                                              throws IOException

Convert a string to a base64Binary value in a given encoding

Parameters:

in - the input string

encoding - the desired encoding

Returns:

the base64Binary value that results from encoding the string as a sequence of octets in the given encoding.

Throws:

IOException

hexBinaryToString

public static String hexBinaryToString(XPathContext context,
                                       HexBinaryValue in,
                                       String encoding)
                                throws Exception

Convert a hexBinary value to a String, assuming a particular encoding

Parameters:

context - the XPath dynamic context

in - the supplied hexBinary value

encoding - the character encoding

Returns:

the string that results from treating the hexBinary value as a sequence of octets that encode a string in the given encoding

Throws:

Exception

stringToHexBinary

public static HexBinaryValue stringToHexBinary(String in,
                                               String encoding)
                                        throws Exception

Convert a string to a hexBinary value in a given encoding

Parameters:

in - the input string

encoding - the desired encoding

Returns:

the hexBinary value that results from encoding the string as a sequence of octets in the given encoding.

Throws:

Exception

validCharacter

public static boolean validCharacter(XPathContext c,
                                     int in)

Test whether a given integer is the codepoint of a valid XML character

Parameters:

c - the XPath dynamic context

in - the character to be tested

Returns:

true if and only if the character is valid in (the relevant version of) XML

namespaceNode

public static NodeInfo namespaceNode(XPathContext context,
                                     String prefix,
                                     String uri)
                              throws XPathException

Create a parentless namespace node. This function is useful in XQuery when namespaces need to be created dynamically. The effect is the same as that of the xsl:namespace instruction in XSLT.

Parameters:

context - the dynamic evaluation context

prefix - the name of the namespace node

uri - the string value of the namespace node

Returns:

the newly constructed namespace node

Throws:

XPathException

deepEqual

public static boolean deepEqual(XPathContext context,
                                SequenceIterator arg1,
                                SequenceIterator arg2,
                                String collation,
                                String flags)
                         throws XPathException

Perform a parameterized deep-equals() test

Parameters:

context - The evaluation context

arg1 - The first sequence to be compared

arg2 - The second sequence to be compared

collation - The collation to be used (null if the default collation is to be used)

flags - A string whose characters select options that cause the comparison to vary from the standard fn:deep-equals() function. The flags are:

• N - take namespace nodes into account
• A - compare type annotations
• C - take comments into account
• F - take namespace prefixes into account
• P - take processing instructions into account
• S - compare string values, not typed values
• w - don't take whitespace-only text nodes into account

Returns:

true if the sequences are deep equal, otherwise false

Throws:

XPathException

lastModified

public static DateTimeValue lastModified(XPathContext c)
                                  throws XPathException

This function implements the last-modified() function without any argument. It returns the modification time of the file containing the context node.

Parameters:

c - the dynamic evaluation context supplied by Saxon

Returns:

file modification time as an xs:dateTime value, or an empty sequence if the context item is not a node or if the context node is not present in a local file

Throws:

XPathException - XPath dynamic error reported back to Saxon

lastModified

public static DateTimeValue lastModified(XPathContext context,
                                         NodeInfo node)
                                  throws XPathException

This function implements the last-modified(node) function with one argument which must be a node. It returns the modification time of the file containing the context node.

Parameters:

node - the node supplied by a user

Returns:

file modification time as an xs:dateTime value, or an empty sequence if the supplied node is not present in a local file

Throws:

XPathException - if an error occurs and the configuration option TRACE_EXTERNAL_FUNCTIONS is true

fileLastModified

public static DateTimeValue fileLastModified(XPathContext context,
                                             String fileURI)
                                      throws XPathException

This function determines the file modification time. It can be called from the stylesheet as file-timestamp(fn).

Parameters:

context - the XPath dynamic evaluation context

fileURI - the URI of a file. This must be an absolute URI to which Saxon can connect

Returns:

file modification time as an xs:dateTime value or an empty sequence if the file is not found

Throws:

XPathException - if an error occurs and the configuration option TRACE_EXTERNAL_FUNCTIONS is true

compileStylesheet

public static Templates compileStylesheet(XPathContext context,
                                          DocumentInfo doc)
                                   throws XPathException

Compile a document containing a stylesheet module into a stylesheet that can be used to perform transformations

Parameters:

context - the XPath dynamic evaluation context

doc - the document containing the stylesheet to be compiled

Returns:

the compiled stylesheet

Throws:

XPathException

transform

public static DocumentInfo transform(XPathContext context,
                                     Templates templates,
                                     NodeInfo source)
                              throws XPathException

Run a transformation to convert an input tree to an output document

Parameters:

context - The dynamic context

templates - The compiled stylesheet

source - The initial context node representing the document to be transformed

Returns:

the document that results from the transformation

Throws:

XPathException

transform

public static DocumentInfo transform(XPathContext context,
                                     Templates templates,
                                     NodeInfo source,
                                     SequenceIterator params)
                              throws XPathException

Run a transformation to convert an input tree to an output document, supplying parameters to the transformation.

Parameters:

context - The dynamic context

templates - The compiled stylesheet

source - The initial context node representing the document to be transformed

params - A sequence of nodes (typically element nodes) supplying values of parameters. The name of the node should match the name of the parameter, the typed value of the node is used as the value of the parameter.

Returns:

the document that results from the transformation

Throws:

XPathException

compileQuery

public static XQueryExpression compileQuery(XPathContext context,
                                            String query)
                                     throws XPathException

Compile a string containing a source query transformations

Parameters:

context - the XPath dynamic evaluation context

query - a string containing the query to be compiled

Returns:

the compiled query

Throws:

XPathException

query

public static SequenceIterator query(XPathContext context,
                                     XQueryExpression query)
                              throws XPathException

Run a previously-compiled query. The initial context item for the query is taken from the context in which the query is called (if there is one); no parameters are supplied

Parameters:

context - The dynamic context

query - The compiled query

Returns:

the sequence representing the result of the query

Throws:

XPathException

query

public static SequenceIterator query(XPathContext context,
                                     XQueryExpression query,
                                     Item source)
                              throws XPathException

Run a previously-compiled query

Parameters:

context - The dynamic context

query - The compiled query

source - The initial context item for the query (may be null)

Returns:

the sequence representing the result of the query

Throws:

XPathException

query

public static SequenceIterator query(XPathContext context,
                                     XQueryExpression query,
                                     Item source,
                                     SequenceIterator params)
                              throws XPathException

Run a previously-compiled query, supplying parameters to the transformation.

Parameters:

context - The dynamic context

query - The compiled query

source - The initial context node for the query (may be null)

params - A sequence of nodes (typically element nodes) supplying values of parameters. The name of the node should match the name of the parameter, the typed value of the node is used as the value of the parameter.

Returns:

the results of the query (a sequence of items)

Throws:

XPathException