|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# QXmlQuery Class Reference
[QtXmlPatterns module]

The QXmlQuery class is used to evaluate XQuery queries. More...

     #include <QXmlQuery>

Note: All the functions in this class are reentrant.

This class was introduced in Qt 4.4.

- List of all members, including inherited members

### Public Functions

- QXmlQuery ()
- QXmlQuery ( const QXmlQuery & other )
- QXmlQuery ( const QXmlNamePool & np )
- ~QXmlQuery ()
- void bindVariable ( const QXmlName & name, const QXmlItem & value )
- void bindVariable ( const QXmlName & name, QIODevice * device )
- void bindVariable ( const QString & localName, const QXmlItem & value )
- void bindVariable ( const QString & localName, QIODevice * device )
- QXmlItem contextItem () const
- bool evaluateToReceiver ( const QAbstractXmlReceiverPointer & callback ) const
- void evaluateToResult ( QXmlResultItems * result ) const
- bool evaluateToStringList ( QStringList * target ) const
- bool isValid () const
- QAbstractMessageHandler * messageHandler () const
- QXmlNamePool namePool () const
- void setContextItem ( const QXmlItem & item )
- void setMessageHandler ( QAbstractMessageHandler * aMessageHandler )
- void setQuery ( QIODevice * sourceCode, const QUrl & documentURI = QUrl() )
- void setQuery ( const QUrl & queryURI )
- void setQuery ( const QString & sourceCode, const QUrl & documentURI = QUrl() )
- void setUriResolver ( const QAbstractUriResolver * resolver )
- const QAbstractUriResolver * uriResolver () const
- QXmlQuery & operator= ( const QXmlQuery & other )

## Detailed Description

The QXmlQuery class is used to evaluate XQuery queries.

QXmlQuery is the central point for running XQuery queries. First setQuery() is called specifying the source code of the query, and one of the following members are called for the actual evaluation.

### Evaluating Queries

serialize() evaluates the query and writes the result as XML to a QIODevice. For instance, the result is indented and then written to a file using QFile. With QSerializationSettings, options governing the serialization process can be specified.

evaluateToReceiver() takes a pointer to a QAbstractXmlReceiver, whose members will be called to appropriately mirror the result of the query. This is conceptually like the SAX API.

evaluateToResult() tranfers the evaluation to a QXmlResultItems instance, a Java-like iterator, which allows items to be accessed on an indivual basis using QXmlNodeModelIndex and QVariant.

evaluateToStringList() is similar to evaluateToResult(), but converts the result directly to a QStringList.

### Variable Bindings

Apart using the fn:doc() function to retrieve data into the query for processing, one can bind variables using bindVariable(). When having called bindVariable(), a variable binding will be available to the query by the specified name. It is not necessary to declare the variable as external inside the query.

### Thread Support

Multiple queries can run in multiple threads, which is achieved by simply copying QXmlQuery and in the new instance modify it accordingly, such as changing the variable bindings or evaluate it with a different method. Behind the scenes, QXmlQuery will reuse resources such as opened files and compiled queries between threads, to the extent possible.

### Error Handling

During the evaluation of a query, an error can occur. A dynamic type error, or failing to load a file are examples of such runtime errors.

When an evaluation error occur, the following happens:

- Error messages are sent to the messageHandler()
- QXmlResultItems::hasError() will return `true` or evaluateToReceiver() will return `false`
- The query result, such as the bytes written out using serialize(), or the events sent to QAbstractXmlReceiver, and items returned from evaluateToResult(), is undefined

### Resource Management

A query potentially creates nodes, opens documents, and in other ways allocate resources. These are automatically managed, and will be deallocated as soon they aren't needed anymore. If it is of interest to deallocate the resources a query has allocated, make sure the relevant QXmlQuery and QAbstractXmlReceiver & QAbstractXmlForwardIterator instances have been destructed.

In order to use QXmlQuery, QCoreApplication must first be instantiated.

## Member Function Documentation

### QXmlQuery::QXmlQuery ()

Constructs an invalid query that cannot be used. setQuery() must be called.

### QXmlQuery::QXmlQuery ( const QXmlQuery & other )

Constructs a QXmlQuery instance that is a copy of other.

### QXmlQuery::QXmlQuery ( const QXmlNamePool & np )

