org.apache.axiom.om.ds
Class AbstractPullOMDataSource
java.lang.Object
org.apache.axiom.om.ds.AbstractOMDataSource
org.apache.axiom.om.ds.AbstractPullOMDataSource
- All Implemented Interfaces:
- OMDataSource, OMDataSourceExt
- Direct Known Subclasses:
- WrappedTextNodeOMDataSource
public abstract class AbstractPullOMDataSource
- extends AbstractOMDataSource
Base class for OMDataSourceExt
implementations that can easily produce the content as an
XMLStreamReader
and that don't implement any kind of optimization for serializing the
content.
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
AbstractPullOMDataSource
public AbstractPullOMDataSource()
isDestructiveWrite
public final boolean isDestructiveWrite()
- Description copied from interface:
OMDataSourceExt
- Returns true if writing the backing object is destructive.
An example of an object with a destructive write is an InputStream.
The owning OMSourcedElement uses this information to detemine if OM tree
expansion is needed when writing the OMDataSourceExt.
- Returns:
- boolean
serialize
public final void serialize(XMLStreamWriter xmlWriter)
throws XMLStreamException
- Description copied from interface:
OMDataSource
- Serializes element data directly to StAX writer.
The implementation of this method must satisfy the following requirements:
- The implementation MUST NOT not write any start document or end document event, i.e. it
MUST NOT use
XMLStreamWriter.writeStartDocument()
,
XMLStreamWriter.writeStartDocument(String)
,
XMLStreamWriter.writeStartDocument(String, String)
or
XMLStreamWriter.writeEndElement()
.
- The implementation MUST output a single element (hereafter called the root element). It
MUST NOT output any other content before or after that element.
- The implementation MUST specify the namespace URI when writing an element, i.e. it MUST
NOT use the namespace unaware methods
XMLStreamWriter.writeStartElement(String)
or
XMLStreamWriter.writeEmptyElement(String)
. On the other hand, it MAY use the
namespace unaware XMLStreamWriter.writeAttribute(String, String)
method, provided
that the specified name is an NCName.
- The implementation MUST ensure that the produced XML is well formed with respect to
namespaces, i.e. it MUST generate the required namespace declarations using
XMLStreamWriter.writeNamespace(String, String)
and
XMLStreamWriter.writeDefaultNamespace(String)
. It MUST NOT assume that the
XMLStreamWriter
performs any kind of namespace repairing (although that may be the
case).
- In addition the implementation MAY use
XMLStreamWriter.setPrefix(String, String)
and XMLStreamWriter.setDefaultNamespace(String)
to track the namespace declarations
it generates, so that the namespace context maintained by the XMLStreamWriter
accurately reflects the namespace context in the output document. However, it MUST NOT call
these methods before the start of the root element or after the end of the root element.
- Since the element may be serialized as part of a larger document, the implementation MUST
take into account the pre-existing namespace context (which can be queried using
XMLStreamWriter.getPrefix(String)
and XMLStreamWriter.getNamespaceContext()
).
This means that the implementation MUST NOT assume that the empty prefix is bound to the
empty namespace URI. Therefore if the implementation outputs elements that have no namespace,
it MUST generate namespace declarations of the form xmlns="" in the appropriate
locations. In addition it MAY use the namespace context information to minimize the number of
generated namespace declarations (by reusing already bound prefixes).
- If the implementation produces base64 binary data (that could be optimized using
XOP/MTOM), then it SHOULD use
XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)
or
XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)
to write the data to the stream. If this is not possible (e.g. because the content is
produced by a third party library that is not aware of these APIs), then the implementation
MUST use the following approach:
- If the
XMLStreamWriter
is an MTOMXMLStreamWriter
, then the implementation
MAY use MTOMXMLStreamWriter.prepareDataHandler(DataHandler)
and generate the
necessary xop:Include elements itself. In this case, the implementation MAY use
MTOMXMLStreamWriter.isOptimized()
to check if XOP/MTOM is enabled at all.
Alternatively, instead of handling MTOMXMLStreamWriter
in a special way, the
implementation MAY use the approach described in the next item. This works because
MTOMXMLStreamWriter
exposes the DataHandlerWriter
extension. However, this
causes a slight overhead because the stream is first XOP decoded and then reencoded again.
- If the
XMLStreamWriter
exposes the DataHandlerWriter
extension, but is
not an MTOMXMLStreamWriter
(or is an MTOMXMLStreamWriter
, but the
implementation doesn't implement the approach described in the previous item), then the
implementation MUST wrap the XMLStreamWriter
in an XOPDecodingStreamWriter
and write xop:Include elements to that wrapper, so that they can be translated into
appropriate calls to the DataHandlerWriter
. This requirement is important for two
reasons:
- In all other cases, the implementation MUST use
XMLStreamWriter.writeCharacters(String)
or
XMLStreamWriter.writeCharacters(char[], int, int)
to write the base64 encoded data to
the stream.
On the other hand, the caller of this method (typically an OMSourcedElement
instance)
must ensure that the following requirements are satisfied:
- The namespace context information provided by
XMLStreamWriter.getPrefix(String)
and XMLStreamWriter.getNamespaceContext()
MUST accurately reflect the actual
namespace context at the location in the output document where the root element is
serialized. Note that this requirement may be relaxed if the caller implements some form of
namespace repairing.
It is assumed that this method consumes the content (i.e. destroys the backing object) unless
the data source also implements OMDataSourceExt
and
OMDataSourceExt.isDestructiveWrite()
returns false
.
- Parameters:
xmlWriter
- destination writer
- Throws:
XMLStreamException
Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.