[AXIOM-94] CustomBuilder interface is not well defined for optimized binary data

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 1.2.9
• Assignee: Andreas Veithen
• Reporter: Andreas Veithen
• Created: 19/May/10 20:27
• Updated: 27/Mar/11 11:43
• Resolved: 23/May/10 12:02

Description

The CustomBuilder contract doesn't specify very well how the implementation is supposed to handle documents with optimized binary data (either from an XOP encoded document or exposed by the OMConstants.DATA_HANDLER / DataHandlerReader extension).

Situation in Axiom 1.2.8: In all cases, the XMLStreamReader passed to the CustomBuilder is the original reader passed to StAXOMBuilder. This means that if the document/message is XOP, the XMLStreamReader passed to CustomBuilder represents an XOP encoded stream. However, in other cases the XMLStreamReader may expose optimized binary data using the OMConstants.DATA_HANDLER property. Therefore the CustomBuilder needs to be able to handle two different cases.

Current situation (since r795595): If the original document/message is XOP, then the XMLStreamReader passed to CustomBuilder will now be a XOPDecodingStreamReader exposing the optimized binary data through a DataHandlerReader. Thus, in all cases, the XMLStreamReader passed to CustomBuilder represents plain XML with optional support for DataHandlerReader. That is consistent and suitable for CustomBuilders that require the binary data as base64 encoded character data or that support the Axiom specific DataHandlerReader extension. However, it makes things more difficult for CustomBuilders that require an XOP encoded stream. This is often required when interacting with third-party libraries to make sure that binary data is handled efficiently. An example of this is JAXB2 (see also WSCOMMONS-344).

Suggested fix: Complete the Javadoc of the CustomBuilder to specify how StAXOMBuilder delivers optimized binary data and how the implementation can get an XOP encoded stream. For the last part, it is necessary to cover the following cases:

1. If the XMLStreamReader passed to StAXOMBuilder was created by parsing a plain XML document, then no special action is required.
2. If the original document is XOP encoded, then the XOPDecodingStreamReader needs to be unwrapped to get access to the original stream.
3. If the XMLStreamReader passed to StAXOMBuilder implements the DataHandlerReader extension, then it needs to be wrapped with an XOPEncodingStreamReader.

Obviously, there should be a utility method implementing this algorithm.