forked from mozilla/gecko-dev
-
Notifications
You must be signed in to change notification settings - Fork 2
/
nsIXULTemplateQueryProcessor.idl
277 lines (267 loc) · 12.8 KB
/
nsIXULTemplateQueryProcessor.idl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
/* -*- 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"
#include "nsISupports.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);
};