View the results

After the application has prepared or loaded the XExecutable object for an XPath expression (an XPathExecutable object), an XSLT stylesheet (an XSLTExecutable object), or an XQuery expression (an XQueryExecutable object), we apply the XExecutable object to some input and then do something with the result. The source of the input that we provide and what we would like to do with the result determine which of the execute methods we use.

Tasks

• View XPath results.

  In the case of an XPath expression, the execute methods on the XPathExecutable interface return an instance of the XSequenceCursor class containing the sequence that results from evaluating the expression with the given context item and dynamic context, if any.

  There is also a set of executeToList methods on the XPathExecutable interface. These methods return the sequence as an instance of the java.util.List<XItemView> interface, where each item in the sequence that results from evaluating the XPath expression is represented in the list as an instance of the XItemView interface. The entries in that list are in the same order as in the sequence that resulted from evaluating the XPath expression.

  The following example shows how to get the cost of each item on a purchase order as an XSequenceCursor.

  XFactory factory = XFactory.newInstance();
  XPathExecutable expr =
      factory.prepareXPath(
          "/purchaseOrder/item/(@unit-price * @quantity)");
  XSequenceCursor exprResult = expr.execute(new StreamSource("input.xml"));
  

  The following example shows how to get the cost of each item on a purchase order in an instance of the java.util.List interface.

  XFactory factory = XFactory.newInstance();
  XPathExecutable expr =
      factory.prepareXPath(
          "/purchaseOrder/item/(@unit-price * @quantity)");
  List<XItemView> exprResult =
     expr.executeToList(new StreamSource("input.xml"));
  

• Use the XItemView interface.

  We can access each item in a sequence using the methods on the XItemView interface. Use the XItemView.isAtomic() method to determine whether the item is an atomic value or a node. If the item is an atomic value, we can use the getValueType() method on the XItemView interface. This method returns an instance of the enumerated type XTypeConstants.Type. If the atomic value is an instance of a built-in atomic type or a user-defined type derived from a built-in atomic type, the result of the getValueType() method is the enumerated value corresponding to that type. For an atomic value that could be of a user-defined derived type, you also might find it handy to use the XItemView.getValueTypeName() method to determine the precise type of the value.

  Given the type of an atomic value, we then can use the appropriate method to get the value.

  XFactory factory = XFactory.newInstance();
  XPathExecutable expr =
      factory.prepareXPath(
          "sum(/purchaseOrder/item/(@unit-price * @quantity))");
  XItemView exprResult =
     expr.execute(new StreamSource(purchaseOrder));
  double totalCost = 0.0;
  
  // Decide how to get result based on the type of the value
  switch (exprResult.getValueType()) {
  case DOUBLE: {
      totalCost = exprResult.getDoubleValue();
      break;
  }
  case FLOAT: {
      totalCost = exprResult.getFloatValue();
      break;
  }
  case INTEGER: {
      totalCost = exprResult.getLongValue();
      break;
  }
  case DECIMAL: {
      totalCost = exprResult.getDecimalValue().doubleValue();
      break;
  }
  default: {
      System.err.println("Unexpected type for result");
  }
  }
  

  The XItemView interface also extends the XNodeView interface, so if the result of calling the XItemView.isAtomic() method is false - that is, the item is a node - we can use the methods inherited from the XNodeView interface to access information about the node. The XNodeView.getNodeQName() method will return the name of the node and the XNodeView.getKind() method will return a value of the enumerated type XNodeView.Kind indicating what sort of node the item is: XNodeView.DOCUMENT, XNodeView.ELEMENT, and so on.

  XFactory factory = XFactory.newInstance();
  
  // Prepare an expression to get the first node whose string value matches a given query string
  XPathExecutable expr =
      factory.prepareXPath(
          "(/descendant-or-self::node()/(self::node()|@*)[. = 'search'])[1]");
  XItemView exprResult =
     expr.execute(new StreamSource(inputFile));
  
  // Print the kind of node found and its name, if appropriate
  switch (exprResult.getKind()) {
  case ELEMENT: {
      System.out.print("Element " + exprResult.getNodeQName().toString());
      break;
  }
  case ATTRIBUTE: {
      System.out.print("Attribute " + exprResult.getNodeQName().toString());
      break;
  }
  case COMMENT: {
      System.out.print("Comment ");
      break;
  }
  case PROCESSING_INSTRUCTION: {
      System.out.print("PI " + exprResult.getNodeQName().toString());
  }
  }
  

  We can also explore the tree containing a node using the XTreeCursor interface.

