nsIXULTemplateQueryProcessor

A query processor takes a template query and generates results for it given
a datasource and a reference point. There is a one-to-one relationship
between a template builder and a query processor. The template builder
creates the query processor, and there is no other means to retrieve it.

A template query is the contents inside a element within the template. The actual syntax is opaque to the template builder and defined by a query processor. The query is expected to consist of either text or DOM nodes that, when executed by a call to the generateResults method, will allow the generation of a list of results.

The template builder will supply two variables, the reference variable and
the member variable to further indicate what part of the datasource is to
be examined in addition to the query itself. The reference is always
a placeholder for the starting point and the member is always a placeholder
for the end points (the results).

The reference point is important when generating output recursively, as
the query will be the same for each iteration, however, the reference point
will differ.

For instance, when examining an XML source, an XML query processor might
begin at the node referred by the reference variable and end at a list of
that node’s children.

Some queries may not need the reference variable if the syntax or the form
of the data implies the value. For instance, a datasource that holds a
table that can only produce one set of results.

The reference variable may be specified in a template by setting the
“container” attribute on the

If unspecified, the default value of the reference variable is ?uri.

For example, a query might have the following syntax:

(?id, ?name, ?url) from Bookmarks where parentfolder = ?start

This query might generate a result for each bookmark within a given folder.
The variable ?start would be the reference variable, while the variable ?id
would be the member variable, since it is the unique value that identifies
a result. Each result will have the four variables referred to defined for
it and the values may be retrieved using the result’s getBindingFor and
getBindingObjectFor methods.

The template builder must call initializeForBuilding before the other
methods, except for translateRef. The builder will then call compileQuery
for each query in the template to compile the queries. When results need
to be generated, the builder will call generateResults. The
initializeForBuilding, compileQuery and addBinding methods may not be
called after generateResults has been called until the builder indicates
that the generated output is being removed by calling the done method.

Currently, the datasource supplied to the methods will always be an
nsIRDFDataSource or a DOM node, and will always be the same one in between
calls to initializeForBuilding and done.

Methods

getDatasource(aDataSources, aRootNode, aIsTrusted, aBuilder, aShouldDelayBuilding)

Retrieve the datasource to use for the query processor. The list of
datasources in a template is specified using the datasources attribute as
a space separated list of URIs. This list is processed by the builder and
supplied to the query processor in the aDataSources array as a list of
nsIURI objects or nsIDOMNode objects. This method may return an object
corresponding to these URIs and the builder will supply this object to
other query processor methods. For example, for an XML source, the
datasource might be an nsIDOMNode.

All of these URIs are checked by the builder so it is safe to use them,
however note that a URI that redirects may still needs to be checked to
ensure that the document containing aRootNode may access it. This is the
responsibility of the query processor if it needs to load the content of
the URI.

If the query processor needs to load the datasource asynchronously, it
may set the aShouldDelayBuilding returned parameter to true to delay
building the template content, and call the builder’s Rebuild method when
the data is available.

Parameters

Returns

initializeForBuilding(aDatasource, aBuilder, aRootNode)

Initialize for query generation. This will be called before the rules are
processed and whenever the template is rebuilt. This method must be
called once before any of the other query processor methods except for
translateRef.

@throws NS_ERROR_INVALID_ARG if the datasource is not supported or
NS_ERROR_UNEXPECTED if generateResults has already been called.

Parameters

done()

Called when the template builder is being destroyed so that the query
processor can clean up any state. The query processor should remove as
much state as possible, such as results or references to the builder.
This method will also be called when the template is going to be rebuilt.

compileQuery(aBuilder, aQuery, aRefVariable, aMemberVariable)

Compile a query from a node. The result of this function will later be
passed to generateResults for result generation. If null is returned,
the query will be ignored.

The template builder will call this method once for each query within
the template, before any results can be generated using generateResults,
but after initializeForBuilding has been called. This method should not
be called again for the same query unless the template is rebuilt.

The reference variable may be used by the query processor as a
placeholder for the reference point, or starting point in the query.

The member variable is determined from the member attribute on the
template, or from the uri in the first action’s rule if that attribute is
not present. A rule processor may use the member variable as a hint to
indicate what variable is expected to contain the results.

Parameters