1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.chemistry.opencmis.client.api;
20
21 import java.net.URI;
22 import java.net.URL;
23 import java.util.Calendar;
24 import java.util.Date;
25
26 import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
27
28 /**
29 * Query Statement.
30 * <p>
31 * Sample code:
32 *
33 * <pre>
34 * Calendar cal = ...
35 * Folder folder = ...
36 *
37 * QueryStatement qs =
38 * session.createQueryStatement("SELECT ?, ? FROM ? WHERE ? > TIMESTAMP ? AND IN_FOLDER(?) OR ? IN (?)");
39 *
40 * qs.setProperty(1, "cmis:document", "cmis:name");
41 * qs.setProperty(2, "cmis:document", "cmis:objectId");
42 * qs.setType(3, "cmis:document");
43 *
44 * qs.setProperty(4, "cmis:document", "cmis:creationDate");
45 * qs.setDateTime(5, cal);
46 *
47 * qs.setId(6, folder);
48 *
49 * qs.setProperty(7, "cmis:document", "cmis:createdBy");
50 * qs.setString(8, "bob", "tom", "lisa");
51 *
52 * String statement = qs.toQueryString();
53 * </pre>
54 */
55 public interface QueryStatement extends Cloneable {
56
57 /**
58 * Sets the designated parameter to the query name of the given type ID.
59 *
60 * @param parameterIndex
61 * the parameter index (one-based)
62 * @param typeId
63 * the type ID
64 */
65 void setType(int parameterIndex, String typeId);
66
67 /**
68 * Sets the designated parameter to the query name of the given type.
69 *
70 * @param parameterIndex
71 * the parameter index (one-based)
72 * @param type
73 * the object type
74 */
75 void setType(int parameterIndex, ObjectType type);
76
77 /**
78 * Sets the designated parameter to the query name of the given property.
79 *
80 * @param parameterIndex
81 * the parameter index (one-based)
82 * @param propertyId
83 * the property ID
84 */
85 void setProperty(int parameterIndex, String typeId, String propertyId);
86
87 /**
88 * Sets the designated parameter to the query name of the given property.
89 *
90 * @param parameterIndex
91 * the parameter index (one-based)
92 * @param propertyDefinition
93 * the property definition
94 */
95 void setProperty(int parameterIndex, PropertyDefinition<?> propertyDefinition);
96
97 /**
98 * Sets the designated parameter to the given number.
99 *
100 * @param parameterIndex
101 * the parameter index (one-based)
102 * @param num
103 * the number
104 */
105 void setNumber(int parameterIndex, Number... num);
106
107 /**
108 * Sets the designated parameter to the given string.
109 *
110 * @param parameterIndex
111 * the parameter index (one-based)
112 * @param str
113 * the string
114 */
115 void setString(int parameterIndex, String... str);
116
117 /**
118 * Sets the designated parameter to the given string. It does not escape
119 * backslashes ('\') in front of '%' and '_'.
120 *
121 * @param parameterIndex
122 * the parameter index (one-based)
123 * @param str
124 * the LIKE string
125 */
126 void setStringLike(int parameterIndex, String str);
127
128 /**
129 * Sets the designated parameter to the given string in a CMIS contains
130 * statement.
131 * <p>
132 * Note that the CMIS specification requires two levels of escaping. The
133 * first level escapes ', ", \ characters to \', \" and \\. The characters
134 * *, ? and - are interpreted as text search operators and are not escaped
135 * on first level. If *, ?, - shall be used as literals, they must be passed
136 * escaped with \*, \? and \- to this method.
137 * <p>
138 * For all statements in a CONTAINS() clause it is required to isolate those
139 * from a query statement. Therefore a second level escaping is performed.
140 * On the second level grammar ", ', - and \ are escaped with a \. See the
141 * spec for further details.
142 * <p>
143 *
144 * Summary:
145 * <table summary="Escaping Summary">
146 * <tr>
147 * <th>input</th>
148 * <th>first level escaping</th>
149 * <th>second level escaping</th>
150 * </tr>
151 * <tr>
152 * <td>*</td>
153 * <td>*</td>
154 * <td>*</td>
155 * </tr>
156 * <tr>
157 * <td>?</td>
158 * <td>?</td>
159 * <td>?</td>
160 * </tr>
161 * <tr>
162 * <td>-</td>
163 * <td>-</td>
164 * <td>-</td>
165 * </tr>
166 * <tr>
167 * <td>\</td>
168 * <td>\\</td>
169 * <td>\\\\<br>
170 * <em>(for any other character following other than * ? -)</em></td>
171 * </tr>
172 * <tr>
173 * <td>\*</td>
174 * <td>\*</td>
175 * <td>\\*</td>
176 * </tr>
177 * <tr>
178 * <td>\?</td>
179 * <td>\?</td>
180 * <td>\\?</td>
181 * </tr>
182 * <tr>
183 * <td>\-</td>
184 * <td>\-</td>
185 * <td>\\-+</td>
186 * </tr>
187 * <tr>
188 * <td>'</td>
189 * <td>\'</td>
190 * <td>\\\'</td>
191 * </tr>
192 * <tr>
193 * <td>"</td>
194 * <td>\"</td>
195 * <td>\\\"</td>
196 * </tr>
197 * </table>
198 *
199 * @param parameterIndex
200 * the parameter index (one-based)
201 * @param str
202 * the CONTAINS string
203 */
204 void setStringContains(int parameterIndex, String str);
205
206 /**
207 * Sets the designated parameter to the given object ID.
208 *
209 * @param parameterIndex
210 * the parameter index (one-based)
211 * @param id
212 * the object ID
213 */
214 void setId(int parameterIndex, ObjectId... id);
215
216 /**
217 * Sets the designated parameter to the given URI.
218 *
219 * @param parameterIndex
220 * the parameter index (one-based)
221 * @param uri
222 * the URI
223 */
224 void setUri(int parameterIndex, URI... uri);
225
226 /**
227 * Sets the designated parameter to the given URL.
228 *
229 * @param parameterIndex
230 * the parameter index (one-based)
231 * @param url
232 * the URL
233 */
234 void setUrl(int parameterIndex, URL... url);
235
236 /**
237 * Sets the designated parameter to the given boolean.
238 *
239 * @param parameterIndex
240 * the parameter index (one-based)
241 * @param bool
242 * the boolean
243 */
244 void setBoolean(int parameterIndex, boolean... bool);
245
246 /**
247 * Sets the designated parameter to the given DateTime value.
248 *
249 * @param parameterIndex
250 * the parameter index (one-based)
251 * @param cal
252 * the DateTime value as Calendar object
253 */
254 void setDateTime(int parameterIndex, Calendar... cal);
255
256 /**
257 * Sets the designated parameter to the given DateTime value.
258 *
259 * @param parameterIndex
260 * the parameter index (one-based)
261 * @param date
262 * the DateTime value as Date object
263 */
264 void setDateTime(int parameterIndex, Date... date);
265
266 /**
267 * Sets the designated parameter to the given DateTime value.
268 *
269 * @param parameterIndex
270 * the parameter index (one-based)
271 * @param ms
272 * the DateTime value in milliseconds from midnight, January 1,
273 * 1970 UTC.
274 */
275 void setDateTime(int parameterIndex, long... ms);
276
277 /**
278 * Sets the designated parameter to the given DateTime value with the prefix
279 * 'TIMESTAMP '.
280 *
281 * @param parameterIndex
282 * the parameter index (one-based)
283 * @param cal
284 * the DateTime value as Calendar object
285 */
286 void setDateTimeTimestamp(int parameterIndex, Calendar... cal);
287
288 /**
289 * Sets the designated parameter to the given DateTime value with the prefix
290 * 'TIMESTAMP '.
291 *
292 * @param parameterIndex
293 * the parameter index (one-based)
294 * @param date
295 * the DateTime value as Date object
296 */
297 void setDateTimeTimestamp(int parameterIndex, Date... date);
298
299 /**
300 * Sets the designated parameter to the given DateTime value with the prefix
301 * 'TIMESTAMP '.
302 *
303 * @param parameterIndex
304 * the parameter index (one-based)
305 * @param ms
306 * the DateTime value in milliseconds from midnight, January 1,
307 * 1970 UTC.
308 */
309 void setDateTimeTimestamp(int parameterIndex, long... ms);
310
311 /**
312 * Returns the query statement.
313 *
314 * @return the query statement, not {@code null}
315 */
316 String toQueryString();
317
318 /**
319 * Executes the query with {@code searchAllVersions} set to {@code false}.
320 *
321 * @see Session#query(String, boolean)
322 */
323 ItemIterable<QueryResult> query();
324
325 /**
326 * Executes the query.
327 *
328 * @param searchAllVersions
329 * {@code true} if all document versions should be included in
330 * the search results, {@code false} if only the latest document
331 * versions should be included in the search results
332 *
333 *
334 * @see Session#query(String, boolean)
335 */
336 ItemIterable<QueryResult> query(boolean searchAllVersions);
337
338 /**
339 * Executes the query.
340 *
341 * @param searchAllVersions
342 * {@code true} if all document versions should be included in
343 * the search results, {@code false} if only the latest document
344 * versions should be included in the search results
345 * @param context
346 * the operation context to use
347 *
348 * @see Session#query(String, boolean, OperationContext)
349 */
350 ItemIterable<QueryResult> query(boolean searchAllVersions, OperationContext context);
351 }