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.io.Serializable; 22 import java.util.List; 23 import java.util.Locale; 24 import java.util.Map; 25 import java.util.Set; 26 27 import org.apache.chemistry.opencmis.commons.data.Ace; 28 import org.apache.chemistry.opencmis.commons.data.Acl; 29 import org.apache.chemistry.opencmis.commons.data.ContentStream; 30 import org.apache.chemistry.opencmis.commons.data.RepositoryInfo; 31 import org.apache.chemistry.opencmis.commons.enums.AclPropagation; 32 import org.apache.chemistry.opencmis.commons.enums.IncludeRelationships; 33 import org.apache.chemistry.opencmis.commons.enums.RelationshipDirection; 34 import org.apache.chemistry.opencmis.commons.enums.VersioningState; 35 import org.apache.chemistry.opencmis.commons.exceptions.CmisBaseException; 36 import org.apache.chemistry.opencmis.commons.spi.CmisBinding; 37 38 /** 39 * A session is a connection to a CMIS repository with a specific user. 40 * 41 * <p> 42 * Not all operations might be supported the connected repository. Either 43 * OpenCMIS or the repository will throw an exception if an unsupported 44 * operation is called. The capabilities of the repository can be discovered by 45 * evaluating the repository info (see {@link #getRepositoryInfo()}). 46 * </p> 47 * 48 * <p> 49 * Almost all methods might throw exceptions derived from 50 * {@link CmisBaseException} which is a runtime exception! 51 * </p> 52 * 53 * <p> 54 * (Please refer to the <a 55 * href="http://docs.oasis-open.org/cmis/CMIS/v1.0/os/">CMIS specification</a> 56 * for details about the domain model, terms, concepts, base types, properties, 57 * ids and query names, query language, etc.) 58 * </p> 59 */ 60 public interface Session extends Serializable { 61 62 /** 63 * Clears all cached data. This implies that all data will be reloaded from 64 * the repository (depending on the implementation, reloading might be done 65 * immediately or be deferred). 66 */ 67 void clear(); 68 69 // session context 70 71 /** 72 * Returns the underlying binding object. 73 */ 74 CmisBinding getBinding(); 75 76 /** 77 * Returns the current default operation parameters for filtering, paging 78 * and caching. 79 * 80 * <p> 81 * <em>Please note:</em> The returned object is not thread-safe and should 82 * only be modified right after the session has been created and before the 83 * session object has been used. In order to change the default context in 84 * thread-safe manner, create a new {@link OperationContext} object and use 85 * {@link #setDefaultContext(OperationContext)} to apply it. 86 * </p> 87 */ 88 OperationContext getDefaultContext(); 89 90 /** 91 * Sets the current session parameters for filtering, paging and caching. 92 * 93 * @param context 94 * the <code>OperationContext</code> to be used for the session; 95 * if <code>null</code>, a default context is used 96 */ 97 void setDefaultContext(OperationContext context); 98 99 /** 100 * Creates a new operation context object. 101 */ 102 OperationContext createOperationContext(); 103 104 /** 105 * Creates a new operation context object with the given properties. 106 * 107 * @see OperationContext 108 */ 109 OperationContext createOperationContext(Set<String> filter, boolean includeAcls, boolean includeAllowableActions, 110 boolean includePolicies, IncludeRelationships includeRelationships, Set<String> renditionFilter, 111 boolean includePathSegments, String orderBy, boolean cacheEnabled, int maxItemsPerPage); 112 113 /** 114 * Creates an object id from a String. 115 */ 116 ObjectId createObjectId(String id); 117 118 // localization 119 120 /** 121 * Get the current locale to be used for this session. 122 */ 123 Locale getLocale(); 124 125 // services 126 127 /** 128 * Returns the repository info of the repository associated with this 129 * session. 130 */ 131 RepositoryInfo getRepositoryInfo(); 132 133 /** 134 * Gets a factory object that provides methods to create the objects used by 135 * this API. 136 */ 137 ObjectFactory getObjectFactory(); 138 139 // types 140 141 /** 142 * Returns the type definition of the given type id. 143 */ 144 ObjectType getTypeDefinition(String typeId); 145 146 /** 147 * Returns the type children of the given type id. 148 */ 149 ItemIterable<ObjectType> getTypeChildren(String typeId, boolean includePropertyDefinitions); 150 151 /** 152 * Returns the type descendants of the given type id. 153 */ 154 List<Tree<ObjectType>> getTypeDescendants(String typeId, int depth, boolean includePropertyDefinitions); 155 156 // navigation 157 158 /** 159 * Gets the root folder of the repository. 160 */ 161 Folder getRootFolder(); 162 163 /** 164 * Gets the root folder of the repository with the given 165 * {@link OperationContext}. 166 */ 167 Folder getRootFolder(OperationContext context); 168 169 /** 170 * Returns all checked out documents. 171 * 172 * @see Folder#getCheckedOutDocs() 173 */ 174 ItemIterable<Document> getCheckedOutDocs(); 175 176 /** 177 * Returns all checked out documents with the given {@link OperationContext} 178 * . 179 * 180 * @see Folder#getCheckedOutDocs(OperationContext) 181 */ 182 ItemIterable<Document> getCheckedOutDocs(OperationContext context); 183 184 /** 185 * Returns a CMIS object from the session cache. If the object is not in the 186 * cache or the cache is turned off per default {@link OperationContext}, it 187 * will load the object from the repository and puts it into the cache. 188 * 189 * @param objectId 190 * the object id 191 * 192 * @see #getObject(String) 193 */ 194 CmisObject getObject(ObjectId objectId); 195 196 /** 197 * Returns a CMIS object from the session cache. If the object is not in the 198 * cache or the given {@link OperationContext} has caching turned off, it 199 * will load the object from the repository and puts it into the cache. 200 * 201 * @param objectId 202 * the object id 203 * @param context 204 * the {@link OperationContext} to use 205 * 206 * @see #getObject(String, OperationContext) 207 */ 208 CmisObject getObject(ObjectId objectId, OperationContext context); 209 210 /** 211 * Returns a CMIS object from the session cache. If the object is not in the 212 * cache or the cache is turned off per default {@link OperationContext}, it 213 * will load the object from the repository and puts it into the cache. 214 * 215 * @param objectId 216 * the object id 217 * 218 * @see #getObject(ObjectId) 219 */ 220 CmisObject getObject(String objectId); 221 222 /** 223 * Returns a CMIS object from the session cache. If the object is not in the 224 * cache or the given {@link OperationContext} has caching turned off, it 225 * will load the object from the repository and puts it into the cache. 226 * 227 * @param objectId 228 * the object id 229 * @param context 230 * the {@link OperationContext} to use 231 * 232 * @see #getObject(ObjectId, OperationContext) 233 */ 234 CmisObject getObject(String objectId, OperationContext context); 235 236 /** 237 * Returns a CMIS object from the session cache. If the object is not in the 238 * cache or the cache is turned off per default {@link OperationContext}, it 239 * will load the object from the repository and puts it into the cache. 240 * 241 * @param path 242 * the object path 243 */ 244 CmisObject getObjectByPath(String path); 245 246 /** 247 * Returns a CMIS object from the session cache. If the object is not in the 248 * cache or the given {@link OperationContext} has caching turned off, it 249 * will load the object from the repository and puts it into the cache. 250 * 251 * @param path 252 * the object path 253 * @param context 254 * the {@link OperationContext} to use 255 */ 256 CmisObject getObjectByPath(String path, OperationContext context); 257 258 /** 259 * Removes the given object from the cache. 260 * 261 * @param objectId 262 * object id 263 */ 264 void removeObjectFromCache(ObjectId objectId); 265 266 /** 267 * Removes the given object from the cache. 268 * 269 * @param objectId 270 * object id 271 */ 272 void removeObjectFromCache(String objectId); 273 274 // discovery 275 276 /** 277 * Sends a query to the repository. (See CMIS spec "2.1.10 Query".) 278 * 279 * @param statement 280 * the query statement (CMIS query language) 281 * @param searchAllVersions 282 * specifies if the latest and non-latest versions of document 283 * objects should be included 284 */ 285 ItemIterable<QueryResult> query(String statement, boolean searchAllVersions); 286 287 /** 288 * Sends a query to the repository using the given {@link OperationContext}. 289 * (See CMIS spec "2.1.10 Query".) 290 * 291 * @param statement 292 * the query statement (CMIS query language) 293 * @param searchAllVersions 294 * specifies if the latest and non-latest versions of document 295 * objects should be included 296 * @param context 297 * the OperationContext 298 */ 299 ItemIterable<QueryResult> query(String statement, boolean searchAllVersions, OperationContext context); 300 301 /** 302 * 303 * @param type 304 * the id of the object type 305 * @param where 306 * the WHERE part of the query 307 * @param searchAllVersions 308 * specifies if the latest and non-latest versions of document 309 * objects should be included 310 * @param context 311 * the OperationContext 312 */ 313 ItemIterable<CmisObject> queryObjects(String typeId, String where, boolean searchAllVersions, 314 OperationContext context); 315 316 /** 317 * Creates a query statement. 318 * 319 * @param statement 320 * the query statement with placeholders ('?'). 321 * 322 * @see QueryStatement 323 */ 324 QueryStatement createQueryStatement(String statement); 325 326 /** 327 * Returns the content changes. 328 * 329 * @param changeLogToken 330 * the change log token to start from or <code>null</code> 331 * @param includeProperties 332 * indicates if changed properties should be included in the 333 * result 334 * @param maxNumItems 335 * maximum numbers of events 336 */ 337 ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems); 338 339 /** 340 * Returns the content changes. 341 * 342 * @param changeLogToken 343 * the change log token to start from or <code>null</code> 344 * @param includeProperties 345 * indicates if changed properties should be included in the 346 * result 347 * @param maxNumItems 348 * maximum numbers of events 349 * @param context 350 * the OperationContext 351 */ 352 ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems, 353 OperationContext context); 354 355 // create 356 357 /** 358 * Creates a new document. 359 * 360 * @return the object id of the new document 361 * 362 * @see Folder#createDocument(Map, ContentStream, VersioningState, List, 363 * List, List, OperationContext) 364 */ 365 ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream, 366 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces); 367 368 /** 369 * Creates a new document. 370 * 371 * @return the object id of the new document 372 * 373 * @see Folder#createDocument(Map, ContentStream, VersioningState, List, 374 * List, List, OperationContext) 375 */ 376 ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream, 377 VersioningState versioningState); 378 379 /** 380 * Creates a new document from a source document. 381 * 382 * @return the object id of the new document 383 * 384 * @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState, 385 * List, List, List, OperationContext) 386 */ 387 ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId, 388 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces); 389 390 /** 391 * Creates a new document from a source document. 392 * 393 * @return the object id of the new document 394 * 395 * @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState, 396 * List, List, List, OperationContext) 397 */ 398 ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId, 399 VersioningState versioningState); 400 401 /** 402 * Creates a new folder. 403 * 404 * @return the object id of the new folder 405 * 406 * @see Folder#createFolder(Map, List, List, List, OperationContext) 407 */ 408 ObjectId createFolder(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces, 409 List<Ace> removeAces); 410 411 /** 412 * Creates a new folder. 413 * 414 * @return the object id of the new folder 415 * 416 * @see Folder#createFolder(Map, List, List, List, OperationContext) 417 */ 418 ObjectId createFolder(Map<String, ?> properties, ObjectId folderId); 419 420 /** 421 * Creates a new policy. 422 * 423 * @return the object id of the new policy 424 * 425 * @see Folder#createPolicy(Map, List, List, List, OperationContext) 426 */ 427 ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces, 428 List<Ace> removeAces); 429 430 /** 431 * Creates a new policy. 432 * 433 * @return the object id of the new policy 434 * 435 * @see Folder#createPolicy(Map, List, List, List, OperationContext) 436 */ 437 ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId); 438 439 /** 440 * Creates a new relationship. 441 * 442 * @return the object id of the new relationship 443 */ 444 ObjectId createRelationship(Map<String, ?> properties, List<Policy> policies, List<Ace> addAces, 445 List<Ace> removeAces); 446 447 /** 448 * Creates a new relationship. 449 * 450 * @return the object id of the new relationship 451 */ 452 ObjectId createRelationship(Map<String, ?> properties); 453 454 /** 455 * Fetches the relationships from or to an object from the repository. 456 */ 457 ItemIterable<Relationship> getRelationships(ObjectId objectId, boolean includeSubRelationshipTypes, 458 RelationshipDirection relationshipDirection, ObjectType type, OperationContext context); 459 460 /** 461 * Fetches the ACL of an object from the repository. 462 */ 463 Acl getAcl(ObjectId objectId, boolean onlyBasicPermissions); 464 465 /** 466 * Applies an ACL to an object. 467 */ 468 Acl applyAcl(ObjectId objectId, List<Ace> addAces, List<Ace> removeAces, AclPropagation aclPropagation); 469 470 /** 471 * Applies a set of policies to an object. 472 */ 473 void applyPolicy(ObjectId objectId, ObjectId... policyIds); 474 475 /** 476 * Removes a set of policies from an object. 477 */ 478 void removePolicy(ObjectId objectId, ObjectId... policyIds); 479 }