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