Package org.apache.axis2.format

Interface DataSourceMessageBuilder

  • All Superinterfaces:
    Builder
    All Known Implementing Classes:
    BinaryBuilder, PlainTextBuilder
    public interface DataSourceMessageBuilder
extends Builder
    Message builder able to build messages from DataSource objects. This interface can be optionally implemented by Builder implementations that support building messages from DataSource objects. Since by definition the data from a DataSource can be read multiple times, this interface can be used by message builders to avoid storing the message content in memory.

    If a message builder implements this interface and the transport is able to provide the message payload as a data source, then the method defined by this interface should be preferred over the method defined by Builder.

    Implementing this interface helps optimizing message processing with transports that use messaging providers that store messages in memory or on the file system. Examples are JMS and VFS.

    The builder will typically expose the data source directly or indirectly through the returned OMElement, e.g. by adding to the tree an OMText or OMDataSource node referencing the data source. This means that the builder will not be able to guarantee that all streams requested from the data source are properly closed. Note that code accessing the returned OMElement can't be expected to take care of this since in many cases the fact that a data source is being used is completely transparent to that code. It is therefore the responsibility of the transport to make sure that all resources linked to the data source itself as well as any open stream requested from that data source are properly released after the message has been processed. Depending on the type of transport, there are three possible cases:

    1. All resources allocated to the data source or streams requested from it are memory based. In that case the garbage collector will take care of freeing these resources and the transport should simply pass the data source object to the builder.
    2. There are operation system resources linked to the data source and open streams will become invalid when these resources are freed, i.e. it is not required that all streams be closed explicitly. In this case the transport only needs to take care to properly dispose of the data source after the message has been processed by the Axis2 engine.
    3. Requesting a stream from the data source allocates operation system resources (e.g. a network connection) that remain linked to the stream, i.e. all streams requested from the data source must be closed properly. In that case the transport should use ManagedDataSourceFactory.create(DataSource) to wrap the original data source before passing it to the builder. After the message has been processed it should then call ManagedDataSource.destroy() on the wrapper to close all remaining open streams.