Package 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 `Outputter` 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 `Outputter.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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Receiver` | `resolve​(XPathContext context, java.lang.String href, java.lang.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,
                           java.lang.String href,
                           java.lang.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