Contents

• Public Functions
• Detailed Description
• XQuery Sequences

Detailed Description

TheQAbstractXmlReceiver class provides a callback interface for transforming the output of aQXmlQuery.

QAbstractXmlReceiver is an abstract base class that provides a callback interface for receiving anXQuery sequence, usually the output of anQXmlQuery, and transforming that sequence into a structure of your choosing, usually XML. Consider the example:

QXmlQuery query;query.setQuery("doc('index.html')/html/body/p[1]");QXmlSerializer serializer(query, myOutputDevice);query.evaluateTo(&serializer);

First it constructs aquery that gets the first paragraph from documentindex.html. Then it constructs anXML serializer with thequery andmyOutputDevice (Note theserializer is anXML receiver, ie a subclass ofQAbstractXmlReceiver). Finally, itevaluates thequery, producing an ordered sequence of calls to theserializer's callback functions. The sequence of callbacks transforms the query output to XML and writes it tomyOutputDevice.

Although the example usesQXmlQuery to produce the sequence of callbacks to functions inQAbstractXmlReceiver, you can call the callback functions directly as long as your sequence of calls represents a validXQuery sequence.

XQuery Sequences

AnXQuerysequence is an ordered collection of zero, one, or manyitems. Eachitem is either anatomic value or anode. Anatomic value is a simple data value.

There are six kinds ofnodes.

• AnElement Node represents an XML element.
• AnAttribute Node represents an XML attribute.
• ADocument Node represents an entire XML document.
• AText Node represents character data (element content).
• AProcessing Instruction Node represents an XML processing instruction, which is used in an XML document to tell the application reading the document to perform some action. A typical example is to use a processing instruction to tell the application to use a particular XSLT stylesheet to display the document.
• And aComment node represents an XML comment.

Thesequence ofnodes andatomic values obeys the following rules. Note thatNamespace Node refers to a specialAttribute Node with namexmlns.

• Eachnode appears in thesequence before its children and their descendants appear.
• Anode's descendants appear in thesequence before any of its siblings appear.
• ADocument Node represents an entire document. Zero or moreDocument Nodes can appear in asequence, but they can only be top level items (i.e., aDocument Node can't be a child of anothernode.
• Namespace Nodes immediately follow theElement Node with which they are associated.
• Attribute Nodes immediately follow theNamespace Nodes of the element with which they are associated, or...
• If there are noNamespace Nodes following an element, then theAttribute Nodes immediately follow the element.
• Anatomic value can only appear as a top levelitem, i.e., it can't appear as a child of anode.
• Processing Instruction Nodes do not have children, and their parent is either aDocument Node or anElement Node.
• Comment Nodes do not have children, and their parent is either aDocument Node or anElement Node.

Thesequence ofnodes andatomic values is sent to anQAbstractXmlReceiver (QXmlSerializer in the example above) as a sequence of calls to the receiver's callback functions. The mapping of callback functions to sequence items is as follows.

• startDocument() andendDocument() are called for eachDocument Node in thesequence.endDocument() is not called until all theDocument Node's children have appeared in thesequence.
• startElement() andendElement() are called for eachElement Node.endElement() is not called until all theElement Node's children have appeared in thesequence.
• attribute() is called for eachAttribute Node.
• comment() is called for eachComment Node.
• characters() is called for eachText Node.
• processingInstruction() is called for eachProcessing Instruction Node.
• namespaceBinding() is called for eachNamespace Node.
• atomicValue() is called for eachatomic value.

For a complete explanation ofXQuery sequences, visitXQuery Data Model.

Member Function Documentation

QAbstractXmlReceiver::QAbstractXmlReceiver()

Constructs an abstract xml receiver.

[virtual]QAbstractXmlReceiver::~QAbstractXmlReceiver()

Destroys the xml receiver.

[pure virtual]void QAbstractXmlReceiver::atomicValue(constQVariant & value)

This callback is called when an atomic value appears in thesequence. Thevalue is a simpledata value. It is guaranteed to bevalid.

[pure virtual]void QAbstractXmlReceiver::attribute(constQXmlName & name, constQStringRef & value)

This callback is called when an attribute node appears in thesequence.name is theattribute name and thevalue string contains the attribute value.

[pure virtual]void QAbstractXmlReceiver::characters(constQStringRef & value)

This callback is called when a text node appears in thesequence. Thevalue contains the text. Adjacent text nodes may not occur in thesequence, i.e., this callback must not be called twice in a row.

[pure virtual]void QAbstractXmlReceiver::comment(constQString & value)

This callback is called when a comment node appears in thesequence. Thevalue is the comment text, which must not contain the string "--".

[pure virtual]void QAbstractXmlReceiver::endDocument()

This callback is called when the end of a document node appears in thesequence.

[pure virtual]void QAbstractXmlReceiver::endElement()

This callback is called when the end of an element node appears in thesequence.

[pure virtual]void QAbstractXmlReceiver::endOfSequence()

This callback is called once only, right after thesequence ends.

[pure virtual]void QAbstractXmlReceiver::namespaceBinding(constQXmlName & name)

This callback is called when a namespace binding is in scope of an element. A namespace is defined by a URI. In theQXmlNamename, the value ofQXmlName::namespaceUri() is that URI. The value ofQXmlName::prefix() is the prefix that the URI is bound to. The local name is insignificant and can be an arbitrary value.

[pure virtual]void QAbstractXmlReceiver::processingInstruction(constQXmlName & target, constQString & value)

This callback is called when a processing instruction appears in thesequence. A processing instruction is used in an XML document to tell the application reading the document to perform some action. A typical example is to use a processing instruction to tell the application to use a particular XSLT stylesheet to process the document.

<?xml-stylesheet type="test/xsl" href="formatter.xsl"?>

target is thename of the processing instruction. Itsprefix andnamespace URI must both be empty. Itslocal name is the target. In the above example, the name isxml-stylesheet.

Thevalue specifies the action to be taken. Note that thevalue must not contain the string "?>". In the above example, thevalue istype="test/xsl" href="formatter.xsl.

Generally, use of processing instructions should be avoided, because they are not namespace aware and in many contexts are stripped out anyway. Processing instructions can often be replaced with elements from a custom namespace.

[pure virtual]void QAbstractXmlReceiver::startDocument()

This callback is called when a document node appears in thesequence.

[pure virtual]void QAbstractXmlReceiver::startElement(constQXmlName & name)

This callback is called when a new element node appears in thesequence.name is the validname of the node element.

[pure virtual]void QAbstractXmlReceiver::startOfSequence()

This callback is called once only, right before thesequence begins.