org.apache.axiom.om.ds

Class InputStreamDataSource

java.lang.Object

org.apache.axiom.om.ds.OMDataSourceExtBase

org.apache.axiom.om.ds.InputStreamDataSource

All Implemented Interfaces:

OMDataSource, OMDataSourceExt

public class InputStreamDataSource
extends OMDataSourceExtBase

InputStream is an example OMDataSourceExt. Use it to insert a (InputStream, encoding) into an OM Tree. This data source is useful for placing an InputStream into an OM tree, instead of having a deeply nested tree.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	InputStreamDataSource.Data Object containing the InputStream/encoding pair

Field Summary

Fields

Modifier and Type	Field and Description
private static int	BUFFER_LEN
(package private) InputStreamDataSource.Data	data

Fields inherited from class org.apache.axiom.om.ds.OMDataSourceExtBase

map

Fields inherited from interface org.apache.axiom.om.OMDataSourceExt

LOSSY_PREFIX

Constructor Summary

Constructors

Constructor and Description
InputStreamDataSource(java.io.InputStream is, java.lang.String encoding) Constructor

Method Summary

Modifier and Type	Method and Description
void	close() Close the DataSource and free its resources.
OMDataSourceExt	copy() Return a InputStreamDataSource backed by a ByteArrayInputStream
java.lang.Object	getObject() Get the object that backs this data source.
javax.xml.stream.XMLStreamReader	getReader() Get parser for element data.
byte[]	getXMLBytes(java.lang.String encoding) Returns a byte[] representing the xml data
java.io.InputStream	getXMLInputStream(java.lang.String encoding) Returns a InputStream representing the xml data
private static void	inputStream2OutputStream(java.io.InputStream is, java.io.OutputStream os) Private utility to write the InputStream contents to the OutputStream.
boolean	isDestructiveRead() Returns true if reading the backing object is destructive.
boolean	isDestructiveWrite() Returns true if writing the backing object is destructive.
void	serialize(java.io.OutputStream output, OMOutputFormat format) Serializes element data directly to stream.
void	serialize(javax.xml.stream.XMLStreamWriter xmlWriter) Serializes element data directly to StAX writer.

Methods inherited from class org.apache.axiom.om.ds.OMDataSourceExtBase

getProperty, hasProperty, serialize, setProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

data

InputStreamDataSource.Data data

BUFFER_LEN

private static final int BUFFER_LEN

See Also:

Constant Field Values

Constructor Detail

InputStreamDataSource

public InputStreamDataSource(java.io.InputStream is,
                             java.lang.String encoding)

Constructor

Parameters:

is -

encoding -

Method Detail

serialize

public void serialize(java.io.OutputStream output,
                      OMOutputFormat format)
               throws javax.xml.stream.XMLStreamException

Description copied from 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 OMDataSourceExt and OMDataSourceExt.isDestructiveWrite() returns false.

Specified by:

serialize in interface OMDataSource

Overrides:

serialize in class OMDataSourceExtBase

Parameters:

output - destination stream for element XML text

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:

javax.xml.stream.XMLStreamException

serialize

public void serialize(javax.xml.stream.XMLStreamWriter xmlWriter)
               throws javax.xml.stream.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:
    • It allows Axiom to respect the contract of the OMSerializable.serialize(XMLStreamWriter, boolean) method.
    • If the OMDataSource is push-only (see AbstractPushOMDataSource), then it enables OMSourcedElement to create OMText nodes for the binary content in an efficient way.
  • 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.

Specified by:

serialize in interface OMDataSource

Overrides:

serialize in class OMDataSourceExtBase

Parameters:

xmlWriter - destination writer

Throws:

javax.xml.stream.XMLStreamException

getReader

public javax.xml.stream.XMLStreamReader getReader()
                                           throws javax.xml.stream.XMLStreamException

Description copied from interface: OMDataSource

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 OMDataSourceExt and OMDataSourceExt.isDestructiveRead() returns false.

Returns:

element parser

Throws:

javax.xml.stream.XMLStreamException

getXMLInputStream

public java.io.InputStream getXMLInputStream(java.lang.String encoding)
                                      throws java.io.UnsupportedEncodingException

Description copied from interface: OMDataSourceExt

Returns a InputStream representing the xml data

Specified by:

getXMLInputStream in interface OMDataSourceExt

Overrides:

getXMLInputStream in class OMDataSourceExtBase

Parameters:

encoding - String encoding of InputStream

Returns:

InputStream

Throws:

java.io.UnsupportedEncodingException

getObject

public java.lang.Object getObject()

Description copied from interface: OMDataSourceExt

Get the object that backs this data source. Application code should in general not call this method directly, but use 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).

Returns:

the backing object, or null if the data source has no backing object or if the backing object can't be accessed in a safe way

isDestructiveRead

public boolean isDestructiveRead()

Description copied from interface: OMDataSourceExt

Returns true if reading the backing object is destructive. An example of an object with a destructive read is an InputSteam. The owning OMSourcedElement uses this information to detemine if OM tree expansion is needed when reading the OMDataSourceExt.

Returns:

boolean

isDestructiveWrite

public 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

getXMLBytes

public byte[] getXMLBytes(java.lang.String encoding)
                   throws java.io.UnsupportedEncodingException

Description copied from interface: OMDataSourceExt

Returns a byte[] representing the xml data

Parameters:

encoding - String encoding of InputStream

Returns:

byte[]

Throws:

java.io.UnsupportedEncodingException

See Also:

OMDataSourceExt.getXMLInputStream(String)

close

public void close()

Description copied from interface: OMDataSourceExt

Close the DataSource and free its resources.

copy

public OMDataSourceExt copy()

Return a InputStreamDataSource backed by a ByteArrayInputStream

Returns:

the copy of the data source, or null if the data source can't be copied (e.g. because it is destructive)

inputStream2OutputStream

private static void inputStream2OutputStream(java.io.InputStream is,
                                             java.io.OutputStream os)
                                      throws java.io.IOException

Private utility to write the InputStream contents to the OutputStream.

Parameters:

is -

os -

Throws:

java.io.IOException