Message builder able to build messages from {@link DataSource} objects.This interface can be optionally implemented by {@link Builder}implementations that support building messages from {@link DataSource} objects.Since by definition the data from a {@link DataSource} can be read multipletimes, 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 {@link 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 {@link OMElement}, e.g. by adding to the tree an {@link org.apache.axiom.om.OMText}or {@link org.apache.axiom.om.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 {@link OMElement} can't be expected to take care of this since in many cases the factthat 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:
- 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.
- 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.
- 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 {@link ManagedDataSourceFactory#create(DataSource)} to wrap the original data sourcebefore passing it to the builder. After the message has been processed it should then call {@link ManagedDataSource#destroy()} on the wrapper to close all remainingopen streams.