The Tor Browser / file revision

 /* -*- 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);

 };