content/xul/templates/public/nsIXULTemplateQueryProcessor.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is Neil Deakin.
  18  * Portions created by the Initial Developer are Copyright (C) 2005
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *  Laurent Jouanneau <laurent.jouanneau@disruptive-innovations.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "domstubs.idl"
  39 #include "nsISupports.idl"
  40
  41 interface nsIAtom;
  42 interface nsIArray;
  43 interface nsISimpleEnumerator;
  44 interface nsIXULTemplateResult;
  45 interface nsIXULTemplateRuleFilter;
  46 interface nsIXULTemplateBuilder;
  47
  48 /**
  49  * A query processor takes a template query and generates results for it given
  50  * a datasource and a reference point. There is a one-to-one relationship
  51  * between a template builder and a query processor. The template builder
  52  * creates the query processor, and there is no other means to retrieve it.
  53  *
  54  * A template query is the contents inside a <query> element within the
  55  * template. The actual syntax is opaque to the template builder and defined
  56  * by a query processor. The query is expected to consist of either text or
  57  * DOM nodes that, when executed by a call to the generateResults method, will
  58  * allow the generation of a list of results.
  59  *
  60  * The template builder will supply two variables, the reference variable and
  61  * the member variable to further indicate what part of the datasource is to
  62  * be examined in addition to the query itself. The reference is always
  63  * a placeholder for the starting point and the member is always a placeholder
  64  * for the end points (the results).
  65  *
  66  * The reference point is important when generating output recursively, as
  67  * the query will be the same for each iteration, however, the reference point
  68  * will differ.
  69  *
  70  * For instance, when examining an XML source, an XML query processor might
  71  * begin at the node referred by the reference variable and end at a list of
  72  * that node's children.
  73  *
  74  * Some queries may not need the reference variable if the syntax or the form
  75  * of the data implies the value. For instance, a datasource that holds a
  76  * table that can only produce one set of results.
  77  *
  78  * The reference variable may be specified in a template by setting the
  79  * "container" attribute on the <template> element to the variable to use. The
  80  * member variable may be specified in a similar way using the "member"
  81  * attribute, or it may be specified in the first <action> body in the
  82  * template as the value of a uri attribute on an element. A breadth-first
  83  * search of the first action is performed to find this element.
  84  *
  85  * If unspecified, the default value of the reference variable is ?uri.
  86  *
  87  * For example, a query might have the following syntax:
  88  *
  89  * (?id, ?name, ?url) from Bookmarks where parentfolder = ?start
  90  *
  91  * This query might generate a result for each bookmark within a given folder.
  92  * The variable ?start would be the reference variable, while the variable ?id
  93  * would be the member variable, since it is the unique value that identifies
  94  * a result. Each result will have the four variables referred to defined for
  95  * it and the values may be retrieved using the result's getBindingFor and
  96  * getBindingObjectFor methods.
  97  *
  98  * The template builder must call initializeForBuilding before the other
  99  * methods, except for translateRef. The builder will then call compileQuery
 100  * for each query in the template to compile the queries. When results need
 101  * to be generated, the builder will call generateResults. The
 102  * initializeForBuilding, compileQuery and addBinding methods may not be
 103  * called after generateResults has been called until the builder indicates
 104  * that the generated output is being removed by calling the done method.
 105  *
 106  * Currently, the datasource supplied to the methods will always be an
 107  * nsIRDFDataSource or a DOM node, and will always be the same one in between
 108  * calls to initializeForBuilding and done.
 109  */
 110 [scriptable, uuid(970f1c36-5d2e-4cbc-a1cf-e3327b50df71)]
 111 interface nsIXULTemplateQueryProcessor : nsISupports
 112 {
 113   /**
 114    * Retrieve the datasource to use for the query processor. The list of
 115    * datasources in a template is specified using the datasources attribute as
 116    * a space separated list of URIs. This list is processed by the builder and
 117    * supplied to the query processor in the aDataSources array as a list of
 118    * nsIURI objects or nsIDOMNode objects. This method may return an object
 119    * corresponding to these URIs and the builder will supply this object to
 120    * other query processor methods. For example, for an XML source, the
 121    * datasource might be an nsIDOMNode.
 122    * All of these URIs are checked by the builder so it is safe to use them.
 123    * If the query processor needs to load the datasource asynchronously, it
 124    * may set the aShouldDelayBuilding returned parameter to true to delay
 125    * building the template content, and call the builder's Rebuild method when
 126    * the data is available.
 127    *
 128    * @param aDataSources  the list of nsIURI objects and/or nsIDOMNode objects
 129    * @param aRootNode     the root node the builder is attached to
 130    * @param aIsTrusted    true if the template is in a trusted document
 131    * @param aBuilder      the template builder
 132    * @param aShouldDelayBuilding [out] whether the builder should wait to
 133    *                                   build the content or not
 134    * @returns a datasource object
 135    */
 136   nsISupports getDatasource(in nsIArray aDataSources,
 137                             in nsIDOMNode aRootNode,
 138                             in boolean aIsTrusted,
 139                             in nsIXULTemplateBuilder aBuilder,
 140                             out boolean aShouldDelayBuilding);
 141
 142   /**
 143    * Initialize for query generation. This will be called before the rules are
 144    * processed and whenever the template is rebuilt. This method must be
 145    * called once before any of the other query processor methods except for
 146    * translateRef.
 147    *
 148    * @param aDatasource datasource for the data
 149    * @param aBuilder the template builder
 150    * @param aRootNode the root node the builder is attached to
 151    *
 152    * @throws NS_ERROR_INVALID_ARG if the datasource is not supported or
 153    *         NS_ERROR_UNEXPECTED if generateResults has already been called.
 154    */
 155   void initializeForBuilding(in nsISupports aDatasource,
 156                              in nsIXULTemplateBuilder aBuilder,
 157                              in nsIDOMNode aRootNode);
 158
 159   /**
 160    * Called when the template builder is being destroyed so that the query
 161    * processor can clean up any state. The query processor should remove as
 162    * much state as possible, such as results or references to the builder.
 163    * This method will also be called when the template is going to be rebuilt.
 164    */
 165   void done();
 166
 167   /**
 168    * Compile a query from a node. The result of this function will later be
 169    * passed to generateResults for result generation. If null is returned,
 170    * the query will be ignored.
 171    *
 172    * The template builder will call this method once for each query within
 173    * the template, before any results can be generated using generateResults,
 174    * but after initializeForBuilding has been called. This method should not
 175    * be called again for the same query unless the template is rebuilt.
 176    *
 177    * The reference variable may be used by the query processor as a
 178    * placeholder for the reference point, or starting point in the query.
 179    *
 180    * The member variable is determined from the member attribute on the
 181    * template, or from the uri in the first action's rule if that attribute is
 182    * not present. A rule processor may use the member variable as a hint to
 183    * indicate what variable is expected to contain the results.
 184    *
 185    * @param aBuilder the template builder
 186    * @param aQuery <query> node to compile
 187    * @param aRefVariable the reference variable
 188    * @param aMemberVariable the member variable
 189    *
 190    * @returns a compiled query object
 191    */
 192   nsISupports compileQuery(in nsIXULTemplateBuilder aBuilder,
 193                            in nsIDOMNode aQuery,
 194                            in nsIAtom aRefVariable,
 195                            in nsIAtom aMemberVariable);
 196
 197   /**
 198    * Generate the results of a query and return them in an enumerator. The
 199    * enumerator must contain nsIXULTemplateResult objects. If there are no
 200    * results, an empty enumerator must be returned.
 201    *
 202    * The datasource will be the same as the one passed to the earlier
 203    * initializeForBuilding method. The context reference (aRef) is a reference
 204    * point used when calculating results.
 205    *
 206    * The value of aQuery must be the result of a previous call to compileQuery
 207    * from this query processor. This method may be called multiple times,
 208    * typically with different values for aRef.
 209    *
 210    * @param aDatasource datasource for the data
 211    * @param aRef context reference value used as a starting point
 212    * @param aQuery the compiled query returned from query compilation
 213    *
 214    * @returns an enumerator of nsIXULTemplateResult objects as the results
 215    *
 216    * @throws NS_ERROR_INVALID_ARG if aQuery is invalid
 217    */
 218   nsISimpleEnumerator generateResults(in nsISupports aDatasource,
 219                                       in nsIXULTemplateResult aRef,
 220                                       in nsISupports aQuery);
 221
 222   /**
 223    * Add a variable binding for a particular rule. A binding allows an
 224    * additional variable to be set for a result, outside of those defined
 225    * within the query. These bindings are always optional, in that they will
 226    * never affect the results generated.
 227    *
 228    * This function will never be called after generateResults. Any bindings
 229    * that were added should be applied to each result when the result's
 230    * ruleMatched method is called, since the bindings are different for each
 231    * rule.
 232    *
 233    * The reference aRef may be used to determine the reference when
 234    * calculating the value for the binding, for example when a value should
 235    * depend on the value of another variable.
 236    *
 237    * The syntax of the expression aExpr is defined by the query processor. If
 238    * the syntax is invalid, the binding should be ignored. Only fatal errors
 239    * should be thrown, or NS_ERROR_UNEXPECTED if generateResults has already
 240    * been called.
 241    *
 242    * As an example, if the reference aRef is the variable '?count' which
 243    * holds the value 5, and the expression aExpr is the string '+2', the value
 244    * of the variable aVar would be 7, assuming the query processor considers
 245    * the syntax '+2' to mean add two to the reference.
 246    *
 247    * @param aRuleNode rule to add the binding to
 248    * @param aVar variable that will be bound
 249    * @param aRef variable that holds reference value
 250    * @param aExpr expression used to compute the value to assign
 251    */
 252   void addBinding(in nsIDOMNode aRuleNode,
 253                   in nsIAtom aVar,
 254                   in nsIAtom aRef,
 255                   in AString aExpr);
 256
 257   /**
 258    * Translate a ref attribute string into a result. This is used as the
 259    * reference point by the template builder when generating the first level
 260    * of content. For recursive generation, the result from the parent
 261    * generation phase will be used directly as the reference so a translation
 262    * is not needed. This allows all levels to be generated using objects that
 263    * all implement the nsIXULTemplateResult interface.
 264    *
 265    * This method may be called before initializeForBuilding, so the
 266    * implementation may use the supplied datasource if it is needed to
 267    * translate the reference.
 268    *
 269    * @param aDatasource datasource for the data
 270    * @param aRefString the ref attribute string
 271    *
 272    * @return the translated ref
 273    */
 274   nsIXULTemplateResult translateRef(in nsISupports aDatasource,
 275                                     in AString aRefString);
 276
 277   /**
 278    * Compare two results to determine their order, used when sorting results.
 279    * This method should return -1 when the left result is less than the right,
 280    * 0 if both are equivalent, and 1 if the left is greater than the right.
 281    * The comparison should only consider the values for the specified
 282    * variable.
 283    *
 284    * If the comparison variable is null, the results may be
 285    * sorted in a natural order, for instance, based on the order the data in
 286    * stored in the datasource.
 287    *
 288    * This method must only be called with results that were created by this
 289    * query processor.
 290    *
 291    * @param aLeft the left result to compare
 292    * @param aRight the right result to compare
 293    * @param aVar variable to compare
 294    *
 295    * @param returns -1 if less, 0 if equal, or 1 if greater
 296    */
 297    PRInt32 compareResults(in nsIXULTemplateResult aLeft,
 298                           in nsIXULTemplateResult aRight,
 299                           in nsIAtom aVar);
 300 };