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