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 }