Class Extensions


  • public class Extensions
    extends java.lang.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 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 java.lang.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 java.lang.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.
      • columnNumber

        public static int columnNumber​(XPathContext c)
        Return the column number of the context node. This is only available if line numbering has been enabled for the containing tree
        Parameters:
        c - the XPath dynamic context
        Returns:
        the column number, or -1 if not available
      • columnNumber

        public static int columnNumber​(NodeInfo node)
        Return the column number of the specified node.
        Parameters:
        node - the node whose column number is required
        Returns:
        the column 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
      • path

        public static java.lang.String path​(NodeInfo node)
                                     throws XPathException
        Return an XPath expression that identifies a specified node
        Parameters:
        node - the node whose path is required
        Returns:
        a path expression giving a path from the root of the tree to the specified node
        Throws:
        XPathException
      • path

        public static java.lang.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
      • printStack

        public static java.lang.String printStack​(XPathContext c)
        Return a string containing a diagnostic print of the current execution stack
        Parameters:
        c - the XPath dynamic context
        Returns:
        a diagnostic stack print
      • getPseudoAttribute

        public static java.lang.String getPseudoAttribute​(XPathContext c,
                                                          java.lang.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 java.math.BigDecimal decimalDivide​(java.math.BigDecimal arg1,
                                                         java.math.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 java.util.List stringToUtf8​(java.lang.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 java.lang.String base64BinaryToString​(XPathContext context,
                                                            Base64BinaryValue in,
                                                            java.lang.String encoding)
                                                     throws java.lang.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:
        java.lang.Exception
      • stringToBase64Binary

        public static Base64BinaryValue stringToBase64Binary​(java.lang.String in,
                                                             java.lang.String encoding)
                                                      throws java.io.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:
        java.io.IOException
      • hexBinaryToString

        public static java.lang.String hexBinaryToString​(XPathContext context,
                                                         HexBinaryValue in,
                                                         java.lang.String encoding)
                                                  throws java.lang.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:
        java.lang.Exception
      • stringToHexBinary

        public static HexBinaryValue stringToHexBinary​(java.lang.String in,
                                                       java.lang.String encoding)
                                                throws java.lang.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:
        java.lang.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,
                                             java.lang.String prefix,
                                             java.lang.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
      • unparsedEntities

        public static java.lang.String[] unparsedEntities​(DocumentInfo doc)
                                                   throws XPathException
        Get a list of the names of the unparsed entities in a document
        Parameters:
        doc - the document node of the document whose unparsed entities are required
        Returns:
        an iterator over a sequence of strings containing the names of the unparsed entities
        Throws:
        XPathException
      • deepEqual

        public static boolean deepEqual​(XPathContext context,
                                        SequenceIterator arg1,
                                        SequenceIterator arg2,
                                        java.lang.String collation,
                                        java.lang.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
        • J - join adjacent text nodes (e.g, nodes either side of a comment)
        • 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,
                                                     java.lang.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
      • inSummerTime

        public static BooleanValue inSummerTime​(XPathContext context,
                                                DateTimeValue date,
                                                java.lang.String region)
        Determine whether a given date/time is in summer time (daylight savings time) in a given region. This relies on the Java database of changes to daylight savings time. Since summer time changes are set by civil authorities the information is not necessarily reliable when applied to dates in the future.
        Parameters:
        context - used to get the implicit timezone in the event that the supplied date/time has no timezone
        date - the date/time in question. This should preferably include a timezone.
        region - either the two-letter ISO country code, or an Olsen timezone name such as "America/New_York" or "Europe/Lisbon". If the country code denotes a country spanning several timezones, such as the US, then one of them is chosen arbitrarily.
        Returns:
        true if the date/time is known to be in summer time in the relevant country; false if it is known not to be in summer time; null if there is no timezone or if no information is available.
      • compileStylesheet

        public static javax.xml.transform.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,
                                             javax.xml.transform.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,
                                             javax.xml.transform.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,
                                                    java.lang.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,
                                             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