Qt 4.8
Public Functions | Protected Functions | Protected Variables | Private Functions | List of all members
QAbstractXmlReceiver Class Referenceabstract

The QAbstractXmlReceiver class provides a callback interface for transforming the output of a QXmlQuery. More...

#include <qabstractxmlreceiver.h>

Inheritance diagram for QAbstractXmlReceiver:
QXmlSerializer QXmlFormatter

Public Functions

virtual void atomicValue (const QVariant &value)=0
 This callback is called when an atomic value appears in the XQuery Sequence. More...
 
virtual void attribute (const QXmlName &name, const QStringRef &value)=0
 This callback is called when an attribute node appears in the XQuery Sequence. More...
 
virtual void characters (const QStringRef &value)=0
 This callback is called when a text node appears in the XQuery Sequence. More...
 
virtual void comment (const QString &value)=0
 This callback is called when a comment node appears in the XQuery Sequence. More...
 
virtual void endDocument ()=0
 This callback is called when the end of a document node appears in the XQuery Sequence. More...
 
virtual void endElement ()=0
 This callback is called when the end of an element node appears in the XQuery Sequence. More...
 
virtual void endOfSequence ()=0
 This callback is called once only, right after the XQuery Sequence ends. More...
 
virtual void item (const QPatternist::Item &item)
 
virtual void namespaceBinding (const QXmlName &name)=0
 This callback is called when a namespace binding is in scope of an element. More...
 
virtual void processingInstruction (const QXmlName &target, const QString &value)=0
 This callback is called when a processing instruction appears in the XQuery Sequence. More...
 
 QAbstractXmlReceiver ()
 Constructs an abstract xml receiver. More...
 
virtual void startDocument ()=0
 This callback is called when a document node appears in the XQuery Sequence. More...
 
virtual void startElement (const QXmlName &name)=0
 This callback is called when a new element node appears in the XQuery Sequence. More...
 
virtual void startOfSequence ()=0
 This callback is called once only, right before the XQuery Sequence begins. More...
 
virtual void whitespaceOnly (const QStringRef &value)
 This function may be called instead of characters() if, and only if, value consists only of whitespace. More...
 
virtual ~QAbstractXmlReceiver ()
 Destroys the xml receiver. More...
 

Protected Functions

 QAbstractXmlReceiver (QAbstractXmlReceiverPrivate *d)
 
void sendAsNode (const QPatternist::Item &outputItem)
 Treats outputItem as a node and calls the appropriate function, e. More...
 

Protected Variables

QScopedPointer< QAbstractXmlReceiverPrivated_ptr
 

Private Functions

template<const QXmlNodeModelIndex::Axis axis>
void sendFromAxis (const QXmlNodeModelIndex &node)
 

Detailed Description

The QAbstractXmlReceiver class provides a callback interface for transforming the output of a QXmlQuery.

Note
This class or function is reentrant.
Since
4.4

