diff -r 000000000000 -r 6474c204b198 content/xul/templates/public/nsIXULTemplateQueryProcessor.idl
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/content/xul/templates/public/nsIXULTemplateQueryProcessor.idl	Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,276 @@
+/* -*- 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);
+};