public interface Destination
A Destination is either a tree destination or a raw destination. A tree destination
performs sequence normalization on the stream of events passed to it, to construct
a tree rooted at a single XDM document node, as defined in the W3C serialization specification
(even if the destination is not actually a serializer). A raw destination omits this step.
Examples of tree destinations are those designed to accept XML: DOMDestination,
SAXDestination, XdmDestination, SchemaValidator.
The Serializer acts as a tree destination when the output methods XML, HTML, XHTML, or TEXT
are used, but as a raw destination when the output method is JSON or ADAPTIVE.
The interface Destination has some similarities with the JAXP
Result class. It differs, however, in that implementations
of this interface can be written by users or third parties to define new kinds of
destination, and any such implementation can be supplied to the Saxon methods that
take a Destination as an argument.
Implementing a new Destination will generally require access
to implementation-level classes and methods within the Saxon product. The only method that
needs to be supplied is getReceiver(net.sf.saxon.event.PipelineConfiguration, net.sf.saxon.serialize.SerializationProperties), which returns an instance of
Receiver, and unless you use an existing implementation of
Receiver, you will need to handle internal Saxon concepts such as name codes
and name pools.
In general a Destination is not thread-safe (cannot be used from more than one thread), and is not serially reusable. So a Destination should only be used once. A Destination supplied to Saxon may be modified by Saxon.
The close() method is called by the system when
it finishes writing the document, and this should cause all resources held by the Destination
to be released.
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Close the destination, allowing resources to be released.
|
void |
closeAndNotify()
Close the destination and notify all registered listeners that it has been closed.
|
java.net.URI |
getDestinationBaseURI()
Get the base URI of the resource being written to this destination
|
Receiver |
getReceiver(PipelineConfiguration pipe,
SerializationProperties params)
Return a
Receiver. |
void |
onClose(Action listener)
Register a listener to be notified when a
Receiver linked to this destination is closed. |
void |
setDestinationBaseURI(java.net.URI baseURI)
Set the base URI of the resource being written to this destination
|
void setDestinationBaseURI(java.net.URI baseURI)
baseURI - the base URI to be usedjava.net.URI getDestinationBaseURI()
Receiver getReceiver(PipelineConfiguration pipe, SerializationProperties params) throws SaxonApiException
Receiver. Saxon calls this method to obtain a Receiver, to which it then sends
a sequence of events representing an XDM value. The method is intended
primarily for internal use, and may give poor diagnostics if used incorrectly.
This method is normally only called once. However, in the case where a stylesheet includes
a call of xsl:result-document with no href attribute (or with an
href attribute that resolves to the base output URI of the transformation), the
method may be called a second time (with a potentially different set of serialization parameters,
and perhaps a different validation request) to return a second Receiver, which will typically
write to the same destination. The XSLT rules ensure that it is not possible to write principal and
secondary output to the same destination, so only one of these Receivers will actually be used.
pipe - The pipeline configuration. This is supplied so that the destination can
use information from the configuration (for example, a reference to the name pool)
to construct or configure the returned Receiver.params - Serialization parameters known to the caller of the method; typically,
output properties defined in a stylesheet or query. These will mainly
be of interest if the destination is performing serialization, but some
properties (such as item-separator) are also used in other
situations. These properties are typically subordinate to any properties
defined on the (serializer) destination itself: for example if indent=yes
was explicitly specified on a Serializer, this takes precedence
over indent=no defined in a query or stylesheet.
The SerializationProperties object may also contain a factory object for
generating a validator to add to the output pipeline. The Destination object
is responsible for instantiating this validator and inserting it into the pipeline.
In most cases this is done by invoking the helper method
SerializationProperties.makeSequenceNormalizer(Receiver). Validation can be skipped
in the case of non-XML destinations.
It is the caller's responsibility to
initialize this Receiver with a PipelineConfiguration before calling
its open() method.
The Receiver is expected to handle a regular event sequence as defined in
RegularSequenceChecker. It is the caller's responsibility to
ensure that the sequence of calls to the Receiver satisfies these rules, and it
is the responsibility of the implementation to accept any sequence conforming these rules;
the implementation is not expected to check that the sequence is valid, but it can do so
if it wishes by inserting a RegularSequenceChecker into the pipeline.
The sequence of events passed to the Receiver represents the raw results of
the query or transformation. If the Destination is to perform sequence normalization,
this is typically done by returning a SequenceNormalizer as the
result of this method.
The returned Receiver is responsible for ensuring that when its Receiver.close()
method is called, this results in all registered onClose actions being invoked.
An implementation returning a SequenceNormalizer can achieve this by registering
the actions with the SequenceNormalizer.onClose(java.util.List<net.sf.saxon.s9api.Action>) method.
Only a single call on this method will be made during the lifetime of the Destination
object, with the exception of the case noted above where a secondary result document is written
to the same destination as the principal transformation result.
SaxonApiException - if the Receiver cannot be createdvoid onClose(Action listener)
Receiver linked to this destination is closed.
Example: destination.onClose(() -> System.out.println("Finished writing to " + uri)
The method must be called before the call on getReceiver(PipelineConfiguration, SerializationProperties); the
effect of calling it after getting a Receiver, but before closing the
Receiver, is undefined.
listener - an object to be notified when writing to the destination
is successfully completedvoid closeAndNotify()
throws SaxonApiException
close()
to close the destination, then it calls Consumer.accept(T) on each of the
listeners in turn to notify the fact that it has been closed.SaxonApiException - if the close() method throws SaxonApiException.void close()
throws SaxonApiException
The close() method should not cause any adverse effects if it is called more than
once. If any other method is called after the close() call, the results are undefined.
This means that a Destination is not, in general, serially reusable.
If an onClose(net.sf.saxon.s9api.Action) action has been associated with the destination,
this will be called after the destination is closed.
SaxonApiException - if any failure occursCopyright (c) 2004-2020 Saxonica Limited. All rights reserved.