The ability to transform XML documents is one of the more useful and powerful features of XML streams.

With transformation filters, you can adapt the format of an XML stream to the requirements of other software, or change the format to make it suitable for display.

Using transformation filters with XML streams can also enhance the capabilities of loosely-coupled messaging systems by reducing the constraints on the format of XML documents. The transformation streams in the XML Streams Module all make use of a “transformation object” to effect the actual transformation of a document. The use of transformation filters is not automatic; you must explicitly implement these objects.

This chapter discusses two types of transformations:

A character-based transformation allows you to modify the incoming or outgoing stream of characters that make up an XML document. The transformation stream buffers the entire document, and then hands that buffer to a transformation object as an istream.

A character-based transformation stream offers the greatest flexibility since a document is treated as merely a sequence of characters; however, this type of transformation stream also requires that the transformation object itself provide any parsing logic.

A character-based transformation stream can be used to implement an XSLT transformation stream as shown in Chapter 6.

This chapter includes code examples from the file transform.cpp. For the complete example, see: buildspace\examples\xmlstreams\transform\transform.cpp

An element-based transformation stream differs from a character-based transformation stream in that the XML document is parsed by the stream before being handed to the transformation object.

The transformation stream passes to the transformation object a pointer to the root element of the document (See the RWXmlStreamElement in the ../sourceproref:index.htmlSourcePro C++ API Reference Guide for a description of the internal structure used to represent an XML element.). The transformation object is then free to modify the document in any way. A transformation object may alter element names or attributes, or may restructure the document by adding, deleting, or rearranging elements contained by the root element or sub-elements.

An element-based transformation is much easier to implement, since the transformation stream handles all the parsing and serialization logic. As long as the initial input or final output to or from an XML stream is all XML, this kind of transformation is more suitable than a character-based transformation.

An element-based transformation cannot be used to transform XML to a non-XML document, or a non-XML document to XML, since the interface to the transformation object is an internal XML structure.

This chapter includes code examples from the file parsedTransform.cpp. For the complete example, see buildspace\examples\xmlstreams\transform\parsedTransform.cpp.