net.sf.saxon.lib

Interface ResultDocumentResolver

All Known Implementing Classes:

OutputURIResolverWrapper, StandardResultDocumentResolver

public interface ResultDocumentResolver

The ResultDocumentResolver interface may be implemented by a user application; it is a callback that is called whenever an xsl:result-document instruction is executed.

There is a single method: resolve(XPathContext, String, String, SerializationProperties). Saxon calls this method supplying the dynamic evaluation context, together with the value of the href attribute and the output base URI for the transformation.

The result of the callback is an application-supplied instance of the Receiver interface. Saxon will send events to this Receiver, representing the raw results of the xsl:result-document instruction. If the application wants results in the form of a document node generated using sequence normalization, then it must include a SequenceNormalizer in the output pipeline.

The ResultDocumentResolver is called for every xsl:result-document instruction whether or not it specifies an href attribute.

The implementation must be thread-safe (calls to xsl:result-document may occur in several threads concurrently). The returned Receiver may be called in a different thread.

If the application wishes to take action when the xsl:result-document instruction finishes, that is, when the results are available for use, then it should intercept the Receiver.close() call on the returned Receiver. This can be done (for example) by adding a CloseNotifier to the output pipeline, or by use of the SequenceNormalizer.onClose(java.util.List<net.sf.saxon.s9api.Action>) method.

This interface supersedes the OutputURIResolver interface provided in earlier Saxon releases. The OutputURIResolver was limited because it did not have access to the dynamic context, nor to the serialization parameters, and it did not handle raw output as required by the XSLT 3.0 specification, needed in particular to create JSON output documents.

Since:

9.9

Method Summary

Modifier and Type	Method and Description
Receiver	resolve(XPathContext context, String href, String baseUri, SerializationProperties properties) Saxon calls this method when an xsl:result-document instruction with an href attribute is evaluated.

Method Detail

resolve

Receiver resolve(XPathContext context,
                 String href,
                 String baseUri,
                 SerializationProperties properties)
          throws XPathException

Saxon calls this method when an xsl:result-document instruction with an href attribute is evaluated.

Note: it may be appropriate for the method to obtain a suitable Receiver by calling one of the static factory methods on the SerializerFactory class. A SerializerFactory can be obtained by calling context.getConfiguration().getSerializerFactory().

Parameters:

context - the dynamic evaluation context

href - the effective value of the href attribute of xsl:result-document instruction. This will be a zero-length string if the attribute is omitted.

baseUri - the base output URI of the transformation (typically, the destination of the principal output destination). This may be null if no base output URI is known. The recommended action if it is null is to use the href value alone if it is absolute URI, otherwise to raise an error (SaxonErrorCode.SXRD0002, since there is no W3C-defined code for the condition).

properties - the serialization properties defined explicitly or implicitly on the xsl:result-document instruction, together with information about character maps in the stylesheet that might be referenced. Serialization parameters can be ignored if the result document is not being serialized. However, if the serialization parameters include a validation factory, then this must not be ignored: a validator must be inserted at a suitable point in the output pipeline.

Returns:

a new instance of the Receiver class, which Saxon will then call to open the output document, and subsequently to close it. This Receiver will receive a sequence of events representing the raw result of the xsl:result-document instruction, as a regular event sequence conforming to the rules defined in RegularSequenceChecker.

The implementation should set the systemId property of the returned Receiver to the result of resolving the supplied href against the supplied baseUri. On return from this method, Saxon will check that the systemId is non-null and that it satisfies the uniqueness conditions imposed by the XSLT specification. Specifically, it is not permitted for two calls on xsl:result-document to use the same URI, and this URI must not be read in a call on doc() or document(), either before or after executing the xsl:result-document instruction.

Throws:

XPathException - if a result document cannot be opened