Constructs a QXmlQuery instance that use np as name pool.

### QXmlQuery::~QXmlQuery ()

Destructs this QXmlQuery instance.

### void QXmlQuery::bindVariable ( const QXmlName & name, const QXmlItem & value )

Makes a variable called name that has value value, avalable to the query.

name cannot be `null`

If a variable by name name has previously been bound, the previous binding is replaced.

If value is `null`, any existing binding is removed.

See also QVariant::isValid(), How QVariant maps to XQuery's Data Model, and QXmlItem::isNull().

### void QXmlQuery::bindVariable ( const QXmlName & name, QIODevice * device )

This is an overloaded member function, provided for convenience.

Binds the QIODevice device to the variable name.

The QIODevice device is exposed as a URI of type `xs:anyURI` to the query, which can be passed to the `fn:doc()` function for reading.

This can be method to pass an XML document that is in memory to `fn:doc`.

         QByteArray myDocument;
         QBuffer buffer(&myDocument); // This is a QIODevice.
         buffer.open(QIODevice::ReadOnly);
         QXmlQuery query;
         query.bindVariable("myDocument", &buffer);
         query.setQuery("declare variable $myDocument external; doc($myDocument)");

The user is reponsible for ensuring the device is opened, and is readable, otherwise effects and behaviors are undefined.

If a variable binding by name name already exists, the existing is overriden.

If device is `null`, result is undefined.

name cannot be `null`

The URI that the variable evaluates to is arbitrary and may change.

### void QXmlQuery::bindVariable ( const QString & localName, const QXmlItem & value )

This is an overloaded member function, provided for convenience.

Same as above, but constructs a QXmlName that has an empty namespace and local name localName. This is convenience for calling:

         query.bindVariable(QXmlName(query.namePool(), localName), value);

### void QXmlQuery::bindVariable ( const QString & localName, QIODevice * device )

This is an overloaded member function, provided for convenience.

Same as above, but constructs variable binding in form of o a URI, whose name is an empty namespace and local name localName and binds device.

localName must be a valid `NCName`.

This is convenience for calling:

         query.bindVariable(QXmlName(query.namePool(), localName), device);

See also QXmlName::isNCName().

### QXmlItem QXmlQuery::contextItem () const

Returns the context item. See setContextItem() for an explanation of what it is.

See also setContextItem().

### bool QXmlQuery::evaluateToReceiver ( const QAbstractXmlReceiverPointer & callback ) const

Evaluates this query and sends the result as a stream of events to callback.

If callback is null or if this query is invalid, behavior is undefined.

QXmlQuery does not claim ownership of callback.

If an error occur during evaluation, messages are sent to messageHandler() and `false` is returned.

If this query is invalid, `false` is returned and it is undefined what events that has been sent to callback.

See also QAbstractXmlReceiver, evaluateToResult(), and isValid().

### void QXmlQuery::evaluateToResult ( QXmlResultItems * result ) const

Starts the evaluation and makes it available in result.

If result is `null`, result & behavior is undefined.

The actual evaluation takes place incrementally, when QXmlResultItems::next() is called.

See also evaluateToReceiver() and QXmlResultItems::next().

### bool QXmlQuery::evaluateToStringList ( QStringList * target ) const

Attempts to evaluate the query, and returns the result in the QStringList target.

If evaluation succeeds, `true` is returned, otherwise `false`. If the query is invalid or evaluation fails, `false` is returned and the content of target is undefined.

The query must evaluate to a sequence of `xs:string` values, and this is checked by compiling the query as if it was passed to a function accepting `xs:string*`. This means nodes will be converted to strings and values that cannot be promoted to `xs:string` trigger type errors, for instance.

If target is `null`, behavior is undefined.

### bool QXmlQuery::isValid () const

Returns `true` if this query is valid, otherwise `false`.

An invalid query is for instance a query that contains a syntax error, or a QXmlQuery instance for which setQuery() hasn't been called.

### QAbstractMessageHandler * QXmlQuery::messageHandler () const

Returns the message handler that is being used.

See also setMessageHandler().

### QXmlNamePool QXmlQuery::namePool () const

Returns the name pool which this QXmlQuery, and all instances which somehow relates to it, is using.

There is no setter for the name pool, since mixing name pools is dangerous.

### void QXmlQuery::setContextItem ( const QXmlItem & item )

