Class JAXBOMDataSource
- All Implemented Interfaces:
OMDataSource,OMDataSourceExt,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().
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncopy()Create a copy of the data source.Get the local name of the element represented by this data source.Get the namespace URI of the element represented by this data source.Get the object that backs this data source.Get the namespace prefix of the element represented by this data source.booleanReturns true if writing the backing object is destructive.voidserialize(XMLStreamWriter writer) Serializes element data directly to StAX writer.Methods inherited from class org.apache.axiom.om.ds.AbstractPushOMDataSource
getReader, isDestructiveReadMethods inherited from class org.apache.axiom.om.ds.AbstractOMDataSource
close, getProperty, getXMLBytes, getXMLInputStream, hasProperty, serialize, serialize, setPropertyMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface org.apache.axiom.om.OMDataSource
getReader, serialize, serialize
-
Constructor Details
-
JAXBOMDataSource
Constructor.- Parameters:
context- the JAXB context to which the object is knownobject- the JAXB object; this may be a plain Java bean or aJAXBElement
-
-
Method Details
-
isDestructiveWrite
public boolean isDestructiveWrite()Description copied from interface:OMDataSourceExtReturns 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.- Specified by:
isDestructiveWritein interfaceOMDataSourceExt- Returns:
- boolean
-
serialize
Description copied from interface:OMDataSourceSerializes 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)orXMLStreamWriter.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)orXMLStreamWriter.writeEmptyElement(String). On the other hand, it MAY use the namespace unawareXMLStreamWriter.writeAttribute(String, String)method, provided that the specified name is anNCName. - 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)andXMLStreamWriter.writeDefaultNamespace(String). It MUST NOT assume that theXMLStreamWriterperforms any kind of namespace repairing (although that may be the case). - In addition the implementation MAY use
XMLStreamWriter.setPrefix(String, String)andXMLStreamWriter.setDefaultNamespace(String)to track the namespace declarations it generates, so that the namespace context maintained by theXMLStreamWriteraccurately 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)andXMLStreamWriter.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 formxmlns=""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). - To produce base64 binary data (that could be optimized using XOP/MTOM), the
implementation MUST use one of the following approaches:
- Use the
BlobWriterextension (or alternatively theXMLStreamWriterUtils.writeBlob(XMLStreamWriter, Blob, String, boolean)orXMLStreamWriterUtils.writeBlob(XMLStreamWriter, BlobProvider, String, boolean)utility methods) to write the data to the stream. This is the preferred approach, unless the content is produced by a third party library that is not aware of these APIs. - Cast the
XMLStreamWriterto anMTOMXMLStreamWriter, useMTOMXMLStreamWriter.prepareBlob(Blob)and generate the necessaryxop:Includeelements. In this case, the implementation MAY useMTOMXMLStreamWriter.isOptimized()to check if XOP/MTOM is enabled at all.
- Use the
- The implementation MUST NOT call
XMLStreamWriter.close().
On the other hand, the caller of this method (typically an
OMSourcedElementinstance) must ensure that the following requirements are satisfied:- The namespace context information provided by
XMLStreamWriter.getPrefix(String)andXMLStreamWriter.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
OMDataSourceExtandOMDataSourceExt.isDestructiveWrite()returnsfalse.- Specified by:
serializein interfaceOMDataSource- Parameters:
writer- destination writer- Throws:
XMLStreamException- if an exception was thrown bywriter; implementations should throw unchecked exceptions in all other cases
- The implementation MUST NOT not write any start document or end document event, i.e. it
MUST NOT use
-
getLocalName
Description copied from interface:QNameAwareOMDataSourceGet the local name of the element represented by this data source.- Specified by:
getLocalNamein interfaceQNameAwareOMDataSource- Returns:
- the local name of the element or
nullif the local name is not known
-
getNamespaceURI
Description copied from interface:QNameAwareOMDataSourceGet the namespace URI of the element represented by this data source.- Specified by:
getNamespaceURIin interfaceQNameAwareOMDataSource- Returns:
- the namespace URI of the element, the empty string if the element has no namespace or
nullif the namespace URI is not known
-
getPrefix
Description copied from interface:QNameAwareOMDataSourceGet the namespace prefix of the element represented by this data source.- Specified by:
getPrefixin interfaceQNameAwareOMDataSource- Returns:
- the prefix of the element, the empty string if the element has no prefix or
nullif the prefix is not known; the implementation is expected to return an empty string ifQNameAwareOMDataSource.getNamespaceURI()returns an empty string (because an element without namespace must not have a prefix)
-
getObject
Description copied from interface:OMDataSourceExtGet the object that backs this data source. Application code should in general not call this method directly, but useOMSourcedElement.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).
- Specified by:
getObjectin interfaceOMDataSourceExt- Overrides:
getObjectin classAbstractOMDataSource- Returns:
- the backing object, or
nullif the data source has no backing object or if the backing object can't be accessed in a safe way
-
copy
Description copied from interface:OMDataSourceExtCreate a copy of the data source. This method is used byOMInformationItem.clone(OMCloneOptions)when theOMCloneOptions.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.- Specified by:
copyin interfaceOMDataSourceExt- Overrides:
copyin classAbstractOMDataSource- Returns:
- the copy of the data source, or
nullif the data source can't be copied (e.g. because it is destructive)
-