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