KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > mmbase > bridge > Query


1 /*
2
3 This software is OSI Certified Open Source Software.
4 OSI Certified is a certification mark of the Open Source Initiative.
5
6 The license (Mozilla version 1.0) can be read at the MMBase site.
7 See http://www.MMBase.org/license
8
9 */

10
11 package org.mmbase.bridge;
12
13 import java.util.SortedSet JavaDoc;
14
15 import org.mmbase.storage.search.*;
16
17 /**
18  * Representation of a (database) query. It is modifiable for use by bridge-users.
19  *
20  * @author Michiel Meeuwissen
21  * @author Pierre van Rooden
22  * @version $Id: Query.java,v 1.40 2006/07/31 13:30:25 michiel Exp $
23  * @since MMBase-1.7
24  * @see org.mmbase.bridge.util.Queries
25  */

26 public interface Query extends SearchQuery, Cacheable, Cloneable JavaDoc {
27
28     /**
29      * Returns the Cloud for which this Query was defined.
30      * @return Cloud
31      */

32     Cloud getCloud();
33
34     /**
35      * Whether this query is 'aggregating'. You can only use 'addAggregatedField' on aggregating querys.
36      * @return <code>true</code> if the query is aggregating
37      * @todo Should this not appear in SearchQuery itself? Or should there be an AggregatingQuery interface?
38      * It is now used in BasicCloud.getList.
39      */

40     boolean isAggregating();
41
42     /**
43      * Adds a NodeManager to this Query. This can normally be done only once. After that you need
44      * to use (one of the) 'addRelationStep'.
45      *
46      * @param nodeManager The nodeManager associated with the step.
47      * @return The 'step' wrapping the NodeManager.
48      * @throws IllegalArgumentException when an invalid argument is supplied.
49      * @see #addRelationStep(NodeManager)
50      */

51     Step addStep(NodeManager nodeManager);
52
53     /**
54      * Sets the alias to the given step.
55      * @param step step to add the alias for
56      * @param alias The alias which must be given to the step. If it is "" an alias should be
57      * generated. 'null' removes the alias.
58      */

59     void setAlias(Step step, String JavaDoc alias);
60
61     /**
62      * Returns the step with given alias, or null if it is not present
63      * @param stepAlias Alias for the step (may also be tableName, in which case the first step for this table is returned)
64      * @return step with given alias
65      */

66     Step getStep(String JavaDoc stepAlias);
67
68     /**
69      * Adds new Relation step to the query. Adds the next step as well, it can be retrieved by
70      * calling <code> {@link org.mmbase.storage.search.RelationStep#getNext getNext()} </code> on
71      * the relationstep, and cast to {@link Step Step}.
72      * @param nodeManager node manager on the other side of the relation
73      * @param role role of a relation
74      * @param searchDir the direction of the relation
75      * @return new Relation step
76      *
77      * @throws IllegalArgumentException when an invalid argument is supplied.
78      * @throws IllegalStateException when there is no previous step.
79      */

80     RelationStep addRelationStep(NodeManager nodeManager, String JavaDoc role, String JavaDoc searchDir);
81
82     /**
83      * If you need to add a 'related' NodeManager without specifying a role/searchDir
84      * simply use these addRelationStep.
85      * @param otherManager node manager on the other side of the relation
86      * @return new Relation step
87      */

88     RelationStep addRelationStep(NodeManager otherManager);
89
90     /**
91      * Adds a field to a step.
92      * @param step step to add field to
93      * @param field field to add
94      * @return new StepField
95      */

96     StepField addField(Step step, Field field);
97
98     /**
99      * Adds a field by string
100      * @param field field to add
101      * @return new StepField
102      */

103     StepField addField(String JavaDoc field);
104
105     /**
106      * Removes all fields from the Query object.
107      */

108     void removeFields();
109
110     /**
111      * Creates a StepField object withouth adding it (needed for aggregated queries).
112      * @param step step to create StepField from
113      * @param field field to create StepField from
114      * @return new StepField
115      */

116     StepField createStepField(Step step, Field field);
117
118     /**
119      * Creates a StepField object withouth adding it (needed for aggregated queries).
120      * @param step step to create StepField from
121      * @param fieldName name of field to create StepField from
122      * @return new StepField
123      */

124     StepField createStepField(Step step, String JavaDoc fieldName);
125
126     /**
127      * Creates the step field for the given name. For a NodeQuery the arguments is simply the name of the
128      * field. For a 'normal' query, it should be prefixed by the (automatic) alias of the Step.
129      * @param fieldIdentifer field identifier to create StepField from
130      * @return new StepField
131      */

132     StepField createStepField(String JavaDoc fieldIdentifer);
133
134     /**
135      * Add an aggregated field to a step
136      * @param step step to add field to
137      * @param field field to add
138      * @param aggregationType Type of aggregation
139      * @return new AggregatedField
140      */

141     AggregatedField addAggregatedField(Step step, Field field, int aggregationType);
142
143     /**
144      * Specifies wether the query result must contain only 'distinct' results.
145      * @param distinct 'distinct' results
146      * @return Query
147      * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setDistinct
148      * @see #isDistinct
149      */

150     Query setDistinct(boolean distinct);
151
152     /**
153      * @see org.mmbase.storage.search.SearchQuery#isDistinct()
154      */

155     boolean isDistinct();
156
157     /**
158      * Limits the query-result to maxNumber records.
159      * @param maxNumber max number of results
160      * @return Query
161      * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setMaxNumber
162      */

163     Query setMaxNumber(int maxNumber);
164
165     /**
166      * Offsets the query-result with offset records.
167      * @param offset offset in results
168      * @return Query
169      * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setOffset
170      */

171     Query setOffset(int offset);
172
173     /**
174      * Gets the 'clean' constraint on this query. I.e. the constraint which were automaticly added
175      * because of security are stripped away, and it is garanteed that you get back what you put in.
176      *
177      * It is adviced that you use this in stead of SearchQuery#getConstraint, because that function
178      * is used by the Query handlers, which <em>do</em> need the security constraints. But otherwise
179      * you don't want to see those.
180      *
181      * @return Constraint
182      * @since MMBase-1.7.1
183      */

184     Constraint getCleanConstraint();
185
186     // Constraints and so on..
187

188
189     /**
190      * Create a contraint (for use with this Query object). The argument is a string, as also can be
191      * used as an argument of the 'non-query' getList. This should be considered legacy.
192      * @param s String with LegacyConstraint
193      * @return LegacyConstraint
194      * @see Cloud#getList(String startNodes, String nodePath, String fields, String constraints, String orderby, String directions, String searchDir, boolean distinct)
195      * @see NodeManager#getList(String constraints, String orderby, String directions)
196      */

197     LegacyConstraint createConstraint(String JavaDoc s);
198
199     /**
200      * Create a contraint (for use with this Query object). The given field must be 'null'.
201      * @param f Stepfield
202      * @return FieldNullConstraint
203      */

204     FieldNullConstraint createConstraint(StepField f);
205
206     /**
207      * Create a contraint (for use with this Query object). The given field must equal the given
208      * value 'v'.
209      * @param f field
210      * @param v value
211      * @return FieldValueConstraint
212      */

213     FieldValueConstraint createConstraint(StepField f, Object JavaDoc v);
214
215     /**
216      * Create a contraint (for use with this Query object). The given field and the given
217      * value 'v', combined with given operator must evaluate to true.
218      * @param f field
219      * @param op operator
220      * @param v value
221      * @return FieldValueConstraint
222      */

223     FieldValueConstraint createConstraint(StepField f, int op, Object JavaDoc v);
224
225     /**
226      * Create a contraint (for use with this Query object). The given date field and the given
227      * value 'v', combined with given operator must evaluate to true for the specified date part.
228      * @param f field
229      * @param op operator
230      * @param v value
231      * @param part part of the date value
232      * @return FieldValueConstraint
233      */

234     FieldValueConstraint createConstraint(StepField f, int op, Object JavaDoc v, int part);
235
236     /**
237      * Create a contraint (for use with this Query object). The two given fields , combined with
238      * given operator must evaluate to true.
239      * @param f field
240      * @param op operator
241      * @param v value
242      * @return CompareFieldsConstraint
243      */

244     CompareFieldsConstraint createConstraint(StepField f, int op, StepField v);
245
246     /**
247      * Create a contraint (for use with this Query object). The given field must lie between the
248      * two given values.
249      * @param f field
250      * @param o1 value one
251      * @param o2 value two
252      * @return FieldValueBetweenConstraint
253      */

254     FieldValueBetweenConstraint createConstraint(StepField f, Object JavaDoc o1, Object JavaDoc o2);
255
256     /**
257      * Create a contraint (for use with this Query object). The given field value must be contained
258      * by the given set of values. If the given set is empty, a FieldValueInConstraint will be
259      * constructed for the number field in stead ('number IN (-1)'), which ensures that also in that
260      * case the logical thing will happen. ('<field> IN ()' fails in most databases).
261      * @param f field
262      * @param v value
263      * @return the new Constraint.
264      */

265     FieldValueInConstraint createConstraint(StepField f, SortedSet JavaDoc v);
266
267     /**
268      * Changes the given constraint's 'case sensitivity' (if applicable). Default it is true.
269      * @param constraint constraint to change
270      * @param sensitive case sensitivity
271      * @return modified FieldConstraint
272      */

273     FieldConstraint setCaseSensitive(FieldConstraint constraint, boolean sensitive);
274
275     /**
276      * Changes the given constraint's 'inverse' (if applicable). Default it is (of course) false.
277      * @param c constraint
278      * @param i inverse
279      * @return Inversed contraint
280      */

281     Constraint setInverse(Constraint c, boolean i);
282
283    /**
284      * Combines two Constraints to one new one, using a boolean operator (AND or OR). Every new
285      * constraint must be combined with the ones you already have with such a new CompositeConstraint.
286      *
287      * If the first constraint is a composite constraint (with the same logical operator), then the
288      * second one will simply be added.
289      * @param c1 constraint one
290      * @param op operator ({@link CompositeConstraint#LOGICAL_AND}, {@link CompositeConstraint#LOGICAL_OR})
291      * @param c2 constraint two
292      * @return a Composite constraint (might not be a new one)
293      */

294     CompositeConstraint createConstraint(Constraint c1, int op, Constraint c2);
295
296     /**
297      * The (composite) constraint can actually be set into the query with this method.
298      * @param c constraint
299      */

300     void setConstraint(Constraint c);
301
302
303     /**
304      * Adds an order on a certain field.
305      * @param f field
306      * @param direction {@link SortOrder#ORDER_ASCENDING} or {@link SortOrder#ORDER_DESCENDING}
307      * @return new SortOrder
308      * @see org.mmbase.storage.search.implementation.BasicSearchQuery#addSortOrder
309      * @since MMBase-1.8
310      */

311     SortOrder addSortOrder(StepField f, int direction, boolean caseSensitive);
312
313     /**
314      * Defaulting version of {@link #addSortOrder(StepField, int, boolean)} (sorting case
315      * insensitively).
316      */

317     SortOrder addSortOrder(StepField f, int direction);
318
319
320
321     /**
322      * Adds a node to a step.
323      * @param s step
324      * @param node node to add
325      */

326     void addNode(Step s, Node node);
327
328     /**
329      * @since MMBase-1.8
330      */

331     void addNode(Step s, int number);
332
333     /**
334      * Whether this query was used or not. If is was used, then you cannot modify it anymore (would
335      * kill caches, and references to 'original query' would get invalid)
336      * @return query already used or not
337      */

338     boolean isUsed();
339
340     /**
341      * Mark this query 'used'. It has to be copied first, if you want to add things to it.
342      * @return if this query is was used before this method call
343      */

344     boolean markUsed();
345
346     /**
347      * Create an (unused) clone
348      * @return Cloned Query
349      */

350     Object JavaDoc clone();
351
352     /**
353      * Clones this object, only without the fields
354      * @return Cloned Query
355      */

356     Query cloneWithoutFields();
357
358     /**
359      * Creates an unused aggregate clone of this query. If this query is not itself aggregated, all
360      * fields are removed (but the contraints on them remain), and you can add aggregated fields
361      * then.
362      * @return Cloned Query
363      */

364     Query aggregatingClone();
365
366     /**
367      * Executes the query and returns the resulting node list.
368      * @since MMBase-1.8
369      */

370     NodeList getList();
371
372     /**
373      * Shows the query in a human-readable SQL form. This is probably not the query which will
374      * actually be sent to the database. This method is provided because 'toString' on a Query object
375      * is pretty complete, but pretty undigestable for mere mortals too.
376      *
377      * @since MMBase-1.8
378      */

379     String JavaDoc toSql();
380
381 }
382
Popular Tags