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