net.sf.saxon.s9api

Class NullDestination

java.lang.Object

net.sf.saxon.s9api.AbstractDestination

net.sf.saxon.s9api.NullDestination

All Implemented Interfaces:

Destination

public class NullDestination
extends AbstractDestination

A NullDestination is a Destination that discards all output sent to it.

Since:

9.9

Field Summary

Fields inherited from class net.sf.saxon.s9api.AbstractDestination

helper

Constructor Summary

Constructors

Constructor and Description
NullDestination()

Method Summary

Modifier and Type	Method and Description
void	close() Close the destination, allowing resources to be released.
Receiver	getReceiver(PipelineConfiguration pipe, SerializationProperties params) Return a Receiver.

Methods inherited from class net.sf.saxon.s9api.AbstractDestination

closeAndNotify, getDestinationBaseURI, onClose, setDestinationBaseURI

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NullDestination

public NullDestination()

Method Detail

getReceiver

public Receiver getReceiver(PipelineConfiguration pipe,
                            SerializationProperties params)

Description copied from interface: Destination

Return a 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.

Parameters:

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.

Returns:

the Receiver to which events are to be sent.

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.

close

public void close()

Description copied from interface: Destination

Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination.

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 Destination.onClose(net.sf.saxon.s9api.Action) action has been associated with the destination, this will be called after the destination is closed.