Sets the context item to item.

The context item is the item which the focus currently contains. For instance, in the expression `p/span`, the elements that the expression `p` evaluations(a sequence), acts as a focus for the following expression, `span`.

The context item is the global focus for the query. It can only be a single item, and can be accessed using the context item expression: `.(a dot)`.

By default the return value is a default constructed QXmlItem, which means that the focus is undefined.

See also contextItem().

### void QXmlQuery::setMessageHandler ( QAbstractMessageHandler * aMessageHandler )

Makes QXmlQuery send compile and runtime messages to aMessageHandler.

QXmlQuery does not claim ownership of aMessageHandler, unless the default message handler is used.

If a new message handler is set after the query is compiled(which is triggered by a call to isValid(), for instance), runtime will use the message handler that was used during compilation.

The default message handler will write messages to `stderr` using color codes, if `stderr` will be able to render the color codes.

See also messageHandler().

### void QXmlQuery::setQuery ( QIODevice * sourceCode, const QUrl & documentURI = QUrl() )

Sets this QXmlQuery instance to use the query contained in sourceCode. The encoding of sourceCode will be detected as according to XQuery's rules.

sourceCode must be opened with at least the QIODevice::ReadOnly flag.

documentURI should be set to the location of the sourceCode. It is used for message reporting, and is used for resolving some of relative URIs in the query(it is the default value of the static base URI, to be specific). documentURI must be empty or valid. If it's empty, QCoreApplication::applicationFilePath() is used. If it is relative, it is resolved against QCoreApplication::applicationFilePath(). If it's invalid, result is undefined.

If the query contains a static error such as a syntax error, descriptive messages are sent to messageHandler() and isValid() will return `false`.

documentURI should be the location of the query. It is used for resolving relative URIs appearing in the query, and for message reporting. To be specific, it is the static base URI. If documentURI is not empty and invalid, behavior is undefined. If documentURI is empty, the application's executable path is used.

QXmlQuery only own the QAbstractMessageHandler if the user hasn't supplied it.

See also isValid().

### void QXmlQuery::setQuery ( const QUrl & queryURI )

This is an overloaded member function, provided for convenience.

Reads the query found at queryURI and sets it.

If any error occurs, such as that the query doesn't exist, can't be read or is invalid, isValid() returns `false`.

The supported URI schemes are the same as for the XQuery function `fn:doc(except that no query can be loaded from a variable binding)`.

queryURI is used as the static base URI and is resolved against QCoreApplication::applicationFilePath() if it is relative. If queryURI is empty or invalid, effects and behavior is undefined.

### void QXmlQuery::setQuery ( const QString & sourceCode, const QUrl & documentURI = QUrl() )

This is an overloaded member function, provided for convenience.

Equivalent to setQuery(QIODevice *, bool &), with the difference that it takes a QString for convenience.

The same behaviors and obligations apply as for the prepareQuery() version that takes a QIODevice.

No encoding detection will be done, since sourceCode is already a Unicode string.

### void QXmlQuery::setUriResolver ( const QAbstractUriResolver * resolver )

Sets the URI resolver to resolver.

See also uriResolver().

### const QAbstractUriResolver * QXmlQuery::uriResolver () const

Returns the URI resolver in use. If no URI resolver has been set, Patternist will use the URI in queries as is.

The URI resolver provides a level of abstraction or "polymorphic URIs." For instance, a query can operate on "logical" URIs which a URI resolver rewrites to physical ones, or to translate obsolete or invalid URIs, to new ones.

Patternist calls the URI resolver for all URIs it encounters, except for namespaces. This means more specically:

- All builtin functions that deals with URIs. This is `fn:doc()`, and `fn:doc-available()`
- The URI for module imports

For instance, in the case of `fn:doc()`, the absolute URI is the base URI in the static context(which most likely is the location of the query). Instead of using the URI the user specified, the return value of QAbstractUriResolver::resolve() will be used.

When Patternist calls QAbstractUriResolver::resolve() the absolute URI is the URI which the XQuery language mandates should be used, and the relative URI is the URI which the user specified.

QXmlQuery does not own the QAbstractUriResolver instance.

See also setUriResolver().

### QXmlQuery & QXmlQuery::operator= ( const QXmlQuery & other )

Assigns other to this QXmlQuery instance.