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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `OMElement` | `create(String namespace, String localPart, OMContainer parent, javax.xml.stream.XMLStreamReader reader, OMFactory factory)` Create an OMElement for this whole subtree.

- - ### Method Detail

    - #### create

          OMElement create(String namespace,
                           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` - the namespace URI, or the empty string if the element has no 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`

Copyright © The Apache Software Foundation. All Rights Reserved.