[Axis2] Axiom restructuring proposal

[Dennis Sosnoski <dm...@sosnoski.com>]

Right now the Axiom code is explicitly tied to StAX as the source of 
data for constructing the document tree. This creates problems in 
working with data binding frameworks which do not support marshalling 
via a StAX XMLStreamReader, and limits the usability of Axiom across a 
wider range of applications.

On the output side, Axiom generally uses XMLStreamWriter but also 
defines OMNode methods taking an OutputStream, a Writer, and a 
OMOutputImpl, as well as variations with OMOutputFormat included, and 
variations for serialize vs. serializeAndConsume. This proliferation of 
methods adds a lot of complexity to the interface while requiring all 
components of the tree to handle each of these forms of output. For 
components representing marshalling output from data binding frameworks 
these variations also force inefficient handling of output (for 
instance, by writing to an XMLStreamWriter when the framework can more 
efficiently write directly to an OutputStream).

I'd like to see Axiom instead define more generic interfaces for 
handling various data sources and output mechanisms. Really all that's 
required from potential data sources is that (1) the element holding 
some data can be converted to an Axiom tree structure on demand 
(possibly piecemeal, as in the case of elements backed by an 
XMLStreamReader), and (2) the data source can write itself to an 
OutputStream, Writer and/or XMLStreamWriter. We can abstract out these 
operations to the data source for unexpanded elements. This will allow 
cleaner handling of data binding framework extensions to Axis2, while 
also allowing flexibility for developers who have their own ways of 
processing XML (see http://issues.apache.org/jira/browse/AXIS2-483 for 
an example).

Here's a first cut at an interface for the data source of an unexpanded 
element:

public interface BackingData {
    void expandElement(OMElement element); // expand the element information
    void expandNextContent(OMElement element); // expand next content 
item of element
    boolean isReusable(); // check if data source can be used repeatedly 
(may avoid the need for expansion if so)
    void serialize(SerializationTarget target); // serialize using any 
supported approach
}

When the expandElement() method of the BackingData is called, it will 
populate at least the element's attributes and namespaces information. 
When the expandNextContent() method is called, it would be the 
responsibility of that BackingData instance to construct at least the 
next content node of the element. If that next content node is an 
element, the BackingData would be able to leave that element unexpanded 
and attach itself to the element. The idea here is to be flexible enough 
to handle both elements backed by an XMLStreamReader and those backed by 
data binding or an alternative form of XML handling. The 
expandElement()/expandNextContent() methods would need to be called in 
proper document order, so that if the data is coming from an 
XMLStreamReader it will be read sequentially (no expandNextContent() 
higher in the tree until all the content before that point in document 
order has been expanded).

Here's a first cut at an interface for the serialization handling:

public inteface SerializationTarget {
    OutputStream getOutputStream(); // return output stream if available 
for direct output, otherwise null
    Writer getWriter(); // return writer if available for direct output, 
otherwise null
    XMLStreamWriter getXMLWriter(); // return XMLStreamWriter (always 
available)

    boolean isAttachable(String contentType, long estimatedSize); // 
check if "optimizable" data should be sent as attachment
    String addAttachment(String contentType, InputStream is);  // add 
attachment in the form of a stream (returns content id)
    String addAttachment(String contentType, byte[] bytes);  // add 
attachment in the form of a byte array (returns content id)
}

The first part of this interface is the basic output handling. The rule 
here is that every SerializationTarget will supply an XMLStreamWriter on 
demand, but will also supply either an OutputStream or a Writer (so 
either of the first two methods may return null, but not both). The 
principle here is that many forms of XML handling can write directly to 
an output stream or writer but not to an XMLStreamWriter, while the 
latter provides a flush() method which should make it safe for the 
output stream or writer to be used independently for XML fragments - so 
use the XMLStreamWriter for the envelope, if that's what you want, but 
still use the stream or writer to output the body of the document.

The second part of this interface deals with attachments. It gives the 
SerializationTarget (which would be transport-dependent, of course) the 
control over what actually gets sent as an attachment, and provides the 
data to be output as an attachment in the form of either a stream or an 
array of bytes. This would allow us to fix the current broken output 
behavior which forces generation of a fully-expanded OM tree for every 
message being sent, just so the transport code can check for anything it 
wants to send as an attachment.

I'm planning to make the chat later today if anyone wants to discuss 
these ideas (and also via email exchange, of course).

  - Dennis

-- 
Dennis M. Sosnoski
SOA, Web Services, and XML
Training and Consulting
http://www.sosnoski.com - http://www.sosnoski.co.nz
Seattle, WA +1-425-296-6194 - Wellington, NZ +64-4-298-6117