Perform basic XPath operations

Use the XPathExecutable instances created using XFactory.prepareXPath methods to evaluate XPath expressions.

XPath expressions can be passed to the XFactory.prepareXPath method using a JAXP StreamSource object or using a plain Java string object. The resulting XPathExecutable instance is thread safe and can be reused to evaluate an XPath expression on multiple XML input documents.

For more info on usage, download and execute the XML samples

Tasks

• Use the XStaticContext object with the prepareXPath method to pass in settings that affect how the XPath expression is prepared.

  If no XStaticContext object is provided, the default setting is used.

  XStaticContext settings relevant to XPath:

  declareFunction

  Declare a Java extension function

  declareNamespace

  Declare a namespace prefix and associate it with a namespace URI to be used as part of an XPath expression

  declareVariable

  Declare a variable externally to be used as part of an XPath expression

  setBaseURI

  Set the base URI used in the resolution of relative URIs (such as by the fn:resolve-uri function)

  The default is the base URI of the expression, query, or stylesheet if the base URI is available. If the base URI is not available, the current working directory is used.

  setDefaultCollation

  Set the default collation URI for string comparison operations

  The default is the Unicode code point collation URI.

  setDefaultElementTypeNamespace

  URI of the default element or type namespace

  Use an empty string to make it unspecified.

  The default is an empty string.

  setDefaultFunctionNamespace

  URI of the default function namespace

  Use an empty string to make it unspecified.

  The default is "http://www.w3.org/2005/xpath-functions".

  setIntegerMathMode

  Set the integer math mode to one of the following:

  INTEGER_MATH_MODE_LIMITED_PRECISION

  Limit to 18-digit precision for xs:integer (default)

  INTEGER_MATH_MODE_ARBITRARY_PRECISION

  Allow users to have arbitrary precision for xs:integer

  INTEGER_MATH_MODE_OVERFLOW_DETECTION

  Generate an error if an overflow is detected

  setMessageHandler()

  Set the message handler for prepare-time errors

  The default behavior is to print errors, warnings, and informational messages to System.err and to generate an XProcessException in the case of an unrecoverable error when compilation cannot continue. If the message handler registered does not generate its own exception in the case of an unrecoverable error, an XProcessException occurs.

  setUseCompiler

  Indicate whether to generate a compiled executable or an interpreted executable

  A compiled executable takes longer to generate but runs faster than an interpreted executable. The default is interpreted.

  setXPathCompatibilityMode

  Set the compatibility mode to be used when evaluating XPath expressions

  The options are as follows:

  XPATH2_0_PURE_COMPATIBILITY (default)

  Use the default behavior defined by XPath 2.0 in evaluating expressions.

  XPATH1_0_BC_COMPATIBILITY

  Use the backwards-compatibility behavior defined by XPath 2.0 that yields results that are most consistent with those that would be produced by an XPath 1.0 processor.

  XPATH_LATEST_VERSION

  Use the default behavior defined by the most recent version of XPath supported by the processor.

• Provide an XDynamicContext object used to pass settings to the XPathExecutable.execute method.

  These settings affect the behavior during the execution when the processor is evaluating an XPath expression.

  If no XDynamicContext object is provided, the default setting is used.

  XDynamicContext settings relevant to XPath:

  bind

  Bind a value to an external variable

  bindCollation

  Binds an instance of the java.text.Collator class to a particular collation URI for use in string comparisons that use that collation URI

  bindFunction

  Bind an external function so that it can be used as part of an XPath expression

  bindSequence

  Bind a sequence value to an external variable

  setCollectionResolver

  Set the collection resolver used to resolve documents loaded with the XPath fn:collection function

  The default behavior is for references to the fn:collection function to return an empty sequence.

  setImplicitTimeZone

  Set the implicit time zone

  The default is to use the system time zone as retrieved through the Java method java.util.TimeZone.getDefault().

  setMessageHandler()

  Set the message handler for excution-time errors

  The default behavior is to print errors, warnings and informational messages to System.err and to generate an XProcessException in the case of an unrecoverable error. If the message handler registered does not generate its own exception in the case of an unrecoverable error, an XProcessException occurs.

  setSourceResolver

  Set the source resolver used to resolve documents loaded with the XPath fn:doc function

  The default behavior is to resolve documents based on the base URI from the static context. If the base URI is not available, the current working directory is used.

• Use schemas with XPath expression evaluation.

  For schema-aware XPath evaluation and validating the input XML file, schema files can be registered using the XFactory.registerSchema() method or we can declare the xsi:schemaLocation directive in their input XML files. In either case, validation needs to be enabled using the XFactory.setValidating() method.

Example

Example: Simple XPath invocation.

package com.ibm.xml.samples.invocations;

import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamSource;

import com.ibm.xml.xapi.XFactory;
import com.ibm.xml.xapi.XPathExecutable;
import com.ibm.xml.xapi.XSequenceCursor;

public class SimpleXPath {

