Interface OMDataSource
-
- All Known Subinterfaces:
OMDataSourceExt,QNameAwareOMDataSource
- All Known Implementing Classes:
AbstractOMDataSource,AbstractPullOMDataSource,AbstractPushOMDataSource,BlobOMDataSource,JAXBOMDataSource,StringOMDataSource,WrappedTextNodeOMDataSource,WrappedTextNodeOMDataSourceFromDataSource,WrappedTextNodeOMDataSourceFromReader
public interface OMDataSourceInterface to arbitrary source of XML element data. This provides the hook for using a general data source (such as data binding frameworks) as the backing source of data for an element. This interface should not be implemented directly; instead create a subclass ofAbstractOMDataSource,AbstractPullOMDataSourceorAbstractPushOMDataSource.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description XMLStreamReadergetReader()Get parser for element data.voidserialize(OutputStream output, OMOutputFormat format)Deprecated.voidserialize(Writer writer, OMOutputFormat format)Deprecated.voidserialize(XMLStreamWriter writer)Serializes element data directly to StAX writer.
-
-
-
Method Detail
-
serialize
void serialize(OutputStream output, OMOutputFormat format) throws XMLStreamException
Deprecated.Serializes element data directly to stream.It is assumed that this method consumes the content (i.e. destroys the backing object) unless the data source also implements
OMDataSourceExtandOMDataSourceExt.isDestructiveWrite()returnsfalse.- Parameters:
output- destination stream for element XML textformat- Output format information. The implementation must use this information to choose the correct character set encoding when writing to the output stream. This parameter must not be null.- Throws:
XMLStreamException
-
serialize
void serialize(Writer writer, OMOutputFormat format) throws XMLStreamException
Deprecated.Serializes element data directly to writer.It is assumed that this method consumes the content (i.e. destroys the backing object) unless the data source also implements
OMDataSourceExtandOMDataSourceExt.isDestructiveWrite()returnsfalse.- Parameters:
writer- destination writer for element XML textformat- output format information (nullif none; may be ignored if not supported by data binding even if supplied)- Throws:
XMLStreamException
-
serialize
void serialize(XMLStreamWriter writer) throws XMLStreamException
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)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
DataHandlerWriterextension (or alternatively theXMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)orXMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, 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.prepareDataHandler(DataHandler)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.- 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
-
getReader
XMLStreamReader getReader() throws XMLStreamException
Get parser for element data. In the general case this may require the data source to serialize data as XML text and then parse that text.It is assumed that this method consumed the content (i.e. destroys the backing object) unless the data source also implements
OMDataSourceExtandOMDataSourceExt.isDestructiveRead()returnsfalse.OMSourcedElementimplementations are expected to callXMLStreamReader.close()on the returned reader as soon as the element is completely built.- Returns:
- element parser
- Throws:
XMLStreamException
-
-