1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/xul/templates/public/nsIXULTemplateQueryProcessor.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,276 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "domstubs.idl"
1.10 +
1.11 +interface nsIAtom;
1.12 +interface nsIArray;
1.13 +interface nsISimpleEnumerator;
1.14 +interface nsIXULTemplateResult;
1.15 +interface nsIXULTemplateRuleFilter;
1.16 +interface nsIXULTemplateBuilder;
1.17 +
1.18 +/**
1.19 + * A query processor takes a template query and generates results for it given
1.20 + * a datasource and a reference point. There is a one-to-one relationship
1.21 + * between a template builder and a query processor. The template builder
1.22 + * creates the query processor, and there is no other means to retrieve it.
1.23 + *
1.24 + * A template query is the contents inside a <query> element within the
1.25 + * template. The actual syntax is opaque to the template builder and defined
1.26 + * by a query processor. The query is expected to consist of either text or
1.27 + * DOM nodes that, when executed by a call to the generateResults method, will
1.28 + * allow the generation of a list of results.
1.29 + *
1.30 + * The template builder will supply two variables, the reference variable and
1.31 + * the member variable to further indicate what part of the datasource is to
1.32 + * be examined in addition to the query itself. The reference is always
1.33 + * a placeholder for the starting point and the member is always a placeholder
1.34 + * for the end points (the results).
1.35 + *
1.36 + * The reference point is important when generating output recursively, as
1.37 + * the query will be the same for each iteration, however, the reference point
1.38 + * will differ.
1.39 + *
1.40 + * For instance, when examining an XML source, an XML query processor might
1.41 + * begin at the node referred by the reference variable and end at a list of
1.42 + * that node's children.
1.43 + *
1.44 + * Some queries may not need the reference variable if the syntax or the form
1.45 + * of the data implies the value. For instance, a datasource that holds a
1.46 + * table that can only produce one set of results.
1.47 + *
1.48 + * The reference variable may be specified in a template by setting the
1.49 + * "container" attribute on the <template> element to the variable to use. The
1.50 + * member variable may be specified in a similar way using the "member"
1.51 + * attribute, or it may be specified in the first <action> body in the
1.52 + * template as the value of a uri attribute on an element. A breadth-first
1.53 + * search of the first action is performed to find this element.
1.54 + *
1.55 + * If unspecified, the default value of the reference variable is ?uri.
1.56 + *
1.57 + * For example, a query might have the following syntax:
1.58 + *
1.59 + * (?id, ?name, ?url) from Bookmarks where parentfolder = ?start
1.60 + *
1.61 + * This query might generate a result for each bookmark within a given folder.
1.62 + * The variable ?start would be the reference variable, while the variable ?id
1.63 + * would be the member variable, since it is the unique value that identifies
1.64 + * a result. Each result will have the four variables referred to defined for
1.65 + * it and the values may be retrieved using the result's getBindingFor and
1.66 + * getBindingObjectFor methods.
1.67 + *
1.68 + * The template builder must call initializeForBuilding before the other
1.69 + * methods, except for translateRef. The builder will then call compileQuery
1.70 + * for each query in the template to compile the queries. When results need
1.71 + * to be generated, the builder will call generateResults. The
1.72 + * initializeForBuilding, compileQuery and addBinding methods may not be
1.73 + * called after generateResults has been called until the builder indicates
1.74 + * that the generated output is being removed by calling the done method.
1.75 + *
1.76 + * Currently, the datasource supplied to the methods will always be an
1.77 + * nsIRDFDataSource or a DOM node, and will always be the same one in between
1.78 + * calls to initializeForBuilding and done.
1.79 + */
1.80 +[scriptable, uuid(C257573F-444F-468A-BA27-DE979DC55FE4)]
1.81 +interface nsIXULTemplateQueryProcessor : nsISupports
1.82 +{
1.83 + /**
1.84 + * Retrieve the datasource to use for the query processor. The list of
1.85 + * datasources in a template is specified using the datasources attribute as
1.86 + * a space separated list of URIs. This list is processed by the builder and
1.87 + * supplied to the query processor in the aDataSources array as a list of
1.88 + * nsIURI objects or nsIDOMNode objects. This method may return an object
1.89 + * corresponding to these URIs and the builder will supply this object to
1.90 + * other query processor methods. For example, for an XML source, the
1.91 + * datasource might be an nsIDOMNode.
1.92 + *
1.93 + * All of these URIs are checked by the builder so it is safe to use them,
1.94 + * however note that a URI that redirects may still needs to be checked to
1.95 + * ensure that the document containing aRootNode may access it. This is the
1.96 + * responsibility of the query processor if it needs to load the content of
1.97 + * the URI.
1.98 + *
1.99 + * If the query processor needs to load the datasource asynchronously, it
1.100 + * may set the aShouldDelayBuilding returned parameter to true to delay
1.101 + * building the template content, and call the builder's Rebuild method when
1.102 + * the data is available.
1.103 + *
1.104 + * @param aDataSources the list of nsIURI objects and/or nsIDOMNode objects
1.105 + * @param aRootNode the root node the builder is attached to
1.106 + * @param aIsTrusted true if the template is in a trusted document
1.107 + * @param aBuilder the template builder
1.108 + * @param aShouldDelayBuilding [out] whether the builder should wait to
1.109 + * build the content or not
1.110 + * @returns a datasource object
1.111 + */
1.112 + nsISupports getDatasource(in nsIArray aDataSources,
1.113 + in nsIDOMNode aRootNode,
1.114 + in boolean aIsTrusted,
1.115 + in nsIXULTemplateBuilder aBuilder,
1.116 + out boolean aShouldDelayBuilding);
1.117 +
1.118 + /**
1.119 + * Initialize for query generation. This will be called before the rules are
1.120 + * processed and whenever the template is rebuilt. This method must be
1.121 + * called once before any of the other query processor methods except for
1.122 + * translateRef.
1.123 + *
1.124 + * @param aDatasource datasource for the data
1.125 + * @param aBuilder the template builder
1.126 + * @param aRootNode the root node the builder is attached to
1.127 + *
1.128 + * @throws NS_ERROR_INVALID_ARG if the datasource is not supported or
1.129 + * NS_ERROR_UNEXPECTED if generateResults has already been called.
1.130 + */
1.131 + void initializeForBuilding(in nsISupports aDatasource,
1.132 + in nsIXULTemplateBuilder aBuilder,
1.133 + in nsIDOMNode aRootNode);
1.134 +
1.135 + /**
1.136 + * Called when the template builder is being destroyed so that the query
1.137 + * processor can clean up any state. The query processor should remove as
1.138 + * much state as possible, such as results or references to the builder.
1.139 + * This method will also be called when the template is going to be rebuilt.
1.140 + */
1.141 + void done();
1.142 +
1.143 + /**
1.144 + * Compile a query from a node. The result of this function will later be
1.145 + * passed to generateResults for result generation. If null is returned,
1.146 + * the query will be ignored.
1.147 + *
1.148 + * The template builder will call this method once for each query within
1.149 + * the template, before any results can be generated using generateResults,
1.150 + * but after initializeForBuilding has been called. This method should not
1.151 + * be called again for the same query unless the template is rebuilt.
1.152 + *
1.153 + * The reference variable may be used by the query processor as a
1.154 + * placeholder for the reference point, or starting point in the query.
1.155 + *
1.156 + * The member variable is determined from the member attribute on the
1.157 + * template, or from the uri in the first action's rule if that attribute is
1.158 + * not present. A rule processor may use the member variable as a hint to
1.159 + * indicate what variable is expected to contain the results.
1.160 + *
1.161 + * @param aBuilder the template builder
1.162 + * @param aQuery <query> node to compile
1.163 + * @param aRefVariable the reference variable
1.164 + * @param aMemberVariable the member variable
1.165 + *
1.166 + * @returns a compiled query object
1.167 + */
1.168 + nsISupports compileQuery(in nsIXULTemplateBuilder aBuilder,
1.169 + in nsIDOMNode aQuery,
1.170 + in nsIAtom aRefVariable,
1.171 + in nsIAtom aMemberVariable);
1.172 +
1.173 + /**
1.174 + * Generate the results of a query and return them in an enumerator. The
1.175 + * enumerator must contain nsIXULTemplateResult objects. If there are no
1.176 + * results, an empty enumerator must be returned.
1.177 + *
1.178 + * The datasource will be the same as the one passed to the earlier
1.179 + * initializeForBuilding method. The context reference (aRef) is a reference
1.180 + * point used when calculating results.
1.181 + *
1.182 + * The value of aQuery must be the result of a previous call to compileQuery
1.183 + * from this query processor. This method may be called multiple times,
1.184 + * typically with different values for aRef.
1.185 + *
1.186 + * @param aDatasource datasource for the data
1.187 + * @param aRef context reference value used as a starting point
1.188 + * @param aQuery the compiled query returned from query compilation
1.189 + *
1.190 + * @returns an enumerator of nsIXULTemplateResult objects as the results
1.191 + *
1.192 + * @throws NS_ERROR_INVALID_ARG if aQuery is invalid
1.193 + */
1.194 + nsISimpleEnumerator generateResults(in nsISupports aDatasource,
1.195 + in nsIXULTemplateResult aRef,
1.196 + in nsISupports aQuery);
1.197 +
1.198 + /**
1.199 + * Add a variable binding for a particular rule. A binding allows an
1.200 + * additional variable to be set for a result, outside of those defined
1.201 + * within the query. These bindings are always optional, in that they will
1.202 + * never affect the results generated.
1.203 + *
1.204 + * This function will never be called after generateResults. Any bindings
1.205 + * that were added should be applied to each result when the result's
1.206 + * ruleMatched method is called, since the bindings are different for each
1.207 + * rule.
1.208 + *
1.209 + * The reference aRef may be used to determine the reference when
1.210 + * calculating the value for the binding, for example when a value should
1.211 + * depend on the value of another variable.
1.212 + *
1.213 + * The syntax of the expression aExpr is defined by the query processor. If
1.214 + * the syntax is invalid, the binding should be ignored. Only fatal errors
1.215 + * should be thrown, or NS_ERROR_UNEXPECTED if generateResults has already
1.216 + * been called.
1.217 + *
1.218 + * As an example, if the reference aRef is the variable '?count' which
1.219 + * holds the value 5, and the expression aExpr is the string '+2', the value
1.220 + * of the variable aVar would be 7, assuming the query processor considers
1.221 + * the syntax '+2' to mean add two to the reference.
1.222 + *
1.223 + * @param aRuleNode rule to add the binding to
1.224 + * @param aVar variable that will be bound
1.225 + * @param aRef variable that holds reference value
1.226 + * @param aExpr expression used to compute the value to assign
1.227 + */
1.228 + void addBinding(in nsIDOMNode aRuleNode,
1.229 + in nsIAtom aVar,
1.230 + in nsIAtom aRef,
1.231 + in AString aExpr);
1.232 +
1.233 + /**
1.234 + * Translate a ref attribute string into a result. This is used as the
1.235 + * reference point by the template builder when generating the first level
1.236 + * of content. For recursive generation, the result from the parent
1.237 + * generation phase will be used directly as the reference so a translation
1.238 + * is not needed. This allows all levels to be generated using objects that
1.239 + * all implement the nsIXULTemplateResult interface.
1.240 + *
1.241 + * This method may be called before initializeForBuilding, so the
1.242 + * implementation may use the supplied datasource if it is needed to
1.243 + * translate the reference.
1.244 + *
1.245 + * @param aDatasource datasource for the data
1.246 + * @param aRefString the ref attribute string
1.247 + *
1.248 + * @return the translated ref
1.249 + */
1.250 + nsIXULTemplateResult translateRef(in nsISupports aDatasource,
1.251 + in AString aRefString);
1.252 +
1.253 + /**
1.254 + * Compare two results to determine their order, used when sorting results.
1.255 + * This method should return -1 when the left result is less than the right,
1.256 + * 0 if both are equivalent, and 1 if the left is greater than the right.
1.257 + * The comparison should only consider the values for the specified
1.258 + * variable.
1.259 + *
1.260 + * If the comparison variable is null, the results may be
1.261 + * sorted in a natural order, for instance, based on the order the data in
1.262 + * stored in the datasource.
1.263 + *
1.264 + * The sort hints are the flags in nsIXULSortService.
1.265 + *
1.266 + * This method must only be called with results that were created by this
1.267 + * query processor.
1.268 + *
1.269 + * @param aLeft the left result to compare
1.270 + * @param aRight the right result to compare
1.271 + * @param aVar variable to compare
1.272 + *
1.273 + * @param returns -1 if less, 0 if equal, or 1 if greater
1.274 + */
1.275 + int32_t compareResults(in nsIXULTemplateResult aLeft,
1.276 + in nsIXULTemplateResult aRight,
1.277 + in nsIAtom aVar,
1.278 + in unsigned long aSortHints);
1.279 +};
