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