org.apache.axis2.format
Interface DataSourceMessageBuilder
- All Superinterfaces:
- org.apache.axis2.builder.Builder
- All Known Implementing Classes:
- BinaryBuilder, PlainTextBuilder
public interface DataSourceMessageBuilder
- extends org.apache.axis2.builder.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:
- 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
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.
Method Summary |
org.apache.axiom.om.OMElement |
processDocument(javax.activation.DataSource dataSource,
java.lang.String contentType,
org.apache.axis2.context.MessageContext messageContext)
|
Methods inherited from interface org.apache.axis2.builder.Builder |
processDocument |
processDocument
org.apache.axiom.om.OMElement processDocument(javax.activation.DataSource dataSource,
java.lang.String contentType,
org.apache.axis2.context.MessageContext messageContext)
throws org.apache.axis2.AxisFault
- Throws:
org.apache.axis2.AxisFault
Copyright © 2004-2009 The Apache Software Foundation. All Rights Reserved.