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.commons.spi; 20 21 import java.math.BigInteger; 22 import java.util.List; 23 24 import org.apache.chemistry.opencmis.commons.data.Acl; 25 import org.apache.chemistry.opencmis.commons.data.AllowableActions; 26 import org.apache.chemistry.opencmis.commons.data.BulkUpdateObjectIdAndChangeToken; 27 import org.apache.chemistry.opencmis.commons.data.ContentStream; 28 import org.apache.chemistry.opencmis.commons.data.ExtensionsData; 29 import org.apache.chemistry.opencmis.commons.data.FailedToDeleteData; 30 import org.apache.chemistry.opencmis.commons.data.ObjectData; 31 import org.apache.chemistry.opencmis.commons.data.Properties; 32 import org.apache.chemistry.opencmis.commons.data.RenditionData; 33 import org.apache.chemistry.opencmis.commons.enums.IncludeRelationships; 34 import org.apache.chemistry.opencmis.commons.enums.UnfileObject; 35 import org.apache.chemistry.opencmis.commons.enums.VersioningState; 36 37 /** 38 * Object Service interface. 39 * 40 * <p> 41 * <em> 42 * See the CMIS 1.0 and CMIS 1.1 specifications for details on the operations, parameters, 43 * exceptions and the domain model. 44 * </em> 45 * </p> 46 */ 47 public interface ObjectService { 48 49 /** 50 * Creates a document object of the specified type (given by the 51 * cmis:objectTypeId property) in the (optionally) specified location. 52 * 53 * The stream in <code>contentStream</code> is consumed but not closed by 54 * this method. 55 * 56 * @param repositoryId 57 * the identifier for the repository 58 * @param properties 59 * the property values that must be applied to the newly created 60 * document object 61 * @param folderId 62 * <em>(optional)</em> if specified, the identifier for the 63 * folder that must be the parent folder for the newly created 64 * document object 65 * @param contentStream 66 * <em>(optional)</em> the content stream that must be stored for 67 * the newly created document object 68 * @param versioningState 69 * <em>(optional)</em> specifies what the versioning state of the 70 * newly created object must be (default is 71 * {@link VersioningState#MAJOR}) 72 * @param policies 73 * <em>(optional)</em> a list of policy IDs that must be applied 74 * to the newly created document object 75 * @param addAces 76 * <em>(optional)</em> a list of ACEs that must be added to the 77 * newly created document object, either using the ACL from 78 * {@code folderId} if specified, or being applied if no 79 * {@code folderId} is specified 80 * @param removeAces 81 * <em>(optional)</em> a list of ACEs that must be removed from 82 * the newly created document object, either using the ACL from 83 * {@code folderId} if specified, or being ignored if no 84 * {@code folderId} is specified 85 * @param extension 86 * extension data 87 * @return the ID of the newly created document 88 */ 89 String createDocument(String repositoryId, Properties properties, String folderId, ContentStream contentStream, 90 VersioningState versioningState, List<String> policies, Acl addAces, Acl removeAces, 91 ExtensionsData extension); 92 93 /** 94 * Creates a document object as a copy of the given source document in the 95 * (optionally) specified location. 96 * 97 * @param repositoryId 98 * the identifier for the repository 99 * @param sourceId 100 * the identifier for the source document 101 * @param properties 102 * the property values that must be applied to the newly created 103 * document object 104 * @param folderId 105 * <em>(optional)</em> if specified, the identifier for the 106 * folder that must be the parent folder for the newly created 107 * document object 108 * @param versioningState 109 * <em>(optional)</em> specifies what the versioning state of the 110 * newly created object must be (default is 111 * {@link VersioningState#MAJOR}) 112 * @param policies 113 * <em>(optional)</em> a list of policy IDs that must be applied 114 * to the newly created document object 115 * @param addAces 116 * <em>(optional)</em> a list of ACEs that must be added to the 117 * newly created document object, either using the ACL from 118 * {@code folderId} if specified, or being applied if no 119 * {@code folderId} is specified 120 * @param removeAces 121 * <em>(optional)</em> a list of ACEs that must be removed from 122 * the newly created document object, either using the ACL from 123 * {@code folderId} if specified, or being ignored if no 124 * {@code folderId} is specified 125 * @param extension 126 * extension data 127 * @return the ID of the newly created document 128 */ 129 String createDocumentFromSource(String repositoryId, String sourceId, Properties properties, String folderId, 130 VersioningState versioningState, List<String> policies, Acl addAces, Acl removeAces, 131 ExtensionsData extension); 132 133 /** 134 * Creates a folder object of the specified type (given by the 135 * cmis:objectTypeId property) in the specified location. 136 * 137 * @param repositoryId 138 * the identifier for the repository 139 * @param properties 140 * the property values that must be applied to the newly created 141 * folder object 142 * @param folderId 143 * the identifier for the parent folder 144 * @param policies 145 * <em>(optional)</em> a list of policy IDs that must be applied 146 * to the newly created folder object 147 * @param addAces 148 * <em>(optional)</em> a list of ACEs that must be added to the 149 * newly created folder object, either using the ACL from 150 * {@code folderId} if specified, or being applied if no 151 * {@code folderId} is specified 152 * @param removeAces 153 * <em>(optional)</em> a list of ACEs that must be removed from 154 * the newly created folder object, either using the ACL from 155 * {@code folderId} if specified, or being ignored if no 156 * {@code folderId} is specified 157 * @param extension 158 * extension data 159 * @return the ID of the newly created folder 160 */ 161 String createFolder(String repositoryId, Properties properties, String folderId, List<String> policies, 162 Acl addAces, Acl removeAces, ExtensionsData extension); 163 164 /** 165 * Creates a relationship object of the specified type (given by the 166 * cmis:objectTypeId property). 167 * 168 * @param repositoryId 169 * the identifier for the repository 170 * @param properties 171 * the property values that must be applied to the newly created 172 * relationship object 173 * @param policies 174 * <em>(optional)</em> a list of policy IDs that must be applied 175 * to the newly created relationship object 176 * @param addAces 177 * <em>(optional)</em> a list of ACEs that must be added to the 178 * newly created relationship object, either using the ACL from 179 * {@code folderId} if specified, or being applied if no 180 * {@code folderId} is specified 181 * @param removeAces 182 * <em>(optional)</em> a list of ACEs that must be removed from 183 * the newly created relationship object, either using the ACL 184 * from {@code folderId} if specified, or being ignored if no 185 * {@code folderId} is specified 186 * @param extension 187 * extension data 188 * @return the ID of the newly created relationship 189 */ 190 String createRelationship(String repositoryId, Properties properties, List<String> policies, Acl addAces, 191 Acl removeAces, ExtensionsData extension); 192 193 /** 194 * Creates a policy object of the specified type (given by the 195 * cmis:objectTypeId property). 196 * 197 * @param repositoryId 198 * the identifier for the repository 199 * @param properties 200 * the property values that must be applied to the newly created 201 * policy object 202 * @param folderId 203 * <em>(optional)</em> if specified, the identifier for the 204 * folder that must be the parent folder for the newly created 205 * policy object 206 * @param policies 207 * <em>(optional)</em> a list of policy IDs that must be applied 208 * to the newly created policy object 209 * @param addAces 210 * <em>(optional)</em> a list of ACEs that must be added to the 211 * newly created policy object, either using the ACL from 212 * {@code folderId} if specified, or being applied if no 213 * {@code folderId} is specified 214 * @param removeAces 215 * <em>(optional)</em> a list of ACEs that must be removed from 216 * the newly created policy object, either using the ACL from 217 * {@code folderId} if specified, or being ignored if no 218 * {@code folderId} is specified 219 * @param extension 220 * extension data 221 * @return the ID of the newly created policy 222 */ 223 String createPolicy(String repositoryId, Properties properties, String folderId, List<String> policies, 224 Acl addAces, Acl removeAces, ExtensionsData extension); 225 226 /** 227 * Creates an item object of the specified type (given by the 228 * cmis:objectTypeId property). 229 * 230 * @param repositoryId 231 * the identifier for the repository 232 * @param properties 233 * the property values that must be applied to the newly created 234 * policy object 235 * @param folderId 236 * <em>(optional)</em> if specified, the identifier for the 237 * folder that must be the parent folder for the newly created 238 * policy object 239 * @param policies 240 * <em>(optional)</em> a list of policy IDs that must be applied 241 * to the newly created policy object 242 * @param addAces 243 * <em>(optional)</em> a list of ACEs that must be added to the 244 * newly created policy object, either using the ACL from 245 * {@code folderId} if specified, or being applied if no 246 * {@code folderId} is specified 247 * @param removeAces 248 * <em>(optional)</em> a list of ACEs that must be removed from 249 * the newly created policy object, either using the ACL from 250 * {@code folderId} if specified, or being ignored if no 251 * {@code folderId} is specified 252 * @param extension 253 * extension data 254 * @return the ID of the newly created item 255 */ 256 String createItem(String repositoryId, Properties properties, String folderId, List<String> policies, Acl addAces, 257 Acl removeAces, ExtensionsData extension); 258 259 /** 260 * Gets the list of allowable actions for an object. 261 * 262 * @param repositoryId 263 * the identifier for the repository 264 * @param objectId 265 * the identifier for the object 266 * @param extension 267 * extension data 268 * @return the allowable actions 269 */ 270 AllowableActions getAllowableActions(String repositoryId, String objectId, ExtensionsData extension); 271 272 /** 273 * Gets the specified information for the object specified by id. 274 * 275 * @param repositoryId 276 * the identifier for the repository 277 * @param objectId 278 * the identifier for the object 279 * @param filter 280 * <em>(optional)</em> a comma-separated list of query names that 281 * defines which properties must be returned by the repository 282 * (default is repository specific) 283 * @param includeAllowableActions 284 * <em>(optional)</em> if {@code true}, then the repository must 285 * return the allowable actions for the object (default is 286 * {@code false}) 287 * @param includeRelationships 288 * <em>(optional)</em> indicates what relationships in which the 289 * object participates must be returned (default is 290 * {@link IncludeRelationships#NONE}) 291 * @param renditionFilter 292 * <em>(optional)</em> indicates what set of renditions the 293 * repository must return whose kind matches this filter (default 294 * is <code>"cmis:none"</code>) 295 * @param includePolicyIds 296 * <em>(optional)</em> if {@code true}, then the repository must 297 * return the policy ids for the object (default is {@code false} 298 * ) 299 * @param includeAcl 300 * <em>(optional)</em> if {@code true}, then the repository must 301 * return the ACL for the object (default is {@code false}) 302 * @param extension 303 * extension data 304 * @return the object 305 */ 306 ObjectData getObject(String repositoryId, String objectId, String filter, Boolean includeAllowableActions, 307 IncludeRelationships includeRelationships, String renditionFilter, Boolean includePolicyIds, 308 Boolean includeAcl, ExtensionsData extension); 309 310 /** 311 * Gets the list of properties for an object. 312 * 313 * @param repositoryId 314 * the identifier for the repository 315 * @param objectId 316 * the identifier for the object 317 * @param filter 318 * <em>(optional)</em> a comma-separated list of query names that 319 * defines which properties must be returned by the repository 320 * (default is repository specific) 321 * @param extension 322 * extension data 323 * @return the object properties 324 */ 325 Properties getProperties(String repositoryId, String objectId, String filter, ExtensionsData extension); 326 327 /** 328 * Gets the list of associated renditions for the specified object. Only 329 * rendition attributes are returned, not rendition stream. 330 * 331 * @param repositoryId 332 * the identifier for the repository 333 * @param objectId 334 * the identifier for the object 335 * @param renditionFilter 336 * <em>(optional)</em> indicates what set of renditions the 337 * repository must return whose kind matches this filter (default 338 * is <code>"cmis:none"</code>) 339 * @param maxItems 340 * <em>(optional)</em> the maximum number of items to return in a 341 * response (default is repository specific) 342 * @param skipCount 343 * <em>(optional)</em> number of potential results that the 344 * repository must skip/page over before returning any results 345 * (default is 0) 346 * @param extension 347 * extension data 348 * @return the list of renditions 349 */ 350 List<RenditionData> getRenditions(String repositoryId, String objectId, String renditionFilter, 351 BigInteger maxItems, BigInteger skipCount, ExtensionsData extension); 352 353 /** 354 * Gets the specified information for the object specified by path. 355 * 356 * @param repositoryId 357 * the identifier for the repository 358 * @param path 359 * the path to the object 360 * @param filter 361 * <em>(optional)</em> a comma-separated list of query names that 362 * defines which properties must be returned by the repository 363 * (default is repository specific) 364 * @param includeAllowableActions 365 * <em>(optional)</em> if {@code true}, then the repository must 366 * return the allowable actions for the object (default is 367 * {@code false}) 368 * @param includeRelationships 369 * <em>(optional)</em> indicates what relationships in which the 370 * object participates must be returned (default is 371 * {@link IncludeRelationships#NONE}) 372 * @param renditionFilter 373 * <em>(optional)</em> indicates what set of renditions the 374 * repository must return whose kind matches this filter (default 375 * is <code>"cmis:none"</code>) 376 * @param includePolicyIds 377 * <em>(optional)</em> if {@code true}, then the repository must 378 * return the policy ids for the object (default is {@code false} 379 * ) 380 * @param includeAcl 381 * <em>(optional)</em> if {@code true}, then the repository must 382 * return the ACL for the object (default is {@code false}) 383 * @param extension 384 * extension data 385 * @return the object 386 */ 387 ObjectData getObjectByPath(String repositoryId, String path, String filter, Boolean includeAllowableActions, 388 IncludeRelationships includeRelationships, String renditionFilter, Boolean includePolicyIds, 389 Boolean includeAcl, ExtensionsData extension); 390 391 /** 392 * Gets the content stream for the specified document object, or gets a 393 * rendition stream for a specified rendition of a document or folder 394 * object. 395 * 396 * @param repositoryId 397 * the identifier for the repository 398 * @param objectId 399 * the identifier for the object 400 * @param extension 401 * extension data 402 * @return the content stream 403 */ 404 ContentStream getContentStream(String repositoryId, String objectId, String streamId, BigInteger offset, 405 BigInteger length, ExtensionsData extension); 406 407 /** 408 * Updates properties of the specified object. 409 * 410 * @param repositoryId 411 * the identifier for the repository 412 * @param objectId 413 * the identifier for the object. The repository might return a 414 * different/new object id 415 * @param changeToken 416 * <em>(optional)</em> the last change token of this object that 417 * the client received. The repository might return a new change 418 * token (default is {@code null}) 419 * @param properties 420 * the updated property values that must be applied to the object 421 * @param extension 422 * extension data 423 */ 424 void updateProperties(String repositoryId, Holder<String> objectId, Holder<String> changeToken, 425 Properties properties, ExtensionsData extension); 426 427 /** 428 * Updates properties and secondary types of one or more objects. 429 * 430 * @param repositoryId 431 * the identifier for the repository 432 * @param objectIdsAndChangeTokens 433 * the ids and change tokens of the objects to update 434 * @param properties 435 * the properties to set 436 * @param addSecondaryTypeIds 437 * the secondary types to apply 438 * @param removeSecondaryTypeIds 439 * the secondary types to remove 440 * @param extension 441 * extension data 442 * @return the list of updated objects with their change tokens 443 */ 444 List<BulkUpdateObjectIdAndChangeToken> bulkUpdateProperties(String repositoryId, 445 List<BulkUpdateObjectIdAndChangeToken> objectIdsAndChangeTokens, Properties properties, 446 List<String> addSecondaryTypeIds, List<String> removeSecondaryTypeIds, ExtensionsData extension); 447 448 /** 449 * Moves the specified file-able object from one folder to another. 450 * 451 * @param repositoryId 452 * the identifier for the repository 453 * @param objectId 454 * the identifier for the object. The repository might return a 455 * different/new object id 456 * @param targetFolderId 457 * the identifier for the target folder 458 * @param sourceFolderId 459 * the identifier for the source folder 460 * @param extension 461 * extension data 462 */ 463 void moveObject(String repositoryId, Holder<String> objectId, String targetFolderId, String sourceFolderId, 464 ExtensionsData extension); 465 466 /** 467 * Deletes the specified object. 468 * 469 * @param repositoryId 470 * the identifier for the repository 471 * @param objectId 472 * the identifier for the object 473 * @param allVersions 474 * <em>(optional)</em> If {@code true} then delete all versions 475 * of the document, otherwise delete only the document object 476 * specified (default is {@code true}) 477 * @param extension 478 * extension data 479 */ 480 void deleteObject(String repositoryId, String objectId, Boolean allVersions, ExtensionsData extension); 481 482 /** 483 * Deletes the specified folder object and all of its child- and 484 * descendant-objects. 485 * 486 * @param repositoryId 487 * the identifier for the repository 488 * @param folderId 489 * the identifier for the folder 490 * @param allVersions 491 * <em>(optional)</em> If {@code true} then delete all versions 492 * of the document, otherwise delete only the document object 493 * specified (default is {@code true}) 494 * @param unfileObjects 495 * <em>(optional)</em> defines how the repository must process 496 * file-able child- or descendant-objects (default is 497 * {@link UnfileObject#DELETE}) 498 * @param continueOnFailure 499 * <em>(optional)</em> If {@code true}, then the repository 500 * should continue attempting to perform this operation even if 501 * deletion of a child- or descendant-object in the specified 502 * folder cannot be deleted (default is {@code false}) 503 * @param extension 504 * extension data 505 * @return a (possibly incomplete) collection of object IDs of objects that 506 * couldn't be deleted 507 */ 508 FailedToDeleteData deleteTree(String repositoryId, String folderId, Boolean allVersions, 509 UnfileObject unfileObjects, Boolean continueOnFailure, ExtensionsData extension); 510 511 /** 512 * Sets the content stream for the specified document object. 513 * 514 * The stream in <code>contentStream</code> is consumed but not closed by 515 * this method. 516 * 517 * @param repositoryId 518 * the identifier for the repository 519 * @param objectId 520 * the identifier for the object. The repository might return a 521 * different/new object id 522 * @param overwriteFlag 523 * <em>(optional)</em> If {@code true}, then the repository must 524 * replace the existing content stream for the object (if any) 525 * with the input content stream. If If {@code false}, then the 526 * repository must only set the input content stream for the 527 * object if the object currently does not have a content stream 528 * (default is {@code true}) 529 * @param changeToken 530 * <em>(optional)</em> the last change token of this object that 531 * the client received. The repository might return a new change 532 * token (default is {@code null}) 533 * @param contentStream 534 * the content stream 535 * @param extension 536 * extension data 537 */ 538 void setContentStream(String repositoryId, Holder<String> objectId, Boolean overwriteFlag, 539 Holder<String> changeToken, ContentStream contentStream, ExtensionsData extension); 540 541 /** 542 * Deletes the content stream for the specified document object. 543 * 544 * @param repositoryId 545 * the identifier for the repository 546 * @param objectId 547 * the identifier for the object. The repository might return a 548 * different/new object id 549 * @param changeToken 550 * <em>(optional)</em> the last change token of this object that 551 * the client received. The repository might return a new change 552 * token (default is {@code null}) 553 * @param extension 554 * extension data 555 */ 556 void deleteContentStream(String repositoryId, Holder<String> objectId, Holder<String> changeToken, 557 ExtensionsData extension); 558 559 /** 560 * Appends the content stream to the content of the document. 561 * 562 * @param repositoryId 563 * the identifier for the repository 564 * @param objectId 565 * the identifier for the object. The repository might return a 566 * different/new object id 567 * @param changeToken 568 * <em>(optional)</em> the last change token of this object that 569 * the client received. The repository might return a new change 570 * token (default is {@code null}) 571 * @param contentStream 572 * the content stream to append 573 * @param isLastChunk 574 * indicates if this content stream is the last chunk 575 * @param extension 576 * extension data 577 */ 578 void appendContentStream(String repositoryId, Holder<String> objectId, Holder<String> changeToken, 579 ContentStream contentStream, boolean isLastChunk, ExtensionsData extension); 580 }