org.apache.axiom.om.impl.builder

Interface CustomBuilder

All Known Implementing Classes:

ByteArrayCustomBuilder

public interface CustomBuilder

A Custom Builder is registered on the StAXBuilder for a particular QName or payload. When the QName or payload is encountered, the CustomBuilder will build the OMElement or OMSourcedElement for the StAXBuilder.

See Also:

StAXBuilder.registerCustomBuilder(javax.xml.namespace.QName, int, CustomBuilder), StAXBuilder.registerCustomBuilderForPayload(CustomBuilder)

Method Summary

Modifier and Type	Method and Description
OMElement	create(java.lang.String namespace, java.lang.String localPart, OMContainer parent, javax.xml.stream.XMLStreamReader reader, OMFactory factory) Create an OMElement for this whole subtree.

Method Detail

create

OMElement create(java.lang.String namespace,
                 java.lang.String localPart,
                 OMContainer parent,
                 javax.xml.stream.XMLStreamReader reader,
                 OMFactory factory)
          throws OMException

Create an OMElement for this whole subtree. A null is returned if the default StAXBuilder behavior should be used.

Parameters:

namespace -

localPart -

parent -

reader - The stream reader to read the StAX events from. The data read from this reader always represents plain XML, even if the original document was XOP encoded. The reader optionally implements the DataHandlerReader extension to give the custom builder access to optimized binary data. This is appropriate for custom builders that support DataHandlerReader or in cases where there is no other option than to transfer binary data as base64 encoded character data.

However, if the custom builder interacts with a third party library that supports XOP, it may want to use that encoding to optimize the transfer of binary data. To do so, the custom builder MUST use XOPUtils.getXOPEncodedStream(XMLStreamReader) to get an XOP encoded stream. This guarantees that the original reader is wrapped or unwrapped properly and also that the custom builder correctly gets access to the attachments, regardless of the type of the original reader. In particular, the custom builder MUST NOT attempt to retrieve attachments through the OMAttachmentAccessor that may be implemented by the builder (because this wouldn't work if the builder was created from an XMLStreamReader implementing the DataHandlerReader extension).

The implementation MUST NOT assume that reader is the original reader returned by the StAX implementation. In general, it will be a wrapper around the original reader, e.g. one added by the StAXDialect implementation. If the method requires access to the original parser (e.g. to pass the XMLStreamReader object to another library that uses some special optimizations for particular parser implementations), it SHOULD use XMLStreamReaderUtils.getOriginalXMLStreamReader(XMLStreamReader) to unwrap the reader. If the method solely relies on the conformance of the reader to the StAX specification, it SHOULD NOT attempt to unwrap it.

If the implementation requires both an XOP encoded stream and wants to get access to the original reader, it should invoke XMLStreamReaderUtils.getOriginalXMLStreamReader(XMLStreamReader) after XOPUtils.getXOPEncodedStream(XMLStreamReader).

Returns:

null or OMElement

Throws:

OMException