public interface Destination
In general a Destination
is designed to hold a single document.
It should therefore not be used as the destination of a query that produces multiple
documents. The effect of sending multiple documents to a Destination
depends on the kind of Destination
.
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
, however, 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.Configuration)
, 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. The close()
method is called by the system when
it finishes writing the document, and this causes 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.
|
Receiver |
getReceiver(Configuration config)
Return a Receiver.
|
Receiver getReceiver(Configuration config) throws SaxonApiException
config
- The Saxon 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.PipelineConfiguration
before calling
its open()
method. The caller is also responsible for ensuring that the sequence
of events sent to the Receiver represents a well-formed document: in particular the event
stream must include namespace events corresponding exactly to the namespace declarations
that are required. If the calling code cannot guarantee this, it should insert a
NamespaceReducer
into the pipeline in front of the returned
Receiver.SaxonApiException
- if the Receiver cannot be createdvoid 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.
SaxonApiException
- if any failure occursCopyright (c) 2004-2018 Saxonica Limited. All rights reserved.