QXmlSerializer Class Reference

The QXmlSerializer class is an implementation of QAbstractXmlReceiver for transforming XQuery output into unformatted XML. More...

#include <qxmlserializer.h>

Inheritance diagram for QXmlSerializer:

Public Functions
virtual void	atomicValue (const QVariant &value)
	Reimplemented Function More...
virtual void	attribute (const QXmlName &name, const QStringRef &value)
	Reimplemented Function More...
virtual void	characters (const QStringRef &value)
	Reimplemented Function More...
const QTextCodec *	codec () const
	Returns the codec being used by the serializer for encoding its XML output. More...
virtual void	comment (const QString &value)
	Reimplemented Function More...
virtual void	endDocument ()
	Reimplemented Function More...
virtual void	endElement ()
	Reimplemented Function More...
virtual void	endOfSequence ()
	Reimplemented Function More...
virtual void	item (const QPatternist::Item &item)
virtual void	namespaceBinding (const QXmlName &nb)
	Reimplemented Function More...
QIODevice *	outputDevice () const
	Returns a pointer to the output device. More...
virtual void	processingInstruction (const QXmlName &name, const QString &value)
	Reimplemented Function More...
	QXmlSerializer (const QXmlQuery &query, QIODevice *outputDevice)
	Constructs a serializer that uses the name pool and message handler in query, and writes the output to outputDevice. More...
void	setCodec (const QTextCodec *codec)
	Sets the codec the serializer will use for encoding its XML output. More...
virtual void	startDocument ()
	Reimplemented Function More...
virtual void	startElement (const QXmlName &name)
	Reimplemented Function More...
virtual void	startOfSequence ()
	Reimplemented Function More...
Public Functions inherited from QAbstractXmlReceiver
	QAbstractXmlReceiver ()
	Constructs an abstract xml receiver. 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
	QXmlSerializer (QAbstractXmlReceiverPrivate *d)
Protected Functions inherited from QAbstractXmlReceiver
	QAbstractXmlReceiver (QAbstractXmlReceiverPrivate *d)
void	sendAsNode (const QPatternist::Item &outputItem)
	Treats outputItem as a node and calls the appropriate function, e. More...

Private Types
enum	State { BeforeDocumentElement, InsideDocumentElement }

Private Functions
bool	atDocumentRoot () const
bool	isBindingInScope (const QXmlName nb) const
void	startContent ()
void	write (const QXmlName &name)
void	write (const char *const chars)
void	write (const QString &content)
void	writeEscaped (const QString &toEscape)
void	writeEscapedAttribute (const QString &toEscape)

Additional Inherited Members
Protected Variables inherited from QAbstractXmlReceiver
QScopedPointer< QAbstractXmlReceiverPrivate >	d_ptr

Detailed Description

The QXmlSerializer class is an implementation of QAbstractXmlReceiver for transforming XQuery output into unformatted XML.

Note

This class or function is reentrant.

Since

4.4

QXmlSerializer translates an XQuery Sequence, usually the output of an QXmlQuery, into 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 instance of this class with the QXmlQuery {query} and QIODevice {myOutputDevice}. Finally, it QXmlQuery::evaluateTo() {evaluates} the QXmlQuery {query}, producing an ordered sequence of calls to the serializer's callback functions. The sequence of callbacks transforms the query output to XML and writes it to QIODevice {myOutputDevice}.

QXmlSerializer will:

• Declare namespaces when needed,

• Use appropriate escaping, when characters can't be represented in the XML,

• Handle line endings appropriately,

• Report errors, when it can't serialize the content, e.g., when asked to serialize an attribute that is a top-level node, or when more than one top-level element is encountered.

If an error occurs during serialization, result is undefined unless the serializer is driven through a call to QXmlQuery::evaluateTo().

If the generated XML should be indented and formatted for reading, use QXmlFormatter.

See also

