277 lines
13 KiB
Plaintext
277 lines
13 KiB
Plaintext
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
#include "domstubs.idl"
|
|
|
|
interface nsIAtom;
|
|
interface nsIArray;
|
|
interface nsISimpleEnumerator;
|
|
interface nsIXULTemplateResult;
|
|
interface nsIXULTemplateRuleFilter;
|
|
interface nsIXULTemplateBuilder;
|
|
|
|
/**
|
|
* 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 <query> 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 <template> element to the variable to use. The
|
|
* member variable may be specified in a similar way using the "member"
|
|
* attribute, or it may be specified in the first <action> body in the
|
|
* template as the value of a uri attribute on an element. A breadth-first
|
|
* search of the first action is performed to find this element.
|
|
*
|
|
* 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.
|
|
*/
|
|
[scriptable, uuid(C257573F-444F-468A-BA27-DE979DC55FE4)]
|
|
interface nsIXULTemplateQueryProcessor : nsISupports
|
|
{
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aDataSources the list of nsIURI objects and/or nsIDOMNode objects
|
|
* @param aRootNode the root node the builder is attached to
|
|
* @param aIsTrusted true if the template is in a trusted document
|
|
* @param aBuilder the template builder
|
|
* @param aShouldDelayBuilding [out] whether the builder should wait to
|
|
* build the content or not
|
|
* @returns a datasource object
|
|
*/
|
|
nsISupports getDatasource(in nsIArray aDataSources,
|
|
in nsIDOMNode aRootNode,
|
|
in boolean aIsTrusted,
|
|
in nsIXULTemplateBuilder aBuilder,
|
|
out boolean aShouldDelayBuilding);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aDatasource datasource for the data
|
|
* @param aBuilder the template builder
|
|
* @param aRootNode the root node the builder is attached to
|
|
*
|
|
* @throws NS_ERROR_INVALID_ARG if the datasource is not supported or
|
|
* NS_ERROR_UNEXPECTED if generateResults has already been called.
|
|
*/
|
|
void initializeForBuilding(in nsISupports aDatasource,
|
|
in nsIXULTemplateBuilder aBuilder,
|
|
in nsIDOMNode aRootNode);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
void done();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aBuilder the template builder
|
|
* @param aQuery <query> node to compile
|
|
* @param aRefVariable the reference variable
|
|
* @param aMemberVariable the member variable
|
|
*
|
|
* @returns a compiled query object
|
|
*/
|
|
nsISupports compileQuery(in nsIXULTemplateBuilder aBuilder,
|
|
in nsIDOMNode aQuery,
|
|
in nsIAtom aRefVariable,
|
|
in nsIAtom aMemberVariable);
|
|
|
|
/**
|
|
* Generate the results of a query and return them in an enumerator. The
|
|
* enumerator must contain nsIXULTemplateResult objects. If there are no
|
|
* results, an empty enumerator must be returned.
|
|
*
|
|
* The datasource will be the same as the one passed to the earlier
|
|
* initializeForBuilding method. The context reference (aRef) is a reference
|
|
* point used when calculating results.
|
|
*
|
|
* The value of aQuery must be the result of a previous call to compileQuery
|
|
* from this query processor. This method may be called multiple times,
|
|
* typically with different values for aRef.
|
|
*
|
|
* @param aDatasource datasource for the data
|
|
* @param aRef context reference value used as a starting point
|
|
* @param aQuery the compiled query returned from query compilation
|
|
*
|
|
* @returns an enumerator of nsIXULTemplateResult objects as the results
|
|
*
|
|
* @throws NS_ERROR_INVALID_ARG if aQuery is invalid
|
|
*/
|
|
nsISimpleEnumerator generateResults(in nsISupports aDatasource,
|
|
in nsIXULTemplateResult aRef,
|
|
in nsISupports aQuery);
|
|
|
|
/**
|
|
* Add a variable binding for a particular rule. A binding allows an
|
|
* additional variable to be set for a result, outside of those defined
|
|
* within the query. These bindings are always optional, in that they will
|
|
* never affect the results generated.
|
|
*
|
|
* This function will never be called after generateResults. Any bindings
|
|
* that were added should be applied to each result when the result's
|
|
* ruleMatched method is called, since the bindings are different for each
|
|
* rule.
|
|
*
|
|
* The reference aRef may be used to determine the reference when
|
|
* calculating the value for the binding, for example when a value should
|
|
* depend on the value of another variable.
|
|
*
|
|
* The syntax of the expression aExpr is defined by the query processor. If
|
|
* the syntax is invalid, the binding should be ignored. Only fatal errors
|
|
* should be thrown, or NS_ERROR_UNEXPECTED if generateResults has already
|
|
* been called.
|
|
*
|
|
* As an example, if the reference aRef is the variable '?count' which
|
|
* holds the value 5, and the expression aExpr is the string '+2', the value
|
|
* of the variable aVar would be 7, assuming the query processor considers
|
|
* the syntax '+2' to mean add two to the reference.
|
|
*
|
|
* @param aRuleNode rule to add the binding to
|
|
* @param aVar variable that will be bound
|
|
* @param aRef variable that holds reference value
|
|
* @param aExpr expression used to compute the value to assign
|
|
*/
|
|
void addBinding(in nsIDOMNode aRuleNode,
|
|
in nsIAtom aVar,
|
|
in nsIAtom aRef,
|
|
in AString aExpr);
|
|
|
|
/**
|
|
* Translate a ref attribute string into a result. This is used as the
|
|
* reference point by the template builder when generating the first level
|
|
* of content. For recursive generation, the result from the parent
|
|
* generation phase will be used directly as the reference so a translation
|
|
* is not needed. This allows all levels to be generated using objects that
|
|
* all implement the nsIXULTemplateResult interface.
|
|
*
|
|
* This method may be called before initializeForBuilding, so the
|
|
* implementation may use the supplied datasource if it is needed to
|
|
* translate the reference.
|
|
*
|
|
* @param aDatasource datasource for the data
|
|
* @param aRefString the ref attribute string
|
|
*
|
|
* @return the translated ref
|
|
*/
|
|
nsIXULTemplateResult translateRef(in nsISupports aDatasource,
|
|
in AString aRefString);
|
|
|
|
/**
|
|
* Compare two results to determine their order, used when sorting results.
|
|
* This method should return -1 when the left result is less than the right,
|
|
* 0 if both are equivalent, and 1 if the left is greater than the right.
|
|
* The comparison should only consider the values for the specified
|
|
* variable.
|
|
*
|
|
* If the comparison variable is null, the results may be
|
|
* sorted in a natural order, for instance, based on the order the data in
|
|
* stored in the datasource.
|
|
*
|
|
* The sort hints are the flags in nsIXULSortService.
|
|
*
|
|
* This method must only be called with results that were created by this
|
|
* query processor.
|
|
*
|
|
* @param aLeft the left result to compare
|
|
* @param aRight the right result to compare
|
|
* @param aVar variable to compare
|
|
*
|
|
* @param returns -1 if less, 0 if equal, or 1 if greater
|
|
*/
|
|
int32_t compareResults(in nsIXULTemplateResult aLeft,
|
|
in nsIXULTemplateResult aRight,
|
|
in nsIAtom aVar,
|
|
in unsigned long aSortHints);
|
|
};
|