68a05a27c8501efa53183027b9c25b1fe78b0084
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / QueryInterface.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Persistence;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 /**
18 * A persistence query interface
19 *
20 * @api
21 */
22 interface QueryInterface {
23
24 /**
25 * The '=' comparison operator.
26 *
27 * @api
28 */
29 const OPERATOR_EQUAL_TO = 1;
30
31 /**
32 * For NULL we have to use 'IS' instead of '='
33 *
34 * @api
35 */
36 const OPERATOR_EQUAL_TO_NULL = 101;
37
38 /**
39 * The '!=' comparison operator.
40 *
41 * @api
42 */
43 const OPERATOR_NOT_EQUAL_TO = 2;
44
45 /**
46 * For NULL we have to use 'IS NOT' instead of '!='
47 *
48 * @api
49 */
50 const OPERATOR_NOT_EQUAL_TO_NULL = 202;
51
52 /**
53 * The '<' comparison operator.
54 *
55 * @api
56 */
57 const OPERATOR_LESS_THAN = 3;
58
59 /**
60 * The '<=' comparison operator.
61 *
62 * @api
63 */
64 const OPERATOR_LESS_THAN_OR_EQUAL_TO = 4;
65
66 /**
67 * The '>' comparison operator.
68 *
69 * @api
70 */
71 const OPERATOR_GREATER_THAN = 5;
72
73 /**
74 * The '>=' comparison operator.
75 *
76 * @api
77 */
78 const OPERATOR_GREATER_THAN_OR_EQUAL_TO = 6;
79
80 /**
81 * The 'like' comparison operator.
82 *
83 * @api
84 */
85 const OPERATOR_LIKE = 7;
86
87 /**
88 * The 'contains' comparison operator for collections.
89 *
90 * @api
91 */
92 const OPERATOR_CONTAINS = 8;
93
94 /**
95 * The 'in' comparison operator.
96 *
97 * @api
98 */
99 const OPERATOR_IN = 9;
100
101 /**
102 * The 'is NULL' comparison operator.
103 *
104 * @api
105 */
106 const OPERATOR_IS_NULL = 10;
107
108 /**
109 * The 'is empty' comparison operator for collections.
110 *
111 * @api
112 */
113 const OPERATOR_IS_EMPTY = 11;
114
115 /**
116 * Constants representing the direction when ordering result sets.
117 */
118 const ORDER_ASCENDING = 'ASC';
119 const ORDER_DESCENDING = 'DESC';
120
121 /**
122 * Gets the node-tuple source for this query.
123 *
124 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\SourceInterface the node-tuple source; non-NULL
125 * @deprecated since Extbase 6.0, will be removed in Extbase 7.0. It is deprecated only in the interface to be more
126 * in sync with Flow in future and will stay in Generic Persistence.
127 */
128 public function getSource();
129
130 /**
131 * Executes the query and returns the result.
132 *
133 * @param bool $returnRawQueryResult avoids the object mapping by the persistence
134 * @return \TYPO3\CMS\Extbase\Persistence\QueryResultInterface|array The query result object or an array if $returnRawQueryResult is TRUE
135 * @api
136 */
137 public function execute($returnRawQueryResult = FALSE);
138
139 /**
140 * Sets the property names to order the result by. Expected like this:
141 * array(
142 * 'foo' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_ASCENDING,
143 * 'bar' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_DESCENDING
144 * )
145 *
146 * @param array $orderings The property names to order by
147 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
148 * @api
149 */
150 public function setOrderings(array $orderings);
151
152 /**
153 * Sets the maximum size of the result set to limit. Returns $this to allow
154 * for chaining (fluid interface).
155 *
156 * @param int $limit
157 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
158 * @api
159 */
160 public function setLimit($limit);
161
162 /**
163 * Sets the start offset of the result set to offset. Returns $this to
164 * allow for chaining (fluid interface).
165 *
166 * @param int $offset
167 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
168 * @api
169 */
170 public function setOffset($offset);
171
172 /**
173 * The constraint used to limit the result set. Returns $this to allow
174 * for chaining (fluid interface).
175 *
176 * @param object $constraint Some constraint, depending on the backend
177 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
178 * @api
179 */
180 public function matching($constraint);
181
182 /**
183 * Performs a logical conjunction of the two given constraints. The method
184 * takes one or more constraints and concatenates them with a boolean AND.
185 * It also accepts a single array of constraints to be concatenated.
186 *
187 * @param mixed $constraint1 The first of multiple constraints or an array of constraints.
188 * @return object
189 * @api
190 */
191 public function logicalAnd($constraint1);
192
193 /**
194 * Performs a logical disjunction of the two given constraints. The method
195 * takes one or more constraints and concatenates them with a boolean OR.
196 * It also accepts a single array of constraints to be concatenated.
197 *
198 * @param mixed $constraint1 The first of multiple constraints or an array of constraints.
199 * @return object
200 * @api
201 */
202 public function logicalOr($constraint1);
203
204 /**
205 * Performs a logical negation of the given constraint
206 *
207 * @param \TYPO3\CMS\Extbase\Persistence\Generic\Qom\ConstraintInterface $constraint Constraint to negate
208 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\NotInterface
209 * @api
210 */
211 public function logicalNot(\TYPO3\CMS\Extbase\Persistence\Generic\Qom\ConstraintInterface $constraint);
212
213 /**
214 * Returns an equals criterion used for matching objects against a query.
215 *
216 * It matches if the $operand equals the value of the property named
217 * $propertyName. If $operand is NULL a strict check for NULL is done. For
218 * strings the comparison can be done with or without case-sensitivity.
219 *
220 * @param string $propertyName The name of the property to compare against
221 * @param mixed $operand The value to compare with
222 * @param bool $caseSensitive Whether the equality test should be done case-sensitive for strings
223 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\ComparisonInterface
224 * @api
225 */
226 public function equals($propertyName, $operand, $caseSensitive = TRUE);
227
228 /**
229 * Returns a like criterion used for matching objects against a query.
230 * Matches if the property named $propertyName is like the $operand, using
231 * standard SQL wildcards.
232 *
233 * @param string $propertyName The name of the property to compare against
234 * @param string $operand The value to compare with
235 * @param bool $caseSensitive Whether the matching should be done case-sensitive
236 * @return object
237 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a non-string property
238 * @api
239 */
240 public function like($propertyName, $operand, $caseSensitive = TRUE);
241
242 /**
243 * Returns a "contains" criterion used for matching objects against a query.
244 * It matches if the multivalued property contains the given operand.
245 *
246 * If NULL is given as $operand, there will never be a match!
247 *
248 * @param string $propertyName The name of the multivalued property to compare against
249 * @param mixed $operand The value to compare with
250 * @return object
251 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a single-valued property
252 * @api
253 */
254 public function contains($propertyName, $operand);
255
256 /**
257 * Returns an "in" criterion used for matching objects against a query. It
258 * matches if the property's value is contained in the multivalued operand.
259 *
260 * @param string $propertyName The name of the property to compare against
261 * @param mixed $operand The value to compare with, multivalued
262 * @return object
263 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property
264 * @api
265 */
266 public function in($propertyName, $operand);
267
268 /**
269 * Returns a less than criterion used for matching objects against a query
270 *
271 * @param string $propertyName The name of the property to compare against
272 * @param mixed $operand The value to compare with
273 * @return object
274 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
275 * @api
276 */
277 public function lessThan($propertyName, $operand);
278
279 /**
280 * Returns a less or equal than criterion used for matching objects against a query
281 *
282 * @param string $propertyName The name of the property to compare against
283 * @param mixed $operand The value to compare with
284 * @return object
285 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
286 * @api
287 */
288 public function lessThanOrEqual($propertyName, $operand);
289
290 /**
291 * Returns a greater than criterion used for matching objects against a query
292 *
293 * @param string $propertyName The name of the property to compare against
294 * @param mixed $operand The value to compare with
295 * @return object
296 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
297 * @api
298 */
299 public function greaterThan($propertyName, $operand);
300
301 /**
302 * Returns a greater than or equal criterion used for matching objects against a query
303 *
304 * @param string $propertyName The name of the property to compare against
305 * @param mixed $operand The value to compare with
306 * @return object
307 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
308 * @api
309 */
310 public function greaterThanOrEqual($propertyName, $operand);
311
312 /**
313 * Returns the type this query cares for.
314 *
315 * @return string
316 * @api
317 */
318 public function getType();
319
320 /**
321 * Sets the Query Settings. These Query settings must match the settings expected by
322 * the specific Storage Backend.
323 *
324 * @param \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface $querySettings The Query Settings
325 * @return void
326 * @todo decide whether this can be deprecated somewhen
327 * @api This method is not part of TYPO3Flow API
328 */
329 public function setQuerySettings(Generic\QuerySettingsInterface $querySettings);
330
331 /**
332 * Returns the Query Settings.
333 *
334 * @return \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface $querySettings The Query Settings
335 * @todo decide whether this can be deprecated eventually
336 * @api This method is not part of TYPO3Flow API
337 */
338 public function getQuerySettings();
339
340 /**
341 * Returns the query result count.
342 *
343 * @return int The query result count
344 * @api
345 */
346 public function count();
347
348 /**
349 * Gets the property names to order the result by, like this:
350 * array(
351 * 'foo' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_ASCENDING,
352 * 'bar' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_DESCENDING
353 * )
354 *
355 * @return array
356 * @api
357 */
358 public function getOrderings();
359
360 /**
361 * Returns the maximum size of the result set to limit.
362 *
363 * @return int
364 * @api
365 */
366 public function getLimit();
367
368 /**
369 * Returns the start offset of the result set.
370 *
371 * @return int
372 * @api
373 */
374 public function getOffset();
375
376 /**
377 * Gets the constraint for this query.
378 *
379 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\ConstraintInterface|NULL the constraint, or null if none
380 * @api
381 */
382 public function getConstraint();
383
384 /**
385 * Returns an "isEmpty" criterion used for matching objects against a query.
386 * It matches if the multivalued property contains no values or is NULL.
387 *
388 * @param string $propertyName The name of the multivalued property to compare against
389 * @return bool
390 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a single-valued property
391 * @api
392 */
393 public function isEmpty($propertyName);
394
395 /**
396 * Sets the source to fetch the result from
397 *
398 * @param \TYPO3\CMS\Extbase\Persistence\Generic\Qom\SourceInterface $source
399 */
400 public function setSource(Generic\Qom\SourceInterface $source);
401
402 /**
403 * Returns the statement of this query.
404 *
405 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\Statement
406 */
407 public function getStatement();
408
409 }