net.sf.saxon.lib

Interface OutputURIResolver

All Known Implementing Classes:

StandardOutputResolver

public interface OutputURIResolver

This interface defines an OutputURIResolver. This is a counterpart to the JAXP URIResolver, but is used to map the URI of a secondary result document to a Result object which acts as the destination for the new document.

From Saxon 9.9 this interface is obsolescent. It is unable to handle the full flexibility of XSLT 3.0, for example it cannot handle raw output, JSON serialization, or the item-separator serialization property. A new mechanism has therefore been introduced. This has a low-level interface XsltController.setResultDocumentResolver(ResultDocumentResolver), and a high-level counterpart at the s9api level, using the setResultDocumentHandler() method on Xslt30Transformer and XsltTransformer.

Method Summary

Modifier and Type	Method and Description
void	close(javax.xml.transform.Result result) Signal completion of the result document.
OutputURIResolver	newInstance() Get an instance of this OutputURIResolver class.
javax.xml.transform.Result	resolve(java.lang.String href, java.lang.String base) Resolve an output URI.

Method Detail

newInstance

OutputURIResolver newInstance()

Get an instance of this OutputURIResolver class.

This method is called every time an xsl:result-document instruction is evaluated (with an href attribute). The resolve() and close() methods will be called on the returned instance.

Note that in Saxon-EE, the xsl:result-document instruction executes asynchronously, which means that documents are not necessarily closed in the order they are opened, and multiple documents may be open at once.

If the OutputURIResolver is stateless (that is, it retains no information between resolve() and close()), then the same instance can safely be returned each time. For a stateful OutputURIResolver, it must either take care to be thread-safe (handling multiple invocations of xsl:result-document concurrently), or it must return a fresh instance of itself for each call.

resolve

javax.xml.transform.Result resolve(java.lang.String href,
                                   java.lang.String base)
                            throws javax.xml.transform.TransformerException

Resolve an output URI.

Parameters:

href - The relative URI of the output document. This corresponds to the href attribute of the xsl:result-document instruction.

base - The base URI that should be used. This is the Base Output URI, typically the URI of the principal output document

Returns:

a Result object representing the destination for the XML document. The method can also return null, in which case the standard output URI resolver will be used to create a Result object.

The systemId property of the returned Result object should normally be the result of resolving href (as a relative URI) against the value of base. This systemId is used to enforce the error conditions in the XSLT specification that disallow writing two result trees to the same destination, or reading from a destination that is written to in the same transformation. Setting the systemId to null, or to a deceptive value, will defeat these error checks (which can sometimes be useful). Equally, setting the systemId to the same value on repeated calls when different href/base arguments are supplied will cause a spurious error.

Throws:

javax.xml.transform.TransformerException - if any error occurs

close

void close(javax.xml.transform.Result result)
    throws javax.xml.transform.TransformerException

Signal completion of the result document. This method is called by the system when the result document has been successfully written. It allows the resolver to perform tidy-up actions such as closing output streams, or firing off processes that take this result tree as input. The original Result object is supplied to identify the document that has been completed. This allows the OutputURIResolver to be stateless, making it easier to handle the asynchronous calls of xsl:result-document that arise in Saxon-EE.

Parameters:

result - The result object returned by the previous call of resolve()

Throws:

javax.xml.transform.TransformerException - if any error occurs