001: /*
002:
003: This software is OSI Certified Open Source Software.
004: OSI Certified is a certification mark of the Open Source Initiative.
005:
006: The license (Mozilla version 1.0) can be read at the MMBase site.
007: See http://www.MMBase.org/license
008:
009: */
010:
011: package org.mmbase.bridge;
012:
013: import java.util.SortedSet;
014:
015: import org.mmbase.storage.search.*;
016:
017: /**
018: * Representation of a (database) query. It is modifiable for use by bridge-users.
019: *
020: * @author Michiel Meeuwissen
021: * @author Pierre van Rooden
022: * @version $Id: Query.java,v 1.45 2008/02/16 22:13:53 nklasens Exp $
023: * @since MMBase-1.7
024: * @see org.mmbase.bridge.util.Queries
025: */
026: public interface Query extends SearchQuery, Cloneable {
027:
028: /**
029: * Returns the Cloud for which this Query was defined.
030: * @return Cloud
031: */
032: Cloud getCloud();
033:
034: /**
035: * Whether this query is 'aggregating'. You can only use 'addAggregatedField' on aggregating querys.
036: * @return <code>true</code> if the query is aggregating
037: * @todo Should this not appear in SearchQuery itself? Or should there be an AggregatingQuery interface?
038: * It is now used in BasicCloud.getList.
039: */
040: boolean isAggregating();
041:
042: /**
043: * Adds a NodeManager to this Query. This can normally be done only once. After that you need
044: * to use (one of the) 'addRelationStep'.
045: *
046: * @param nodeManager The nodeManager associated with the step.
047: * @return The 'step' wrapping the NodeManager.
048: * @throws IllegalArgumentException when an invalid argument is supplied.
049: * @see #addRelationStep(NodeManager)
050: */
051: Step addStep(NodeManager nodeManager);
052:
053: /**
054: * Sets the alias to the given step.
055: * @param step step to add the alias for
056: * @param alias The alias which must be given to the step. If it is "" an alias should be
057: * generated. 'null' removes the alias.
058: */
059: void setAlias(Step step, String alias);
060:
061: /**
062: * Returns the step with given alias, or null if it is not present
063: * @param stepAlias Alias for the step (may also be tableName, in which case the first step for this table is returned)
064: * @return step with given alias
065: */
066: Step getStep(String stepAlias);
067:
068: /**
069: * Adds new Relation step to the query. Adds the next step as well, it can be retrieved by
070: * calling <code> {@link org.mmbase.storage.search.RelationStep#getNext getNext()} </code> on
071: * the relationstep, and cast to {@link Step Step}.
072: * @param nodeManager node manager on the other side of the relation
073: * @param role role of a relation
074: * @param searchDir the direction of the relation
075: * @return new Relation step
076: *
077: * @throws IllegalArgumentException when an invalid argument is supplied.
078: * @throws IllegalStateException when there is no previous step.
079: */
080: RelationStep addRelationStep(NodeManager nodeManager, String role,
081: String searchDir);
082:
083: /**
084: * If you need to add a 'related' NodeManager without specifying a role/searchDir
085: * simply use these addRelationStep.
086: * @param otherManager node manager on the other side of the relation
087: * @return new Relation step
088: */
089: RelationStep addRelationStep(NodeManager otherManager);
090:
091: /**
092: * Adds a field to a step.
093: * @param step step to add field to
094: * @param field field to add
095: * @return new StepField
096: */
097: StepField addField(Step step, Field field);
098:
099: /**
100: * Adds a field by string
101: * @param field field to add
102: * @return new StepField
103: */
104: StepField addField(String field);
105:
106: /**
107: * Removes all fields from the Query object.
108: */
109: void removeFields();
110:
111: /**
112: * Creates a StepField object withouth adding it (needed for aggregated queries).
113: * @param step step to create StepField from
114: * @param field field to create StepField from
115: * @return new StepField
116: */
117: StepField createStepField(Step step, Field field);
118:
119: /**
120: * Creates a StepField object withouth adding it (needed for aggregated queries).
121: * @param step step to create StepField from
122: * @param fieldName name of field to create StepField from
123: * @return new StepField
124: */
125: StepField createStepField(Step step, String fieldName);
126:
127: /**
128: * Creates the step field for the given name. For a NodeQuery the arguments is simply the name of the
129: * field. For a 'normal' query, it should be prefixed by the (automatic) alias of the Step.
130: * @param fieldIdentifer field identifier to create StepField from
131: * @return new StepField
132: */
133: StepField createStepField(String fieldIdentifer);
134:
135: /**
136: * Add an aggregated field to a step
137: * @param step step to add field to
138: * @param field field to add
139: * @param aggregationType Type of aggregation
140: * @return new AggregatedField
141: */
142: AggregatedField addAggregatedField(Step step, Field field,
143: int aggregationType);
144:
145: /**
146: * Specifies wether the query result must contain only 'distinct' results.
147: * @param distinct 'distinct' results
148: * @return Query
149: * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setDistinct
150: * @see #isDistinct
151: */
152: Query setDistinct(boolean distinct);
153:
154: /**
155: * @see org.mmbase.storage.search.SearchQuery#isDistinct()
156: */
157: boolean isDistinct();
158:
159: /**
160: * Limits the query-result to maxNumber records.
161: * @param maxNumber max number of results
162: * @return Query
163: * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setMaxNumber
164: */
165: Query setMaxNumber(int maxNumber);
166:
167: /**
168: * Offsets the query-result with offset records.
169: * @param offset offset in results
170: * @return Query
171: * @see org.mmbase.storage.search.implementation.BasicSearchQuery#setOffset
172: */
173: Query setOffset(int offset);
174:
175: /**
176: * Gets the 'clean' constraint on this query. I.e. the constraint which were automaticly added
177: * because of security are stripped away, and it is garanteed that you get back what you put in.
178: *
179: * It is adviced that you use this in stead of SearchQuery#getConstraint, because that function
180: * is used by the Query handlers, which <em>do</em> need the security constraints. But otherwise
181: * you don't want to see those.
182: *
183: * @return Constraint
184: * @since MMBase-1.7.1
185: */
186: Constraint getCleanConstraint();
187:
188: // Constraints and so on..
189:
190: /**
191: * Create a contraint (for use with this Query object). The argument is a string, as also can be
192: * used as an argument of the 'non-query' getList. This should be considered legacy.
193: * @param s String with LegacyConstraint
194: * @return LegacyConstraint
195: * @see Cloud#getList(String startNodes, String nodePath, String fields, String constraints, String orderby, String directions, String searchDir, boolean distinct)
196: * @see NodeManager#getList(String constraints, String orderby, String directions)
197: */
198: LegacyConstraint createConstraint(String s);
199:
200: /**
201: * Create a contraint (for use with this Query object). The given field must be 'null'.
202: * @param f Stepfield
203: * @return FieldNullConstraint
204: */
205: FieldNullConstraint createConstraint(StepField f);
206:
207: /**
208: * Create a contraint (for use with this Query object). The given field must equal the given
209: * value 'v'.
210: * @param f field
211: * @param v value
212: * @return FieldValueConstraint
213: */
214: FieldValueConstraint createConstraint(StepField f, Object v);
215:
216: /**
217: * Create a contraint (for use with this Query object). The given field and the given
218: * value 'v', combined with given operator must evaluate to true.
219: * @param f field
220: * @param op operator
221: * @param v value
222: * @return FieldValueConstraint
223: */
224: FieldValueConstraint createConstraint(StepField f, int op, Object v);
225:
226: /**
227: * Create a contraint (for use with this Query object). The given date field and the given
228: * value 'v', combined with given operator must evaluate to true for the specified date part.
229: * @param f field
230: * @param op operator
231: * @param v value
232: * @param part part of the date value
233: * @return FieldValueConstraint
234: */
235: FieldValueConstraint createConstraint(StepField f, int op,
236: Object v, int part);
237:
238: /**
239: * Create a contraint (for use with this Query object). The two given fields , combined with
240: * given operator must evaluate to true.
241: * @param f field
242: * @param op operator
243: * @param v value
244: * @return CompareFieldsConstraint
245: */
246: CompareFieldsConstraint createConstraint(StepField f, int op,
247: StepField v);
248:
249: /**
250: * Create a contraint (for use with this Query object). The given field must lie between the
251: * two given values.
252: * @param f field
253: * @param o1 value one
254: * @param o2 value two
255: * @return FieldValueBetweenConstraint
256: */
257: FieldValueBetweenConstraint createConstraint(StepField f,
258: Object o1, Object o2);
259:
260: /**
261: * Create a contraint (for use with this Query object). The given field value must be contained
262: * by the given set of values. If the given set is empty, a FieldValueInConstraint will be
263: * constructed for the number field in stead ('number IN (-1)'), which ensures that also in that
264: * case the logical thing will happen. ('<field> IN ()' fails in most databases).
265: * @param f field
266: * @param v value
267: * @return the new Constraint.
268: */
269: FieldValueInConstraint createConstraint(StepField f,
270: SortedSet<? extends Object> v);
271:
272: /**
273: * Changes the given constraint's 'case sensitivity' (if applicable). Default it is true.
274: * @param constraint constraint to change
275: * @param sensitive case sensitivity
276: * @return modified FieldConstraint
277: */
278: FieldConstraint setCaseSensitive(FieldConstraint constraint,
279: boolean sensitive);
280:
281: /**
282: * Changes the given constraint's 'inverse' (if applicable). Default it is (of course) false.
283: * @param c constraint
284: * @param i inverse
285: * @return Inversed contraint
286: */
287: Constraint setInverse(Constraint c, boolean i);
288:
289: /**
290: * Combines two Constraints to one new one, using a boolean operator (AND or OR). Every new
291: * constraint must be combined with the ones you already have with such a new CompositeConstraint.
292: *
293: * If the first constraint is a composite constraint (with the same logical operator), then the
294: * second one will simply be added.
295: * @param c1 constraint one
296: * @param op operator ({@link CompositeConstraint#LOGICAL_AND}, {@link CompositeConstraint#LOGICAL_OR})
297: * @param c2 constraint two
298: * @return a Composite constraint (might not be a new one)
299: */
300: CompositeConstraint createConstraint(Constraint c1, int op,
301: Constraint c2);
302:
303: /**
304: * The (composite) constraint can actually be set into the query with this method.
305: * @param c constraint
306: */
307: void setConstraint(Constraint c);
308:
309: /**
310: * Adds an order on a certain field.
311: * @param f field
312: * @param direction {@link SortOrder#ORDER_ASCENDING} or {@link SortOrder#ORDER_DESCENDING}
313: * @param caseSensitive case sensitivity
314: * @param part part to sort on for a date value
315: * @return new SortOrder
316: * @see org.mmbase.storage.search.implementation.BasicSearchQuery#addSortOrder
317: * @since MMBase-1.9
318: */
319: SortOrder addSortOrder(StepField f, int direction,
320: boolean caseSensitive, int part);
321:
322: /**
323: * Defaulting version of {@link #addSortOrder(StepField, int, boolean, int)} (no date parts)
324: * @param f field
325: * @param direction {@link SortOrder#ORDER_ASCENDING} or {@link SortOrder#ORDER_DESCENDING}
326: * @param caseSensitive case sensitivity
327: * @return new SortOrder
328: * @since MMBase-1.8
329: */
330: SortOrder addSortOrder(StepField f, int direction,
331: boolean caseSensitive);
332:
333: /**
334: * Defaulting version of {@link #addSortOrder(StepField, int, boolean, int)} (sorting case
335: * insensitively, and no date parts).
336: * @param f field
337: * @param direction {@link SortOrder#ORDER_ASCENDING} or {@link SortOrder#ORDER_DESCENDING}
338: * @return new SortOrder
339: */
340: SortOrder addSortOrder(StepField f, int direction);
341:
342: /**
343: * Adds a node to a step.
344: * @param s step
345: * @param node node to add
346: */
347: void addNode(Step s, Node node);
348:
349: /**
350: * @param s query step
351: * @param number node number
352: * @since MMBase-1.8
353: */
354: void addNode(Step s, int number);
355:
356: /**
357: * Whether this query was used or not. If is was used, then you cannot modify it anymore (would
358: * kill caches, and references to 'original query' would get invalid)
359: * @return query already used or not
360: */
361: boolean isUsed();
362:
363: /**
364: * Mark this query 'used'. It has to be copied first, if you want to add things to it.
365: * @return if this query is was used before this method call
366: */
367: boolean markUsed();
368:
369: /**
370: * Create an (unused) clone
371: * @return Cloned Query
372: */
373: Object clone();
374:
375: /**
376: * Clones this object, only without the fields
377: * @return Cloned Query
378: */
379: Query cloneWithoutFields();
380:
381: /**
382: * Creates an unused aggregate clone of this query. If this query is not itself aggregated, all
383: * fields are removed (but the contraints on them remain), and you can add aggregated fields
384: * then.
385: * @return Cloned Query
386: */
387: Query aggregatingClone();
388:
389: /**
390: * Executes the query and returns the resulting node list.
391: * @return resulting node list
392: * @since MMBase-1.8
393: */
394: NodeList getList();
395:
396: /**
397: * Shows the query in a human-readable SQL form. This is probably not the query which will
398: * actually be sent to the database. This method is provided because 'toString' on a Query object
399: * is pretty complete, but pretty undigestable for mere mortals too.
400: * @return human-readable SQL
401: *
402: * @since MMBase-1.8
403: */
404: String toSql();
405:
406: }
|