{http://www.w3.org/TR/xslt-xquery-serialization/}{XSLT 2.0 and XQuery 1.0 Serialization}

QXmlFormatter

Definition at line 58 of file qxmlserializer.h.

Enumerations

State

enum QXmlSerializer::State

private

Where in the document the QXmlSerializer is currently working.

Enumerator
BeforeDocumentElement	Before the document element. This is the XML prolog where the XML declaration, and possibly comments and processing instructions are found.
InsideDocumentElement	This is inside the document element, at any level.

Definition at line 103 of file qxmlserializer.h.

    {
        BeforeDocumentElement,

        InsideDocumentElement
    };

Constructors and Destructors

QXmlSerializer() [1/2]

QXmlSerializer::QXmlSerializer	(	const QXmlQuery &	query,
		QIODevice *	outputDevice
	)

Constructs a serializer that uses the name pool and message handler in query, and writes the output to outputDevice.

outputDevice must be a valid, non-null device that is open in write mode, otherwise behavior is undefined.

outputDevice must not be opened with QIODevice::Text because it will cause the output to be incorrect. This class will ensure line endings are serialized as according with the XML specification. QXmlSerializer does not take ownership of outputDevice.

Definition at line 159 of file qxmlserializer.cpp.

                                                        : QAbstractXmlReceiver(new QXmlSerializerPrivate(query, outputDevice))
{
    if(!outputDevice)
    {
        qWarning("outputDevice cannot be null.");
        return;
    }

    if(!outputDevice->isWritable())
    {
        qWarning("outputDevice must be opened in write mode.");
        return;
    }
}

QXmlSerializer() [2/2]

QXmlSerializer::QXmlSerializer ( QAbstractXmlReceiverPrivate *  d )

protected

Warning

This function is not part of the public interface.

Definition at line 178 of file qxmlserializer.cpp.

                                                             : QAbstractXmlReceiver(d)
{
}

Functions

atDocumentRoot()

bool QXmlSerializer::atDocumentRoot ( ) const

inlineprivate

If the current state is neither BeforeDocumentElement or AfterDocumentElement.

Warning

This function is not part of the public interface.

Definition at line 185 of file qxmlserializer.cpp.

Referenced by attribute(), and startElement().

{
    Q_D(const QXmlSerializer);
    return d->state == BeforeDocumentElement ||
           (d->state == InsideDocumentElement && d->hasClosedElement.size() == 1);
}

atomicValue()

void QXmlSerializer::atomicValue ( const QVariant &  value )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 575 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::atomicValue().

{
    Q_UNUSED(value);
}

attribute()

void QXmlSerializer::attribute ( const QXmlName &  name, const QStringRef &  value  )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 366 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::attribute().

{
    Q_D(QXmlSerializer);
    Q_ASSERT(!name.isNull());

    /* Ensure that the namespace URI used in the name gets outputted. */
    {
        /* Since attributes doesn't pick up the default namespace, a
         * namespace declaration would cause trouble if we output it. */
        if(name.prefix() != StandardPrefixes::empty)
            namespaceBinding(name);
    }

    if(atDocumentRoot())
    {
        Q_UNUSED(d);
        d->query.d->staticContext()->error(QtXmlPatterns::tr(
           "Attribute %1 can't be serialized because it appears at "
           "the top level.").arg(formatKeyword(d->np, name)),
                                           ReportContext::SENR0001,
                                           d->query.d->expression().data());
    }
    else
    {
        d->write(' ');
        write(name);
        write("=\"");
        writeEscapedAttribute(value.toString());
        d->write('"');
    }
}

characters()

void QXmlSerializer::characters ( const QStringRef &  value )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 507 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::endOfSequence(), and QXmlFormatter::startFormattingContent().

{
    Q_D(QXmlSerializer);
    d->isPreviousAtomic = false;
    startContent();
    writeEscaped(value.toString());
}

codec()

const QTextCodec * QXmlSerializer::codec

(

)

const

Returns the codec being used by the serializer for encoding its XML output.

See also

setCodec()

Definition at line 632 of file qxmlserializer.cpp.

{
    Q_D(const QXmlSerializer);
    return d->codec;
}

comment()

void QXmlSerializer::comment ( const QString &  value )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 489 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::comment().

{
    Q_D(QXmlSerializer);
    Q_ASSERT_X(!value.contains(QLatin1String("--")),
               Q_FUNC_INFO,
               "Invalid input; it's the caller's responsibility to ensure "
               "the input is correct.");

    startContent();
    write("<!--");
    write(value);
    write("-->");
    d->isPreviousAtomic = false;
}

endDocument()

void QXmlSerializer::endDocument ( )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 592 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::endDocument().

{
    Q_D(QXmlSerializer);
    d->isPreviousAtomic = false;
}

endElement()

void QXmlSerializer::endElement ( )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 345 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::endElement().

{
    Q_D(QXmlSerializer);
    const QPair<QXmlName, bool> e(d->hasClosedElement.pop());
    d->namespaces.pop();

    if(e.second)
    {
        write("</");
        write(e.first);
        d->write('>');
    }
    else
        write("/>");

    d->isPreviousAtomic = false;
}

endOfSequence()

void QXmlSerializer::endOfSequence ( )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 648 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::endOfSequence().

{
    /* If this function is changed to flush or close or something like that,
     * take into consideration QXmlFormatter, especially
     * QXmlFormatter::endOfSequence().
     */
}

isBindingInScope()

bool QXmlSerializer::isBindingInScope ( const QXmlName  nb ) const

inlineprivate

Warning

This function is not part of the public interface.

Definition at line 402 of file qxmlserializer.cpp.

Referenced by namespaceBinding().

{
    Q_D(const QXmlSerializer);
    const int levelLen = d->namespaces.size();

    if(nb.prefix() == StandardPrefixes::empty)
    {
        for(int lvl = levelLen - 1; lvl >= 0; --lvl)
        {
            const QVector<QXmlName> &scope = d->namespaces.at(lvl);
            const int vectorLen = scope.size();

            for(int s = vectorLen - 1; s >= 0; --s)
            {
                const QXmlName &nsb = scope.at(s);

                if(nsb.prefix() == StandardPrefixes::empty)
                    return nsb.namespaceURI() == nb.namespaceURI();
            }
        }
    }
    else
    {
        for(int lvl = 0; lvl < levelLen; ++lvl)
        {
            const QVector<QXmlName> &scope = d->namespaces.at(lvl);
            const int vectorLen = scope.size();

            for(int s = 0; s < vectorLen; ++s)
            {
                const QXmlName &n = scope.at(s);
                if (n.prefix() == nb.prefix() &&
                    n.namespaceURI() == nb.namespaceURI())
                    return true;
            }
        }
    }

    return false;
}

item()

void QXmlSerializer::item ( const QPatternist::Item &  outputItem )

virtual

Warning

This function is not part of the public interface.

Reimplemented from QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 540 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::item().

{
    Q_D(QXmlSerializer);

    if(outputItem.isAtomicValue())
    {
        if(d->isPreviousAtomic)
        {
            startContent();
            d->write(' ');
            writeEscaped(outputItem.stringValue());
        }
        else
        {
            d->isPreviousAtomic = true;
            const QString value(outputItem.stringValue());

            if(!value.isEmpty())
            {
                startContent();
                writeEscaped(value);
            }
        }
    }
    else
    {
        startContent();
        Q_ASSERT(outputItem.isNode());
        sendAsNode(outputItem);
    }
}

namespaceBinding()

void QXmlSerializer::namespaceBinding ( const QXmlName &  nb )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Definition at line 446 of file qxmlserializer.cpp.

Referenced by attribute(), and startElement().

{
    /*
     * Writes out \a nb.
     *
     * Namespace bindings aren't looked up in a cache, because
     * we typically receive very few.
     */

    Q_D(QXmlSerializer);
    Q_ASSERT_X(!nb.isNull(), Q_FUNC_INFO,
               "It makes no sense to pass a null QXmlName.");

    Q_ASSERT_X((nb.namespaceURI() != StandardNamespaces::empty) ||
               (nb.prefix() == StandardPrefixes::empty),
               Q_FUNC_INFO,
               "Undeclarations of prefixes aren't allowed in XML 1.0 "
               "and aren't supposed to be received.");

    if(nb.namespaceURI() == QPatternist::StandardNamespaces::StopNamespaceInheritance)
        return;

    if(isBindingInScope(nb))
        return;

    d->namespaces.top().append(nb);

    if(nb.prefix() == StandardPrefixes::empty)
        write(" xmlns");
    else
    {
        write(" xmlns:");
        write(d->np->stringForPrefix(nb.prefix()));
    }

    write("=\"");
    writeEscapedAttribute(d->np->stringForNamespace(nb.namespaceURI()));
    d->write('"');
}

outputDevice()

QIODevice * QXmlSerializer::outputDevice

(

)

const

Returns a pointer to the output device.

There is no corresponding function to set the output device, because the output device must be passed to the constructor. The serializer does not take ownership of its IO device.

Definition at line 605 of file qxmlserializer.cpp.

{
    Q_D(const QXmlSerializer);
    return d->device;
}

processingInstruction()

void QXmlSerializer::processingInstruction ( const QXmlName &  name, const QString &  value  )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 518 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::processingInstruction().

{
    Q_D(QXmlSerializer);
    Q_ASSERT_X(!value.contains(QLatin1String("?>")),
               Q_FUNC_INFO,
               "Invalid input; it's the caller's responsibility to ensure "
               "the input is correct.");

    startContent();
    write("<?");
    write(name);
    d->write(' ');
    write(value);
    write("?>");

    d->isPreviousAtomic = false;
}

setCodec()

void QXmlSerializer::setCodec

(

const QTextCodec *

outputCodec

)

Sets the codec the serializer will use for encoding its XML output.

The output codec is set to outputCodec. By default, the output codec is set to the one for UTF-8. The serializer does not take ownership of the codec.

See also

codec()

Definition at line 620 of file qxmlserializer.cpp.

{
    Q_D(QXmlSerializer);
    d->codec = outputCodec;
}

startContent()

void QXmlSerializer::startContent ( )

inlineprivate

Closes any open element start tag. Must be called before outputting any element content.

Warning

This function is not part of the public interface.

Definition at line 195 of file qxmlserializer.cpp.

Referenced by characters(), comment(), item(), processingInstruction(), and startElement().

{
    Q_D(QXmlSerializer);
    if (!d->hasClosedElement.top().second) {
        d->write('>');
        d->hasClosedElement.top().second = true;
    }
}

startDocument()

void QXmlSerializer::startDocument ( )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 583 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::startDocument().

{
    Q_D(QXmlSerializer);
    d->isPreviousAtomic = false;
}

startElement()

void QXmlSerializer::startElement ( const QXmlName &  name )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 307 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::startElement().

{
    Q_D(QXmlSerializer);
    Q_ASSERT(d->device);
    Q_ASSERT(d->device->isWritable());
    Q_ASSERT(d->codec);
    Q_ASSERT(!name.isNull());

    d->namespaces.push(QVector<QXmlName>());

    if(atDocumentRoot())
    {
        if(d->state == BeforeDocumentElement)
            d->state = InsideDocumentElement;
        else if(d->state != InsideDocumentElement)
        {
            d->query.d->staticContext()->error(QtXmlPatterns::tr(
               "Element %1 can't be serialized because it appears outside "
               "the document element.").arg(formatKeyword(d->np, name)),
                                               ReportContext::SENR0001,
                                               d->query.d->expression().data());
        }
    }

    startContent();
    d->write('<');
    write(name);

    /* Ensure that the namespace URI used in the name gets outputted. */
    namespaceBinding(name);

    d->hasClosedElement.push(qMakePair(name, false));
    d->isPreviousAtomic = false;
}

startOfSequence()

void QXmlSerializer::startOfSequence ( )

virtual

Reimplemented Function

Implements QAbstractXmlReceiver.

Reimplemented in QXmlFormatter.

Definition at line 641 of file qxmlserializer.cpp.

Referenced by QXmlFormatter::startOfSequence().

{
}

write() [1/3]

void QXmlSerializer::write ( const QXmlName &  name )

inlineprivate

Writes out name.

Warning

This function is not part of the public interface.

Definition at line 276 of file qxmlserializer.cpp.

Referenced by attribute(), comment(), endElement(), namespaceBinding(), processingInstruction(), startElement(), writeEscaped(), and writeEscapedAttribute().

{
    Q_D(QXmlSerializer);
    const QByteArray &cell = d->nameCache[name.code()];

    if(cell.isNull())
    {
        QByteArray &mutableCell = d->nameCache[name.code()];

        const QString content(d->np->toLexical(name));
        mutableCell = d->codec->fromUnicode(content.constData(),
                                            content.length(),
                                            &d->converterState);
        d->device->write(mutableCell);
    }
    else
        d->device->write(cell);
}

write() [2/3]

void QXmlSerializer::write ( const char *const  chars )

inlineprivate

Warning

This function is not part of the public interface.

Definition at line 298 of file qxmlserializer.cpp.

{
    Q_D(QXmlSerializer);
    d->device->write(chars);
}

write() [3/3]

void QXmlSerializer::write ( const QString &  content )

inlineprivate

Encodes and writes out content.

Warning

This function is not part of the public interface.

Definition at line 267 of file qxmlserializer.cpp.

{
    Q_D(QXmlSerializer);
    d->device->write(d->codec->fromUnicode(content.constData(), content.length(), &d->converterState));
}

writeEscaped()

void QXmlSerializer::writeEscaped ( const QString &  toEscape )

private

Escapes content intended as text nodes for elements.

Warning

This function is not part of the public interface.

Definition at line 207 of file qxmlserializer.cpp.

Referenced by characters(), and item().

{
    if(toEscape.isEmpty()) /* Early exit. */
        return;

    QString result;
    result.reserve(int(toEscape.length() * 1.1));
    const int length = toEscape.length();

    for(int i = 0; i < length; ++i)
    {
        const QChar c(toEscape.at(i));

        if(c == QLatin1Char('<'))
            result += QLatin1String("&lt;");
        else if(c == QLatin1Char('>'))
            result += QLatin1String("&gt;");
        else if(c == QLatin1Char('&'))
            result += QLatin1String("&amp;");
        else
            result += toEscape.at(i);
    }

    write(result);
}

writeEscapedAttribute()

void QXmlSerializer::writeEscapedAttribute ( const QString &  toEscape )

inlineprivate

Identical to writeEscaped(), but also escapes quotes.

Warning

This function is not part of the public interface.

Definition at line 236 of file qxmlserializer.cpp.

Referenced by attribute(), and namespaceBinding().

{
    if(toEscape.isEmpty()) /* Early exit. */
        return;

    QString result;
    result.reserve(int(toEscape.length() * 1.1));
    const int length = toEscape.length();

    for(int i = 0; i < length; ++i)
    {
        const QChar c(toEscape.at(i));

        if(c == QLatin1Char('<'))
            result += QLatin1String("&lt;");
        else if(c == QLatin1Char('>'))
            result += QLatin1String("&gt;");
        else if(c == QLatin1Char('&'))
            result += QLatin1String("&amp;");
        else if(c == QLatin1Char('"'))
            result += QLatin1String("&quot;");
        else
            result += toEscape.at(i);
    }

    write(result);
}

---

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

• /src/xmlpatterns/api/qxmlserializer.h
• /src/xmlpatterns/api/qxmlserializer.cpp