Serializing the results

After the application has evaluated an XPath or XQuery expression or performed a transformation with an XSLT stylesheet, we might want to write the output as an actual XML document represented as a file or as a Java string. The process of rendering results as an XML document is known as serialization.

Tasks

• Serialize an XSequenceCursor.

  The application can call the XSequenceCursor.exportSequence method to serialize a sequence represented by an instance of the XSequenceCursor interface. The arguments on this method are an instance of the javax.xml.transform.Result interface and optionally an instance of the XOutputParameters interface.

  If the instance of the Result interface is also an instance of the javax.xml.transform.stream.StreamResult class, the sequence is serialized as described in the XSLT 2.0 and XQuery 1.0 Serialization Recommendation. The StreamResult object can contain an instance of the java.io.Writer class or the java.io.OutputStream class, where the processor will write the serialized sequence.

  Create an instance of the XOutputParameters interface by calling XFactory.newOutputParameters() and call the methods on that object to override the default serialization parameter settings.

  XFactory factory = XFactory.newInstance();
  XPathExecutable expr = factory.prepareXPath("/purchaseOrder/item[@price > 1000]");
  XSequenceCursor exprResult = expr.execute(new StreamSource(inputFile));
  
  System.out.println("Items purchased costing more than $1000");
  if (exprResult != null) {
      // Set indenting in order to pretty-print result
      XOutputParameters params = factory.newOutputParameters();
      params.setIndent(true);
      exprResult.exportSequence(new StreamResult(System.out), params);
  } else {
      System.out.println("None found");
  }
  

  We can also call one of the getOutputParameters() methods on an instance of the XSLTExecutable interface to get the serialization parameters associated with a particular output definition in an XSLT stylesheet. Use the XSLTExecutable.getOutputParameters(javax.xml.namespace.QName) method to get the serialization parameters for a named output definition or the no-argument XSLTExecutable.getOutputParameters() method to get those of the unnamed output definition. We might want do this to perform some post-processing on the result of the transformation using the instance of the XSequenceCursor interface that the transformation produces before serializing the result. If we change the settings of the serialization parameters in the instance of the XOutputParameters interface returned by one of the XSLTExecutable.getOutputParameters() methods, it will not affect the output definition in the stylesheet.

  XFactory factory = XFactory.newInstance();
  XSLTExecutable style = factory.prepareXSLT(new StreamSource("style.xsl"));
  XSequenceCursor xformResult = style.execute(new StreamSource("purchase.xml");
  
  XOutputParameters params = style.getOutputParameters(new QName("my-output-definition"));
  params.setMethod(XOutputParameters.METHOD_XHTML);
  xformResult.exportSequence(new StreamResult("output.html"), params);
  

  Note that according to the XSLT 2.0 and XQuery 1.0 Serialization Recommendation, a serialization error results if the sequence that is to be serialized contains attribute nodes or namespace nodes. If the sequence needed to serialize might contain attribute or namespace nodes, get the values of those nodes as strings or some other appropriate type and serialize those values instead.

• Serialize a single item.

  We can also serialize just the current item in an instance of the XSequenceCursor interface using one of the exportItem methods. The exportItem methods are inherited from the XItemView interface, so they can be called on an instance of that interface as well.

  As with the exportSequence method described previously, the arguments of the exportItem method are an instance of the javax.xml.transform.Result interface and optionally an instance of the XOutputParameters interface. The effect of calling exportItem is identical to the effect of calling exportSequence with a sequence that consists of just the current item.

• Serialize the result of a transformation or query directly.

  The application can also serialize the result of an XSLT transformation or XQuery expression directly by supplying an instance of the javax.xml.transform.Result interface on the XSLTExecutable.execute method or XQueryExecutable.execute method. The serialization parameter settings are determined by the attributes of any applicable xsl:output declaration or xsl:result-document instruction in the case of an XSLT stylesheet, and are always the default values in the case of the result of an XQuery expression.

  XFactory factory = XFactory.newInstance();
  XSLTExecutable style = factory.prepareXSLT(new StreamSource("style.xsl"));
  style.execute(new StreamSource("purchase.xml"),
                new StreamResult("output.xml"));
  

  If the application supplies an instance of the XResultResolver interface on a transformation, the application can direct each final result tree to a different destination.

• Use identity transformation.

  Use the XML API to transform XML data contained in an instance of javax.xml.transform.Source directly to an instance of a javax.xml.transform.Result. This is often referred to as an identity transformation. See Perform basic XSLT operations for an example.

Related:

Supported input and result types

View the results

Perform basic XSLT operations