• View XSLT and XQuery results.

  All the execute and executeToList methods available from the XPathExecutable interface are actually inherited from the XExecutable interface, so they are available for use on instances of the XSLTExecutable interface or the XQueryExecutable interface as well. In the case of an instance of the XQueryExecutable interface, the object the method returns contains the sequence that resulted from evaluating the query. In the case of the XSLTExecutable interface, the sequence contains the document node of the primary result of evaluating the stylesheet, if there is any.

  The XSLTExecutable and XQueryExecutable interfaces also define execute methods that accept an instance of the javax.xml.transform.Result interface. The result object that the application supplies will contain the primary result of evaluating the stylesheet, in the case of the XSLTExecutable interface, or the result of evaluating your query, in the case of XQueryExecutable.

  The following example produces a DOM tree as the result of a transformation, and stores the tree in the instance of the DOMResult class that is passed as an argument to the XSLTExecutable.execute method.

  XFactory factory = XFactory.newInstance();
  XSLTExecutable style = factory.prepareXSLT(new StreamSource("style.xsl"));
  DOMResult res = new DOMResult();
  style.execute(new StreamSource("purchase.xml"), res);
  Node node = res.getNode();
  

  The following example produces an instance of the XSequenceCursor interface as the result of transformation.

  XFactory factory = XFactory.newInstance();
  XSLTExecutable style = factory.prepareXSLT(new StreamSource("style.xsl"));
  XSequenceCursor xformResult =
          style.execute(new StreamSource("purchase.xml"));
  

• Use the XResultResolver and XSLT.

  An XSLT 2.0 stylesheet can produce more than one result document using the xsl:result-document instruction. The primary result of the transformation is produced for any result tree that the stylesheet constructs that is not contained in an xsl:result-document instruction or that is contained in an xsl:result-document instruction that has an href attribute whose effective value is a zero-length string. The primary result is returned to the application using the various means described previously.

  If our stylesheet evaluates an xsl:result-document instruction that has an href attribute whose effective value is not a zero-length string, by default that result is written to an output stream. The URI of the output stream is determined by resolving the effective value of the href attribute against the setting of the base output URI in the dynamic context.

  We can override this default behavior by supplying an instance of the XResultResolver interface on the XDynamicContext we use for the transformation. The getResult method on the XResultResolver interface is called if any xsl:result-document instructions are invoked; the result of the getResult method is an instance of the Result interface where the result of the xsl:result-document instruction is directed. Using the XResultResolver interface allows the application to decide on a case by case basis where to direct the result of all the xsl:result-document instructions in your stylesheets. If the application did not supply an instance of the Result interface for the primary result on the execute method of the XSLTExecutable interface, the getResult method of XResultResolver is called for the primary result as well.

  If the getResult method of XResultResolver returns a null reference, the default behavior is restored for that particular result-that is, the result is written to an output stream, in the case of a secondary result, or returned from as the result of the execute method as an instance of the XSequenceCursor interface, in the case of the primary result.

  The following example uses an instance of the XResultResolver interface to capture all the results produced by a stylesheet as instances of the XSequenceCursorResult class in the variable allResults. The application then could extract the instance of the XSequenceCursor interface that each instance of the XSequenceCursorResult class contains using the XSequenceCursorResult.getSequenceCursor() method.

  final ArrayList<XSequenceCursorResult> allResults =
              new ArrayList<XSequenceCursorResult>();
  XFactory factory = XFactory.newInstance();
  XDynamicContext context = factory.newDynamicContext();
  
  // Create XResultResolver that saves XSequenceCursorResult
  // instances in allResults
  context.setResultResolver(new XResultResolver() {
          public Result getResult(String href, String base) {
              XSequenceCursorResult result =
                      new XSequenceCursorResult();
              allResults.add(result);
              return result;
          }
      });
  
  XSLTExecutable style = factory.prepareXSLT(new StreamSource("style.xsl"));
  style.execute(new StreamSource("purchase.xml"), context);
  
  // All results, including the primary, are now available from the allResults variable.
  

Navigating with XSequenceCursor

Navigating with XTreeCursor

Serializing the results

Perform basic XSLT operations

Use a result resolver at execution time