    /**
     * @param args
     */
    public static String execute(String inputfile, String xpathS) throws Exception {
        StringBuffer result = new StringBuffer();
        
        // Create the factory
        XFactory factory = XFactory.newInstance();

        // Create an XPath executable for the expression
        XPathExecutable xpath = factory.prepareXPath(xpathS);
        
        // Create the input source
        Source source = new StreamSource(SimpleXPath.class.getResourceAsStream(inputfile));
        
        // Execute the expression
        XSequenceCursor sequence = xpath.execute(source);
        
        // Print out the result
        if (sequence != null) {
            do {
                result.append(sequence.getStringValue() + "\n");
            } while (sequence.toNext());
        }
        
        return result.toString();
    }
}

The above code reads names.xml

<doc>
    <style type="text/css" 
              id="night-mode-pro-style">
              html {background-color: #FFFFFF !important; filter: brightness(99%) !important;} body {background-color: #FFFFFF;}
    </style>
    <link type="text/css" rel="stylesheet" id="night-mode-pro-link"/>
    <name first="Jane" last="Doe"/>
    <name first="Jim" last="Smith"/>
    <name first="John" last="Doe"/>
</doc>

To invoke...

SimpleXPath.execute("/sampledata/names.xml", "/doc/name[1]/@last");

Output is "Doe"

Example: Prepare and execute an interpreted XPath expression.

// Create a string for the XPath expression
String expression = "/doc/something";

// Create the factory
XFactory factory = XFactory.newInstance();

// Create an XPath executable for the expression
XPathExecutable xPathExecutable = factory.prepareXPath(expression);

// Create the input XML source
String xml = "<doc><something>something is selected</something></doc>";

// Execute the expression and store the results in an XSequenceCursor
xSequenceCursor = xPathExecutable.execute(new StreamSource(new ByteArrayInputStream(xml.getBytes())));

Example: Prepare and execute a compiled XPath expression.

// Create a string for the XPath expression
String expression = "/doc/something";

// Create the factory
XFactory factory = XFactory.newInstance();

// Create a new static context from the factory
XStaticContext xStaticContext = factory.newStaticContext();

// Set the mode to compile for the processor
xStaticContext.setUseCompiler(true);

// Create an XPath executable for the expression
XPathExecutable xPathExecutable = factory.prepareXPath(expression, xStaticContext);

// Create the input XML source
String xml = "<doc><something>something is selected</something></doc>";

// Execute the expression and store the results in an XSequenceCursor
XSequenceCursor xSequenceCursor = xPathExecutable.execute(new StreamSource(new ByteArrayInputStream(xml.getBytes())));

Example: Prepare and execute interpreted XPath expressions with schema validation.

// Create a string for the XPath expression
String expression = "/doc/byte cast as my:derived1-byte-enumeration-Type";

// Create the factory
XFactory factory = XFactory.newInstance();
            
// Create the schema source
String schema = "<xsd:schema xmlns:xsd='http://www.w3.org/2001/XMLSchema'" +
          " targetNamespace='http://www.schematype.ibm.com/UDSimple'" +
          " xmlns:my='http://www.schematype.ibm.com/UDSimple'" +
          " xmlns:smokey='http://www.schematype.ibm.com/UDSimple'>"
          + "  <xsd:simpleType name='derived1-byte-enumeration-Type'>"
          + "   <xsd:restriction base='xsd:byte'>"
          + "     <xsd:enumeration value='1' />"
          + "     <xsd:enumeration value='-1' />"
          + "     <xsd:enumeration value='0' />"
          + "     <xsd:enumeration value='127' />"
          + "     <xsd:enumeration value='-128' />"
          + "     <xsd:enumeration value='32' />"
          + "     <xsd:enumeration value='-32' />"
          + "     <xsd:enumeration value='8' />"
          + "     <xsd:enumeration value='-8' />"
          + "     <xsd:enumeration value='2' />"
          + "     <xsd:enumeration value='-2' />"
          + "   </xsd:restriction>"
          + "  </xsd:simpleType>"
          + "</xsd:schema>";
// Load schema
factory.registerSchema(new StreamSource(new ByteArrayInputStream(schema.getBytes())));
            
// Turn on validation
factory.setValidating(true);
            
// Create a new static context from the factory
XStaticContext xStaticContext = factory.newStaticContext();

// Add new namespace
xStaticContext.declareNamespace("my", "http://www.schematype.ibm.com/UDSimple");

// Create an XPath executable for the expression
XPathExecutable xPathExecutable = factory.prepareXPath(expression, xStaticContext);
            
// Create the input XML source
String xml = "<doc>" +
             "    <byte>1</byte>" +
             "</doc>";

// Execute the expression and store the results in an XSequenceCursor
XSequenceCursor xSequenceCursor = xPathExecutable.execute(new StreamSource(new ByteArrayInputStream(xml.getBytes())));

Use static and dynamic contexts

Use external functions

Use external functions with XPath

Use a source resolver at prepare time

Use a message handler

Use a message handler and managing exceptions

Choosing between the compiler and the interpreter

Use external variables

Use external variables with XPath

Use a source resolver at execution time

Registering a collection resolver

Work with collations

XML Samples Application