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