QAbstractXmlReceiver is an abstract base class that provides a callback interface for receiving an XQuery Sequence, usually the output of an QXmlQuery, 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 a QXmlQuery {query} that gets the first paragraph from document index.html. Then it constructs an QXmlSerializer {XML serializer} with the QXmlQuery {query} and QIODevice {myOutputDevice} (Note the QXmlSerializer {serializer} is an {XML receiver}, ie a subclass of QAbstractXmlReceiver). Finally, it QXmlQuery::evaluateTo() {evaluates} the QXmlQuery {query}, producing an ordered sequence of calls to the QXmlSerializer {serializer's} callback functions. The sequence of callbacks transforms the query output to XML and writes it to QIODevice {myOutputDevice}.

Although the example uses QXmlQuery to produce the sequence of callbacks to functions in QAbstractXmlReceiver, you can call the callback functions directly as long as your sequence of calls represents a valid XQuery Sequence.

XQuery Sequences

An XQuery sequence is an ordered collection of zero, one, or many items. Each item is either an {atomic value} or a {node}. An {atomic value} is a simple data value.

There are six kinds of nodes.

The sequence of nodes and {atomic values} obeys the following rules. Note that {Namespace Node} refers to a special {Attribute Node} with name {xmlns}.

The sequence of nodes and {atomic values} is sent to an QAbstractXmlReceiver (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.

For a complete explanation of XQuery sequences, visit http://www.w3.org/TR/xpath-datamodel/ {XQuery Data Model}.

See also
{http://www.w3.org/TR/xpath-datamodel/}{W3C XQuery 1.0 and XPath 2.0 Data Model (XDM)}
QXmlSerializer
QXmlResultItems

Definition at line 63 of file qabstractxmlreceiver.h.

Constructors and Destructors

◆ QAbstractXmlReceiver() [1/2]

QAbstractXmlReceiver::QAbstractXmlReceiver ( )

Constructs an abstract xml receiver.

Definition at line 220 of file qabstractxmlreceiver.cpp.

220  : d_ptr(0)
221 {
222 }
QScopedPointer< QAbstractXmlReceiverPrivate > d_ptr

◆ ~QAbstractXmlReceiver()

QAbstractXmlReceiver::~QAbstractXmlReceiver ( )
virtual

Destroys the xml receiver.

Definition at line 227 of file qabstractxmlreceiver.cpp.

228 {
229 }

◆ QAbstractXmlReceiver() [2/2]

QAbstractXmlReceiver::QAbstractXmlReceiver ( QAbstractXmlReceiverPrivate d)
protected
Warning
This function is not part of the public interface.

Definition at line 212 of file qabstractxmlreceiver.cpp.

213  : d_ptr(d)
214 {
215 }
QScopedPointer< QAbstractXmlReceiverPrivate > d_ptr

Functions

◆ atomicValue()

void QAbstractXmlReceiver::atomicValue ( const QVariant value)
pure virtual

This callback is called when an atomic value appears in the XQuery Sequence.

The value is a simple QVariant {data value}. It is guaranteed to be QVariant::isValid() {valid}.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by item().

◆ attribute()

void QAbstractXmlReceiver::attribute ( const QXmlName name,
const QStringRef value 
)
pure virtual

This callback is called when an attribute node appears in the XQuery Sequence.

name is the QXmlName {attribute name} and the value string contains the attribute value.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ characters()

void QAbstractXmlReceiver::characters ( const QStringRef value)
pure virtual

This callback is called when a text node appears in the XQuery Sequence.

The value contains the text. Adjacent text nodes may not occur in the XQuery Sequence, i.e., this callback must not be called twice in a row.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode(), and whitespaceOnly().

◆ comment()

void QAbstractXmlReceiver::comment ( const QString value)
pure virtual

This callback is called when a comment node appears in the XQuery Sequence.

The value is the comment text, which must not contain the string "--".

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ endDocument()

void QAbstractXmlReceiver::endDocument ( )
pure virtual

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

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ endElement()

void QAbstractXmlReceiver::endElement ( )
pure virtual

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

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ endOfSequence()

void QAbstractXmlReceiver::endOfSequence ( )
pure virtual

This callback is called once only, right after the XQuery Sequence ends.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by QXmlQuery::evaluateTo().

◆ item()

void QAbstractXmlReceiver::item ( const QPatternist::Item item)
virtual
Warning
This function is not part of the public interface.

Reimplemented in QXmlSerializer, and QXmlFormatter.

Definition at line 488 of file qabstractxmlreceiver.cpp.

489 {
490  if(item.isNode())
491  return sendAsNode(item);
492  else
494 }
static QVariant toQt(const AtomicValue *const value)
const AtomicValue * asAtomicValue() const
Definition: qitem_p.h:373
bool isNode() const
Determines whether this item is an atomic value, or a node.
Definition: qitem_p.h:349
void sendAsNode(const QPatternist::Item &outputItem)
Treats outputItem as a node and calls the appropriate function, e.
virtual void atomicValue(const QVariant &value)=0
This callback is called when an atomic value appears in the XQuery Sequence.

◆ namespaceBinding()

void QAbstractXmlReceiver::namespaceBinding ( const QXmlName name)
pure virtual

This callback is called when a namespace binding is in scope of an element.

A namespace is defined by a URI. In the QXmlName name, the value of QXmlName::namespaceUri() is that URI. The value of QXmlName::prefix() is the prefix that the URI is bound to. The local name is insignificant and can be an arbitrary value.

Implemented in QXmlSerializer.

◆ processingInstruction()

void QAbstractXmlReceiver::processingInstruction ( const QXmlName target,
const QString value 
)
pure virtual

This callback is called when a processing instruction appears in the XQuery Sequence.

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 the QXmlName {name} of the processing instruction. Its prefix and {namespace URI} must both be empty. Its {local name} is the target. In the above example, the name is {xml-stylesheet}.

The value specifies the action to be taken. Note that the value must not contain the string "?>". In the above example, the value is type="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.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ sendAsNode()

void QAbstractXmlReceiver::sendAsNode ( const QPatternist::Item outputItem)
protected

Treats outputItem as a node and calls the appropriate function, e.

Warning
This function is not part of the public interface.

g., attribute() or comment(), depending on its QXmlNodeModelIndex::NodeKind.

This is a helper function that subclasses can use to multiplex Nodes received via item().

Definition at line 397 of file qabstractxmlreceiver.cpp.

Referenced by item(), QXmlSerializer::item(), and sendFromAxis().

398 {
399  Q_ASSERT(outputItem);
400  Q_ASSERT(outputItem.isNode());
401  const QXmlNodeModelIndex asNode = outputItem.asNode();
402 
403  switch(asNode.kind())
404  {
406  {
407  const QString &v = outputItem.stringValue();
408  attribute(asNode.name(), QStringRef(&v));
409  return;
410  }
412  {
413  startElement(asNode.name());
414 
415  /* First the namespaces, then attributes, then the children. */
416  asNode.sendNamespaces(this);
417  sendFromAxis<QXmlNodeModelIndex::AxisAttribute>(asNode);
418  sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);
419 
420  endElement();
421 
422  return;
423  }
425  {
426  const QString &v = asNode.stringValue();
427  characters(QStringRef(&v));
428  return;
429  }
431  {
432  processingInstruction(asNode.name(), outputItem.stringValue());
433  return;
434  }
436  {
437  comment(outputItem.stringValue());
438  return;
439  }
441  {
442  startDocument();
443  sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);
444  endDocument();
445  return;
446  }
448  Q_ASSERT_X(false, Q_FUNC_INFO, "Not implemented");
449  }
450 
451  Q_ASSERT_X(false, Q_FUNC_INFO,
452  QString::fromLatin1("Unknown node type: %1").arg(asNode.kind()).toUtf8().constData());
453 }
The QXmlNodeModelIndex class identifies a node in an XML node model subclassed from QAbstractXmlNodeM...
virtual void characters(const QStringRef &value)=0
This callback is called when a text node appears in the XQuery Sequence.
virtual void attribute(const QXmlName &name, const QStringRef &value)=0
This callback is called when an attribute node appears in the XQuery Sequence.
virtual void startElement(const QXmlName &name)=0
This callback is called when a new element node appears in the XQuery Sequence.
virtual void processingInstruction(const QXmlName &target, const QString &value)=0
This callback is called when a processing instruction appears in the XQuery Sequence.
The QString class provides a Unicode character string.
Definition: qstring.h:83
bool isNode() const
Determines whether this item is an atomic value, or a node.
Definition: qitem_p.h:349
virtual void comment(const QString &value)=0
This callback is called when a comment node appears in the XQuery Sequence.
#define Q_ASSERT(cond)
Definition: qglobal.h:1823
virtual void endDocument()=0
This callback is called when the end of a document node appears in the XQuery Sequence.
QString stringValue() const
Returns the string value of this Item.
Definition: qitem_p.h:302
The QStringRef class provides a thin wrapper around QString substrings.
Definition: qstring.h:1099
virtual void startDocument()=0
This callback is called when a document node appears in the XQuery Sequence.
#define Q_ASSERT_X(cond, where, what)
Definition: qglobal.h:1837
const QXmlNodeModelIndex & asNode() const
Definition: qitem_p.h:379
static QString fromLatin1(const char *, int size=-1)
Returns a QString initialized with the first size characters of the Latin-1 string str...
Definition: qstring.cpp:4188
const QChar * constData() const
Returns a pointer to the data stored in the QString.
Definition: qstring.h:712
virtual void endElement()=0
This callback is called when the end of an element node appears in the XQuery Sequence.
#define Q_FUNC_INFO
Definition: qglobal.h:1871

◆ sendFromAxis()

template<const QXmlNodeModelIndex::Axis axis>
void QAbstractXmlReceiver::sendFromAxis ( const QXmlNodeModelIndex node)
private

Definition at line 196 of file qabstractxmlreceiver.cpp.

197 {
198  Q_ASSERT(!node.isNull());
199  const QXmlNodeModelIndex::Iterator::Ptr it(node.iterate(axis));
200  QXmlNodeModelIndex next(it->next());
201 
202  while(!next.isNull())
203  {
204  sendAsNode(next);
205  next = it->next();
206  }
207 }
The QXmlNodeModelIndex class identifies a node in an XML node model subclassed from QAbstractXmlNodeM...
bool isNull() const
Returns true if this QXmlNodeModelIndex is a default constructed value, otherwise false...
#define it(className, varName)
The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object...
Definition: qshareddata.h:136
#define Q_ASSERT(cond)
Definition: qglobal.h:1823
void sendAsNode(const QPatternist::Item &outputItem)
Treats outputItem as a node and calls the appropriate function, e.
QExplicitlySharedDataPointer< QAbstractXmlForwardIterator< QXmlNodeModelIndex > > iterate(const Axis axis) const
Definition: qitem_p.h:456

◆ startDocument()

void QAbstractXmlReceiver::startDocument ( )
pure virtual

This callback is called when a document node appears in the XQuery Sequence.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ startElement()

void QAbstractXmlReceiver::startElement ( const QXmlName name)
pure virtual

This callback is called when a new element node appears in the XQuery Sequence.

name is the valid QXmlName {name} of the node element.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by sendAsNode().

◆ startOfSequence()

void QAbstractXmlReceiver::startOfSequence ( )
pure virtual

This callback is called once only, right before the XQuery Sequence begins.

Implemented in QXmlSerializer, and QXmlFormatter.

Referenced by QXmlQuery::evaluateTo().

◆ whitespaceOnly()

void QAbstractXmlReceiver::whitespaceOnly ( const QStringRef value)
virtual

This function may be called instead of characters() if, and only if, value consists only of whitespace.

Warning
This function is not part of the public interface.

The caller gurantees that value is not empty.

Whitespace refers to a sequence of characters that are either spaces, tabs, or newlines, in any order. In other words, not all the Unicode whitespace category is considered whitespace here.

However, there is no guarantee or requirement that whitespaceOnly() is called for text nodes containing whitespace only. characters() may be called just as well. This is why the default implementation for whitespaceOnly() calls characters().

See also
characters()

Definition at line 477 of file qabstractxmlreceiver.cpp.

478 {
480  "The caller must guarantee only whitespace is passed. Use characters() in other cases.");
481  const QString &v = value.toString();
482  characters(QStringRef(&v));
483 }
QString toString() const
Returns a copy of the string reference as a QString object.
Definition: qstring.cpp:8653
virtual void characters(const QStringRef &value)=0
This callback is called when a text node appears in the XQuery Sequence.
The QString class provides a Unicode character string.
Definition: qstring.h:83
QString trimmed() const Q_REQUIRED_RESULT
Returns a string that has whitespace removed from the start and the end.
Definition: qstring.cpp:4506
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
The QStringRef class provides a thin wrapper around QString substrings.
Definition: qstring.h:1099
#define Q_ASSERT_X(cond, where, what)
Definition: qglobal.h:1837
#define Q_FUNC_INFO
Definition: qglobal.h:1871

Properties

◆ d_ptr

QScopedPointer<QAbstractXmlReceiverPrivate> QAbstractXmlReceiver::d_ptr
protected

Definition at line 94 of file qabstractxmlreceiver.h.


The documentation for this class was generated from the following files: