Contents

• Public Types
• Public Functions
• Protected Functions
• Detailed Description
• Usage
• Subclassing
• Thread Safety

Detailed Description

TheQAbstractXmlNodeModel class is an abstract base class for modeling non-XML data to look like XML forQXmlQuery.

TheQAbstractXmlNodeModel specifies the interface that a node model must implement for that node model be accessible to the query engine for processingXQuery queries. A node model represents data as a structure that can be queried as if the data were XML.

The node model represented by a subclass ofQAbstractXmlNodeModel is meant to be accessed by theQtXmlPatterns query engine. If the API seems a little strange in a few places, it is because the member functions are called by the query engine as it evaluates anXQuery. They aren't meant to be used programatically.

Usage

QAbstractXmlNodeModel bridges the gap between the arbitrary structure of the non-XML data to be queried and the well-defined structure of XML data understood byQXmlQuery.

Consider a chemistry application that reads the filechemistryData, which contains non-XML data that represents a chemical structure composed of molecules and atoms. The application will query this chemistry data with anXQuery it reads from filequeryFile. We write a custom subclass ofQAbstractXmlNodeModel (ChemistryNodeModel) that readschemistryData and builds a data structure, perhaps composed of objects of our own classesmolecule andatom. Clearly, this data structure is not XML. Our custom subclass will know how to traverse this non-XML structure and present it through theXPath Data Model interface.

QFile queryFile(argv[1]);QFile chemistryData(argv[2]);QString moleculeName= argv[3];QXmlQuery query;query.setQuery(&queryFile,QUrl::fromLocalFile(queryFile.fileName()));ChemistryNodeModel myNodeModel(query.namePool(), chemistryData);QXmlNodeModelIndex startNode= myNodeModel.nodeFor(moleculeName);query.bindVariable("queryRoot", startNode);QFile out;out.open(stdout,QIODevice::WriteOnly);QXmlSerializer serializer(query,&out);query.evaluateTo(&serializer);

The application first creates an instance ofQXmlQuery and callssetQuery() to readqueryFile containing theXQuery we want to run. Then it creates an instance of our custom node model class,ChemistryNodeModel, which is a subclass ofQAbstractXmlNodeModel. Its constructor is called with thename pool obtained from ourQXmlQuery, and with thechemistryFile containing the structure of molecules and atoms to be queried. Thename pool is required because our custom node model has the member functionname(), which returns thename of any node in the model. Thequery and the custom node model must use the same name pool for constructing thesenames. The constructor would then readchemistryFile and build the custom node model structure.

To connect thequery to the custom node model, we must bind a variable name used in the query to a node in the model. The variable can then be used in the query as a starting node. First, anindex for the desired starting node is retrieved by callingQAbstractXmlNodeModel::createIndex(). Then the index is bound to a variable name, in this casequeryRoot, by passing the name and the index toQXmlQuery::bindVariable(). The query can then use a variable reference$queryRoot to refer to the starting node. Note that if thequery uses multiple variable references, a call toQXmlQuery::bindVariable() is required to bind each different variable name to a node in the model.

The query is executed when the application calls one of theQXmlQuery evaluation functions. The application usesQXmlQuery::evaluateTo(QAbstractXmlReceiver *), because it then uses aserializer to out the query result as XML tostdout. We could have usedQXmlQuery::evaluateTo(QXmlResultItems *) to get a list of result items, orQXmlQuery::evaluateTo(QStringList *) if the query evaluated to a sequence ofxs:string values.

During query execution, the engine iterates over the node model usingnextFromSimpleAxis() to get theindex of the next node to be visited. The engine can get the name of a node by callingname() with the node'sindex.stringValue(),baseUri(),documentUri() andkind() are also called as needed with a nodeindex.

The example demonstrates the standard pattern for using a subclass ofQAbstractXmlNodeModel in combination withQXmlQuery to perform anXQuery.

1. InstantiateQXmlQuery and give it theXQuery to be run;
2. Instantiate a subclass ofQAbstractXmlNodeModel orQSimpleXmlNodeModel;
3. Retrieve aQXmlNodeModelIndex for the node in the model where theQXmlQuery should start the query;
4. UseQXmlQuery::bindVariable() to bind theQXmlNodeModelIndex to$variable name;
5. Call one of theQXmlQuery evaluation functions to run the query.

Subclassing

Because theXPath Data Model interface presented byQAbstractXmlNodeModel allowsQXmlQuery to operate on non-XML data as if it were XML, implementing subclasses ofQAbstractXmlNodeModel can involve a significant amount of work. TheQSimpleXmlNodeModel class is provided to simplify the implementation for many common use cases.

Thread Safety

Because the node model can be accessed concurrently by threads in theQtXmlPatterns module, subclasses ofQAbstractXmlNodeModel must be written to bethread-safe. Classes that simplify implementing thread-safety includeQReadLocker andQWriteLocker.

See the exampleFile System Example for a demonstration.

Member Type Documentation

typedef QAbstractXmlNodeModel::List

Alist ofsmart pointers to instances ofQAbstractXmlNodeModel.

See alsoQExplicitlySharedDataPointer.

typedef QAbstractXmlNodeModel::Ptr

Asmart pointer to an instance ofQAbstractXmlNodeModel.

See alsoQExplicitlySharedDataPointer.

enum QAbstractXmlNodeModel::SimpleAxis

Four axes that each contain one node only.

Member Function Documentation

QAbstractXmlNodeModel::QAbstractXmlNodeModel()

Default constructor.

[virtual]QAbstractXmlNodeModel::~QAbstractXmlNodeModel()

Destructor.

[pure virtual protected]QVector<QXmlNodeModelIndex> QAbstractXmlNodeModel::attributes(constQXmlNodeModelIndex & element) const

Returns the attributes ofelement. The caller guarantees thatelement is an element in this node model.

[pure virtual]QUrl QAbstractXmlNodeModel::baseUri(constQXmlNodeModelIndex & n) const

Returns the base URI for the node whose index isn. The caller guarantees thatn is notnull and that it belongs to a node in this node model.

The base URI of a node can be extracted using thefn:base-uri() function. The base URI is typically used for resolving relative URIs that appear in the node or its children. It is conformant to just return the document URI, although that might not properly reflect the underlying data.

This function maps to thedm:base-uri accessor, which returns a base URI according to the following:

• For document nodes, the base URI and the document URI are the same.
• For elements, the base URI is the URI appearing in the element'sxml:base attribute, if present, or it is resolved to the parent element's base URI.
• Namespace nodes have no base URI.
• The base URI for a processing instruction, comment, attribute, or text node is the base URI of the node's parent element.

The implementation guarantees to return a validQUrl, or a default constructedQUrl. If a node has no base URI, as in the case where a comment has no parent, a default constructedQUrl is returned.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 5.2 base-uri Accessor.

[pure virtual]QXmlNodeModelIndex::DocumentOrder QAbstractXmlNodeModel::compareOrder(constQXmlNodeModelIndex & ni1, constQXmlNodeModelIndex & ni2) const

This function returns the relative document order for the nodes indexed byni1 andni2. It is used for theIs operator and for sorting nodes in document order.

The caller guarantees thatni1 andni2 are notnull and that both identify nodes in this node model.

Ifni1 is identical toni2,QXmlNodeModelIndex::Is is returned. Ifni1 precedesni2 in document order,QXmlNodeModelIndex::Precedes is returned. Ifni1 followsni2 in document order,QXmlNodeModelIndex::Follows is returned.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 2.4 Document Order.

[protected]QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(qint64 data) const

Creates a node index withdata as its internal data.data is not constrained.

[protected]QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(void * pointer,qint64 additionalData = 0) const

Creates a node index withpointer andadditionalData as its internal data.

Whatpointer andadditionalData is, is not constrained.

[protected]QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(qint64 data,qint64 additionalData) const

This is an overloaded function.

Creates aQXmlNodeModelIndex containingdata andadditionalData.

[pure virtual]QUrl QAbstractXmlNodeModel::documentUri(constQXmlNodeModelIndex & n) const

Returns the document URI ofn. The document URI identifies the resource which is the document. For example, the document could be a regular file, e.g.,file:/, or it could be thehttp:// URL of the location of a file. The document URI is used for resolving URIs and to simply know where the document is.

If the node model maps to a URI in a natural way, return that URI. Otherwise, return the company or product URI. The document URI can be any URI as long as its valid and absolute.

The caller guarantees thatn is notnull and that it belongs to thisQAbstractXmlNodeModel.

This function maps to thedm:document-uri accessor, which returns a document URI according to the following:

• Ifn is a document node, return an absoluteQUrl containing the document URI, or a default constructedQUrl. The latter signals that no document URI is available for the document node.
• For all other nodes, return a default constructedQUrl.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 5.4 document-uri Accessor,QUrl::isValid(), andQUrl::isRelative().

[pure virtual]QXmlNodeModelIndex QAbstractXmlNodeModel::elementById(constQXmlName & id) const

Returns the index of the element identified asid.XQuery'sid() function calls this function.

The node index returned will be the element node whose value is of typeID and equalsid, or it will be the element node that has an attribute whose typed value is of typeID and equalsid. If there is no such element, a default constructedQXmlNodeModelIndex instance is returned. The implementor guarantees that if the returned node index is not null, it identifies an element.

It is not sufficient for an attribute or element to merely be calledid. Its value type must also beID. However, the reserved namexml:id is sufficient.

Inid, thenamespace URI and theprefix are undefined, and thelocal name is the ID that should be looked up.

See alsoXQuery 1.0 and XPath 2.0 Functions and Operators, 15.5.2 fn:id.

[pure virtual]QXmlNodeModelIndex::NodeKind QAbstractXmlNodeModel::kind(constQXmlNodeModelIndex & ni) const

Returns a value indicating the kind of node identified byni. The caller guarantees thatni is not null and that it identifies a node in this node model. This function maps to thedm:node-kind() accessor.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 5.10 node-kind Accessor.

[pure virtual]QXmlName QAbstractXmlNodeModel::name(constQXmlNodeModelIndex & ni) const

Returns the name ofni. The caller guarantees thatni is notnull and that it belongs to thisQAbstractXmlNodeModel.

If a node does not have a name, e.g., comment nodes, a nullQXmlName is returned. QXmlNames must be created with the instance ofQXmlQuery that is being used for evaluating queries using thisQAbstractXmlNodeModel.

This function maps to thedm:node-name() accessor.

Ifni is a processing instruction, aQXmlName is returned with the local name as the target name and the namespace URI and prefix both empty.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 5.11 node-name Accessor andQXmlName.

[pure virtual]QVector<QXmlName> QAbstractXmlNodeModel::namespaceBindings(constQXmlNodeModelIndex & n) const

Returns the in-scope namespaces ofn. The caller guarantees thatn is notnull and that it belongs to thisQAbstractXmlNodeModel.

This function corresponds to thedm:namespace-nodes accessor.

The returned vector of namespace declarations includes namespaces of the ancestors ofn.

The caller guarantees thatn is an Element that belongs to thisQAbstractXmlNodeModel.

[pure virtual protected]QXmlNodeModelIndex QAbstractXmlNodeModel::nextFromSimpleAxis(SimpleAxis axis, constQXmlNodeModelIndex & origin) const

WhenQtXmlPatterns evaluate path expressions, it emulate them through a combination of calls withQSimpleXmlNodeModel::SimpleAxis values. Therefore, the implementation of this function must return the node, if any, that appears on theaxis emanating from theorigin.

If no such node is available, a default constructedQXmlNodeModelIndex is returned.

QSimpleXmlNodeModel eliminates the need to handle redundant corner cases by guaranteeing that it will never ask for:

• Children or siblings for attributes.
• Children for comments, processing instructions, and text nodes.
• Siblings or parents for document nodes.

A typical implementation performs aswitch on the value ofaxis:

QXmlNodeModelIndex MyTreeModel::nextFromSimpleAxis(SimpleAxis axis,constQXmlNodeModelIndex&origin)const{// Convert the QXmlNodeModelIndex to a value that is specific to what we represent.const MyValue value= toMyValue(ni);switch(axis)  {case Parent:return toNodeIndex(value.parent());case FirstChild:case PreviousSibling:case NextSibling:// and so on  }}

[pure virtual]QVector<QXmlNodeModelIndex> QAbstractXmlNodeModel::nodesByIdref(constQXmlName & idref) const

Returns the elements and/or attributes that have anIDREF value equal toidref.XQuery'sidref() function calls this function.

The implementor guarantees that the nodes identified by the returned indexes are elements or attributes.

It is not sufficient for an attribute or element to merely be calledidref. It must also be of typeIDREF. Elements must be typed asxs:IDREF orxs:IDREFS, or, in the case of attributes, asIDREF orIDREFS in the schema.

Inidref, thenamespace URI and theprefix are undefined, and thelocal name is the ID that should be looked up.

See alsoXQuery 1.0 and XPath 2.0 Functions and Operators, 15.5.3 fn:idref.

[pure virtual]QXmlNodeModelIndex QAbstractXmlNodeModel::root(constQXmlNodeModelIndex & n) const

Returns the root node of the tree that contains the node whose index isn. The caller guarantees thatn is notnull and that it identifies a node in this node model.

Ifn identifies a node that is a direct child of the root, parent() would return the sameQXmlNodeModelIndex returned by this function.

QSourceLocation QAbstractXmlNodeModel::sourceLocation(constQXmlNodeModelIndex & index) const

Returns the source location for the object with the givenindex or a default constructedQSourceLocation in case no location information is available.

This function was introduced in Qt 4.6.

[pure virtual]QString QAbstractXmlNodeModel::stringValue(constQXmlNodeModelIndex & n) const

Returns the string value for noden.

The caller guarantees thatn is notnull and that it belong to thisQAbstractXmlNodeModel instance.

This function maps to thedm:string-value() accessor, which the specification completely specifies. Here's a summary:

• For processing instructions, the string value is the data section(excluding any whitespace appearing between the name and the data).
• For text nodes, the string value equals the text node.
• For comments, the content of the comment
• For elements, the concatenation of all text nodes that are descendants. Note, this is not only the children, but the childrens' childrens' text nodes, and so forth.
• For document nodes, the concatenation of all text nodes in the document.

See alsoXQuery 1.0 and XPath 2.0 Data Model (XDM), 5.13 string-value Accessor.

[pure virtual]QVariant QAbstractXmlNodeModel::typedValue(constQXmlNodeModelIndex & node) const

Returns the typed value for nodenode.

The typed value is an atomic value, which an element or attribute contains.

The caller guarantees thatnode is either an element or an attribute. The implementor guarantees that the returnedQVariant has a value which is supported inXQuery. It cannot be an arbitraryQVariant value. The implementor also guarantees thatstringValue() returns a lexical representation of typedValue()(this is guaranteed byQSimpleXmlNodeModel::stringValue()).

If the returnQVariant is a default constructed variant, it signals thatnode has no typed value.