[!!!][~API] Extbase (Persistence): $query->execute() now returns a plain array of...
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / QueryInterface.php
1 <?php
2 /***************************************************************
3 * Copyright notice
4 *
5 * (c) 2009 Jochen Rau <jochen.rau@typoplanet.de>
6 * All rights reserved
7 *
8 * This class is a backport of the corresponding class of FLOW3.
9 * All credits go to the v5 team.
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 *
20 * This script is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU General Public License for more details.
24 *
25 * This copyright notice MUST APPEAR in all copies of the script!
26 ***************************************************************/
27
28 /**
29 * A persistence query interface
30 *
31 * @package Extbase
32 * @subpackage Persistence
33 * @version $Id$
34 * @api
35 */
36 interface Tx_Extbase_Persistence_QueryInterface {
37
38 /**
39 * The '=' comparison operator.
40 * @api
41 */
42 const OPERATOR_EQUAL_TO = 1;
43
44 /**
45 * The '!=' comparison operator.
46 * @api
47 */
48 const OPERATOR_NOT_EQUAL_TO = 2;
49
50 /**
51 * The '<' comparison operator.
52 * @api
53 */
54 const OPERATOR_LESS_THAN = 3;
55
56 /**
57 * The '<=' comparison operator.
58 * @api
59 */
60 const OPERATOR_LESS_THAN_OR_EQUAL_TO = 4;
61
62 /**
63 * The '>' comparison operator.
64 * @api
65 */
66 const OPERATOR_GREATER_THAN = 5;
67
68 /**
69 * The '>=' comparison operator.
70 * @api
71 */
72 const OPERATOR_GREATER_THAN_OR_EQUAL_TO = 6;
73
74 /**
75 * The 'like' comparison operator.
76 * @api
77 */
78 const OPERATOR_LIKE = 7;
79
80 /**
81 * The 'contains' comparison operator.
82 * @api
83 */
84 const OPERATOR_CONTAINS = 8;
85
86 /**
87 * The 'in' comparison operator.
88 * @api
89 */
90 const OPERATOR_IN = 9;
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 * An inner join.
100 */
101 const JCR_JOIN_TYPE_INNER = '{http://www.jcp.org/jcr/1.0}joinTypeInner';
102
103 /**
104 * A left-outer join.
105 */
106 const JCR_JOIN_TYPE_LEFT_OUTER = '{http://www.jcp.org/jcr/1.0}joinTypeLeftOuter';
107
108 /**
109 * A right-outer join.
110 */
111 const JCR_JOIN_TYPE_RIGHT_OUTER = '{http://www.jcp.org/jcr/1.0}joinTypeRightOuter';
112
113 /**
114 * Executes the query against the backend and returns the result
115 *
116 * @return array<object> The query result as an array of objects
117 * @api
118 */
119 public function execute();
120
121 /**
122 * Executes the query against the database and returns the number of matching objects
123 *
124 * @return integer The number of matching objects
125 * @api
126 */
127 public function count();
128
129 /**
130 * Sets the property names to order the result by. Expected like this:
131 * array(
132 * 'foo' => Tx_Extbase_Persistence_QueryInterface::ORDER_ASCENDING,
133 * 'bar' => Tx_Extbase_Persistence_QueryInterface::ORDER_DESCENDING
134 * )
135 *
136 * @param array $orderings The property names to order by
137 * @return Tx_Extbase_Persistence_QueryInterface
138 * @api
139 */
140 public function setOrderings(array $orderings);
141
142 /**
143 * Sets the maximum size of the result set to limit. Returns $this to allow
144 * for chaining (fluid interface)
145 *
146 * @param integer $limit
147 * @return Tx_Extbase_Persistence_QueryInterface
148 * @api
149 */
150 public function setLimit($limit);
151
152 /**
153 * Sets the start offset of the result set to offset. Returns $this to
154 * allow for chaining (fluid interface)
155 *
156 * @param integer $offset
157 * @return Tx_Extbase_Persistence_QueryInterface
158 * @api
159 */
160 public function setOffset($offset);
161
162 /**
163 * The constraint used to limit the result set. Returns $this to allow
164 * for chaining (fluid interface)
165 *
166 * @param object $constraint Some constraint, depending on the backend
167 * @return Tx_Extbase_Persistence_QueryInterface
168 * @api
169 */
170 public function matching($constraint);
171
172 /**
173 * Performs a logical conjunction of the two given constraints.
174 *
175 * @param object $constraint1 First constraint
176 * @param object $constraint2 Second constraint
177 * @return object
178 * @api
179 */
180 public function logicalAnd($constraint1, $constraint2);
181
182 /**
183 * Performs a logical disjunction of the two given constraints
184 *
185 * @param object $constraint1 First constraint
186 * @param object $constraint2 Second constraint
187 * @return object
188 * @api
189 */
190 public function logicalOr($constraint1, $constraint2);
191
192 /**
193 * Performs a logical negation of the given constraint
194 *
195 * @param object $constraint Constraint to negate
196 * @return object
197 * @api
198 */
199 public function logicalNot($constraint);
200
201 /**
202 * Matches against the (internal) identifier.
203 *
204 * @param string $uid An identifier to match against
205 * @return object
206 * @api
207 */
208 public function withUid($uid);
209
210 /**
211 * Returns an equals criterion used for matching objects against a query
212 *
213 * @param string $propertyName The name of the property to compare against
214 * @param mixed $operand The value to compare with
215 * @param boolean $caseSensitive Whether the equality test should be done case-sensitive
216 * @return object
217 * @api
218 */
219 public function equals($propertyName, $operand, $caseSensitive = TRUE);
220
221 /**
222 * Returns a like criterion used for matching objects against a query
223 *
224 * @param string $propertyName The name of the property to compare against
225 * @param mixed $operand The value to compare with
226 * @return object
227 * @api
228 */
229 public function like($propertyName, $operand);
230
231 /**
232 * Returns a "contains" criterion used for matching objects against a query.
233 * It matches if the multivalued property contains the given operand.
234 *
235 * @param string $propertyName The name of the (multivalued) property to compare against
236 * @param mixed $operand The value to compare with
237 * @return object
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 * @api
250 */
251 public function in($propertyName, $operand);
252
253 /**
254 * Returns a less than criterion used for matching objects against a query
255 *
256 * @param string $propertyName The name of the property to compare against
257 * @param mixed $operand The value to compare with
258 * @return object
259 * @api
260 */
261 public function lessThan($propertyName, $operand);
262
263 /**
264 * Returns a less or equal than criterion used for matching objects against a query
265 *
266 * @param string $propertyName The name of the property to compare against
267 * @param mixed $operand The value to compare with
268 * @return object
269 * @api
270 */
271 public function lessThanOrEqual($propertyName, $operand);
272
273 /**
274 * Returns a greater than 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 * @api
280 */
281 public function greaterThan($propertyName, $operand);
282
283 /**
284 * Returns a greater than or equal 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 object
289 * @api
290 */
291 public function greaterThanOrEqual($propertyName, $operand);
292
293 }
294 ?>