org.apache.axiom.om.OMDataSource Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/**
*
*/
package org.apache.axiom.om;
import javax.activation.DataHandler;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
import javax.xml.stream.XMLStreamWriter;
import org.apache.axiom.ext.stax.datahandler.DataHandlerProvider;
import org.apache.axiom.ext.stax.datahandler.DataHandlerWriter;
import org.apache.axiom.om.ds.AbstractPushOMDataSource;
import org.apache.axiom.om.impl.MTOMXMLStreamWriter;
import org.apache.axiom.util.stax.XMLStreamWriterUtils;
import org.apache.axiom.util.stax.xop.XOPDecodingStreamWriter;
import java.io.OutputStream;
import java.io.Writer;
/**
* Interface 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.
*/
public interface OMDataSource {
/**
* 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 {@link OMDataSourceExt} and
* {@link OMDataSourceExt#isDestructiveWrite()} returns false.
*
* @param output
* destination stream for element XML text
* @param format
* 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
*/
void serialize(OutputStream output, OMOutputFormat format) throws XMLStreamException;
/**
* 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 {@link OMDataSourceExt} and
* {@link OMDataSourceExt#isDestructiveWrite()} returns false.
*
* @param writer
* destination writer for element XML text
* @param format
* output format information (null if none; may be ignored if not
* supported by data binding even if supplied)
* @throws XMLStreamException
*/
void serialize(Writer writer, OMOutputFormat format) 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 {@link XMLStreamWriter#writeStartDocument()},
* {@link XMLStreamWriter#writeStartDocument(String)},
* {@link XMLStreamWriter#writeStartDocument(String, String)} or
* {@link 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 {@link XMLStreamWriter#writeStartElement(String)} or
* {@link XMLStreamWriter#writeEmptyElement(String)}. On the other hand, it MAY use the
* namespace unaware {@link 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
* {@link XMLStreamWriter#writeNamespace(String, String)} and
* {@link XMLStreamWriter#writeDefaultNamespace(String)}. It MUST NOT assume that the
* {@link XMLStreamWriter} performs any kind of namespace repairing (although that may be the
* case).
*
- In addition the implementation MAY use {@link XMLStreamWriter#setPrefix(String, String)}
* and {@link XMLStreamWriter#setDefaultNamespace(String)} to track the namespace declarations
* it generates, so that the namespace context maintained by the {@link 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
* {@link XMLStreamWriter#getPrefix(String)} and {@link 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
* {@link XMLStreamWriterUtils#writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)}
* or
* {@link 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 {@link XMLStreamWriter} is an {@link MTOMXMLStreamWriter}, then the implementation
* MAY use {@link MTOMXMLStreamWriter#prepareDataHandler(DataHandler)} and generate the
* necessary xop:Include elements itself. In this case, the implementation MAY use
* {@link MTOMXMLStreamWriter#isOptimized()} to check if XOP/MTOM is enabled at all.
* Alternatively, instead of handling {@link MTOMXMLStreamWriter} in a special way, the
* implementation MAY use the approach described in the next item. This works because
* {@link MTOMXMLStreamWriter} exposes the {@link DataHandlerWriter} extension. However, this
* causes a slight overhead because the stream is first XOP decoded and then reencoded again.
*
- If the {@link XMLStreamWriter} exposes the {@link DataHandlerWriter} extension, but is
* not an {@link MTOMXMLStreamWriter} (or is an {@link MTOMXMLStreamWriter}, but the
* implementation doesn't implement the approach described in the previous item), then the
* implementation MUST wrap the {@link XMLStreamWriter} in an {@link XOPDecodingStreamWriter}
* and write xop:Include elements to that wrapper, so that they can be translated into
* appropriate calls to the {@link DataHandlerWriter}. This requirement is important for two
* reasons:
*
* - It allows Axiom to respect the contract of the
* {@link OMSerializable#serialize(XMLStreamWriter, boolean)} method.
*
- If the {@link OMDataSource} is push-only (see {@link AbstractPushOMDataSource}), then it
* enables {@link OMSourcedElement} to create {@link OMText} nodes for the binary content in an
* efficient way.
*
* - In all other cases, the implementation MUST use
* {@link XMLStreamWriter#writeCharacters(String)} or
* {@link XMLStreamWriter#writeCharacters(char[], int, int)} to write the base64 encoded data to
* the stream.
*
* - The implementation MUST NOT call {@link XMLStreamWriter#close()}.
*
*
* On the other hand, the caller of this method (typically an {@link OMSourcedElement} instance)
* must ensure that the following requirements are satisfied:
*
* - The namespace context information provided by {@link XMLStreamWriter#getPrefix(String)}
* and {@link 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 {@link OMDataSourceExt} and
* {@link OMDataSourceExt#isDestructiveWrite()} returns false.
*
* @param xmlWriter
* destination writer
* @throws XMLStreamException
*/
void serialize(XMLStreamWriter xmlWriter) 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 {@link OMDataSourceExt} and
* {@link OMDataSourceExt#isDestructiveRead()} returns false.
*
* {@link OMSourcedElement} implementations are expected to call {@link XMLStreamReader#close()}
* on the returned reader as soon as the element is completely built.
*
* @return element parser
* @throws XMLStreamException
*/
XMLStreamReader getReader() throws XMLStreamException;
}