Class XPathCompiler


  • public class XPathCompiler
    extends java.lang.Object
    An XPathCompiler object allows XPath queries to be compiled. The compiler holds information that represents the static context for an XPath expression.

    To construct an XPathCompiler, use the factory method Processor.newXPathCompiler().

    An XPathCompiler may be used repeatedly to compile multiple queries. Any changes made to the XPathCompiler (that is, to the static context) do not affect queries that have already been compiled. An XPathCompiler may be used concurrently in multiple threads, but it should not then be modified once initialized.

    Changes to an XPathCompiler are cumulative. There is no simple way to reset the XPathCompiler to its initial state; instead, simply create a new XPathCompiler.

    Since:
    9.0
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected XPathCompiler​(Processor processor)
      Protected constructor
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      XPathExecutable compile​(java.lang.String source)
      Compile an XPath expression, supplied as a character string.
      XPathExecutable compilePattern​(java.lang.String source)
      Compile an XSLT 2.0 pattern, supplied as a character string.
      void declareNamespace​(java.lang.String prefix, java.lang.String uri)
      Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler
      void declareVariable​(QName qname)
      Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler.
      void declareVariable​(QName qname, ItemType itemType, OccurrenceIndicator occurrences)
      Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler.
      java.net.URI getBaseURI()
      Get the static base URI for XPath expressions compiled using this XPathCompiler.
      StaticContext getUnderlyingStaticContext()
      Escape-hatch method to get the underlying static context object used by the implementation.
      void importSchemaNamespace​(java.lang.String uri)
      Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.
      boolean isBackwardsCompatible()
      Ask whether XPath 1.0 backwards compatibility mode is in force.
      void setBackwardsCompatible​(boolean option)
      Set whether XPath 1.0 backwards compatibility mode is to be used.
      void setBaseURI​(java.net.URI uri)
      Set the static base URI for XPath expressions compiled using this XPathCompiler.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • XPathCompiler

        protected XPathCompiler​(Processor processor)
        Protected constructor
        Parameters:
        processor - the s9api Processor
    • Method Detail

      • setBackwardsCompatible

        public void setBackwardsCompatible​(boolean option)
        Set whether XPath 1.0 backwards compatibility mode is to be used. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).
        Parameters:
        option - true if XPath 1.0 backwards compatibility is to be enabled, false if it is to be disabled.
      • isBackwardsCompatible

        public boolean isBackwardsCompatible()
        Ask whether XPath 1.0 backwards compatibility mode is in force.
        Returns:
        true if XPath 1.0 backwards compatibility is enabled, false if it is disabled.
      • setBaseURI

        public void setBaseURI​(java.net.URI uri)
        Set the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI is supplied, then the current working directory is used.
        Parameters:
        uri - the base URI to be set in the static context. This must be an absolute URI.
      • getBaseURI

        public java.net.URI getBaseURI()
        Get the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI has been explicitly set, this method returns null.
        Returns:
        the base URI from the static context
      • declareNamespace

        public void declareNamespace​(java.lang.String prefix,
                                     java.lang.String uri)
        Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler
        Parameters:
        prefix - The namespace prefix. If the value is a zero-length string, this method sets the default namespace for elements and types.
        uri - The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace; in this case the prefix will not be available for use, except in the case where the prefix is also a zero length string, in which case the absence of a prefix implies that the name is in no namespace.
        Throws:
        java.lang.NullPointerException - if either the prefix or uri is null.
      • importSchemaNamespace

        public void importSchemaNamespace​(java.lang.String uri)
        Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

        This method will not cause the schema to be loaded. That must be done separately, using the SchemaManager. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.

        This method does not bind a prefix to the namespace. That must be done separately, using the declareNamespace(String, String) method.

        Parameters:
        uri - The schema namespace to be imported. To import declarations in a no-namespace schema, supply a zero-length string.
        Since:
        9.1
      • declareVariable

        public void declareVariable​(QName qname)
        Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler. It is an error for the XPath expression to refer to a variable unless it has been declared. This method declares the existence of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated. The variable is allowed to have any type (that is, the required type is item()*).
        Parameters:
        qname - The name of the variable, expressions as a QName
      • declareVariable

        public void declareVariable​(QName qname,
                                    ItemType itemType,
                                    OccurrenceIndicator occurrences)
                             throws SaxonApiException
        Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler. It is an error for the XPath expression to refer to a variable unless it has been declared. This method declares the existence of the variable, and defines the required type of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated.
        Parameters:
        qname - The name of the variable, expressed as a QName
        itemType - The required item type of the value of the variable
        occurrences - The allowed number of items in the sequence forming the value of the variable
        Throws:
        SaxonApiException - if the requiredType is syntactically invalid or if it refers to namespace prefixes or schema components that are not present in the static context
      • compile

        public XPathExecutable compile​(java.lang.String source)
                                throws SaxonApiException
        Compile an XPath expression, supplied as a character string.
        Parameters:
        source - A string containing the source text of the XPath expression
        Returns:
        An XPathExecutable which represents the compiled xpath expression object. The XPathExecutable may be run as many times as required, in the same or a different thread. The XPathExecutable is not affected by any changes made to the XPathCompiler once it has been compiled.
        Throws:
        SaxonApiException - if any static error is detected while analyzing the expression
      • compilePattern

        public XPathExecutable compilePattern​(java.lang.String source)
                                       throws SaxonApiException
        Compile an XSLT 2.0 pattern, supplied as a character string. The compiled pattern behaves as a boolean expression which, when evaluated in a particular context, returns true if the context node matches the pattern, and false if it does not. An error is reported if there is no context item or it the context item is not a node.
        Parameters:
        source - A string conforming to the syntax of XSLT 2.0 patterns
        Returns:
        An XPathExecutable representing an expression which evaluates to true when the context node matches the pattern, and false when it does not.
        Throws:
        SaxonApiException - if the pattern contains static errors: for example, if its syntax is incorrect, or if it refers to undeclared variables or namespaces
        Since:
        9.1
      • getUnderlyingStaticContext

        public StaticContext getUnderlyingStaticContext()
        Escape-hatch method to get the underlying static context object used by the implementation.
        Returns:
        the underlying static context object. In the current implementation this will always be an instance of IndependentContext.

        This method provides an escape hatch to internal Saxon implementation objects that offer a finer and lower-level degree of control than the s9api classes and methods. Some of these classes and methods may change from release to release.

        Since:
        9.1