public class JAXBOMDataSource extends AbstractPushOMDataSource implements QNameAwareOMDataSource
OMDataSource
backed by a JAXB object. This class can be used both for plain JAXB objects
and for JAXBElement
instances. It implements QNameAwareOMDataSource
so that it
can be used with OMFactory.createOMElement(OMDataSource)
, i.e. it is not necessary to
supply the QName during construction of the OMSourcedElement
. It also has full support
for XOP/MTOM. It is implemented as a push-style OMDataSource
so that an
OMSourcedElement
backed by an instance of this class can be expanded in an efficient way
(including the case where the JAXB object contains base64 binary data represented as
DataHandler
instances or byte arrays).
The JAXB object encapsulated by an instance of this class can be retrieved using
OMDataSourceExt.getObject()
. Note that modifying the JAXB object after passing it to the
constructor may result in unexpected behavior and should be avoided.
Instances of this class are non destructive, in the sense defined by
OMDataSourceExt.isDestructiveWrite()
.
LOSSY_PREFIX
Constructor and Description |
---|
JAXBOMDataSource(JAXBContext context,
Object object)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
OMDataSourceExt |
copy()
Create a copy of the data source.
|
String |
getLocalName()
Get the local name of the element represented by this data source.
|
String |
getNamespaceURI()
Get the namespace URI of the element represented by this data source.
|
Object |
getObject()
Get the object that backs this data source.
|
String |
getPrefix()
Get the namespace prefix of the element represented by this data source.
|
boolean |
isDestructiveWrite()
Returns true if writing the backing object is destructive.
|
void |
serialize(XMLStreamWriter writer)
Serializes element data directly to StAX writer.
|
getReader, isDestructiveRead
close, getProperty, getXMLBytes, getXMLInputStream, hasProperty, serialize, serialize, setProperty
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getReader, serialize, serialize
public JAXBOMDataSource(JAXBContext context, Object object)
context
- the JAXB context to which the object is knownobject
- the JAXB object; this may be a plain Java bean or a JAXBElement
public boolean isDestructiveWrite()
OMDataSourceExt
isDestructiveWrite
in interface OMDataSourceExt
public void serialize(XMLStreamWriter writer) throws XMLStreamException
OMDataSource
The implementation of this method must satisfy the following requirements:
XMLStreamWriter.writeStartDocument()
,
XMLStreamWriter.writeStartDocument(String)
,
XMLStreamWriter.writeStartDocument(String, String)
or
XMLStreamWriter.writeEndElement()
.
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.
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).
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.
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).
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:
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.
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:
OMSerializable.serialize(XMLStreamWriter, boolean)
method.
OMDataSource
is push-only (see AbstractPushOMDataSource
), then it
enables OMSourcedElement
to create OMText
nodes for the binary content in an
efficient way.
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:
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
.
serialize
in interface OMDataSource
writer
- destination writerXMLStreamException
public String getLocalName()
QNameAwareOMDataSource
getLocalName
in interface QNameAwareOMDataSource
null
if the local name is not knownpublic String getNamespaceURI()
QNameAwareOMDataSource
getNamespaceURI
in interface QNameAwareOMDataSource
null
if the namespace URI is not knownpublic String getPrefix()
QNameAwareOMDataSource
getPrefix
in interface QNameAwareOMDataSource
null
if the prefix is not known; the implementation is expected to
return an empty string if QNameAwareOMDataSource.getNamespaceURI()
returns an empty string (because
an element without namespace must not have a prefix)public Object getObject()
OMDataSourceExt
OMSourcedElement.getObject(Class)
instead.
Data sources that support non destructive read/write should return the object from which the XML is produced. Data sources with destructive read/write should return a non null value only if the backing object has not been consumed yet (even partially).
getObject
in interface OMDataSourceExt
getObject
in class AbstractOMDataSource
null
if the data source has no backing object or
if the backing object can't be accessed in a safe waypublic OMDataSourceExt copy()
OMDataSourceExt
OMInformationItem.clone(OMCloneOptions)
when the
OMCloneOptions.isCopyOMDataSources()
option is enabled. If the data source is
immutable and stateless, then it may return a reference to itself instead of creating a new
data source instance.copy
in interface OMDataSourceExt
copy
in class AbstractOMDataSource
null
if the data source can't be copied
(e.g. because it is destructive)Copyright © 2004–2022 The Apache Software Foundation. All rights reserved.