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.OutputStream; 22 import java.math.BigInteger; 23 import java.util.List; 24 import java.util.Map; 25 26 import org.apache.chemistry.opencmis.commons.data.Ace; 27 import org.apache.chemistry.opencmis.commons.data.ContentStream; 28 import org.apache.chemistry.opencmis.commons.enums.VersioningState; 29 import org.apache.chemistry.opencmis.commons.exceptions.CmisContentAlreadyExistsException; 30 31 /** 32 * CMIS document interface. 33 * 34 * @cmis 1.0 35 */ 36 public interface Document extends FileableCmisObject, DocumentProperties { 37 38 /** 39 * Returns the object type as a document type. 40 * 41 * @return the document type 42 * 43 * @throws ClassCastException 44 * if the object type is not a document type 45 * 46 * @cmis 1.0 47 */ 48 DocumentType getDocumentType(); 49 50 /** 51 * Returns whether the document is versionable or not. 52 * 53 * @return {@code true} if the document is versionable, {@code false} if the 54 * document is not versionable or if it's unknown 55 * 56 * @cmis 1.0 57 */ 58 boolean isVersionable(); 59 60 /** 61 * Determines whether this document is the PWC in the version series or not. 62 * 63 * The evaluation is based on the properties 64 * {@code cmis:isVersionSeriesCheckedOut}, 65 * {@code cmis:isPrivateWorkingCopy}, and 66 * {@code cmis:versionSeriesCheckedOutId} and works for all CMIS versions. 67 * 68 * @return {@code true} if it is the PWC, {@code false} if it is not the 69 * PWC, or {@code null} if it can't be determined 70 * 71 * @see DocumentProperties#isPrivateWorkingCopy() 72 * 73 * @cmis 1.0 74 */ 75 Boolean isVersionSeriesPrivateWorkingCopy(); 76 77 // object service 78 79 /** 80 * Deletes this document and all its versions. 81 * 82 * @cmis 1.0 83 */ 84 void deleteAllVersions(); 85 86 /** 87 * Retrieves the content stream of this document. 88 * 89 * @return the content stream, or {@code null} if the document has no 90 * content 91 * 92 * @cmis 1.0 93 */ 94 ContentStream getContentStream(); 95 96 /** 97 * Retrieves the content stream of this document. 98 * 99 * @param offset 100 * the offset of the stream or {@code null} to read the stream 101 * from the beginning 102 * @param length 103 * the maximum length of the stream or {@code null} to read to 104 * the end of the stream 105 * 106 * @return the content stream, or {@code null} if the document has no 107 * content 108 * 109 * @cmis 1.0 110 */ 111 ContentStream getContentStream(BigInteger offset, BigInteger length); 112 113 /** 114 * Retrieves the content stream that is associated with the given stream ID. 115 * This is usually a rendition of the document. 116 * 117 * @param streamId 118 * the stream ID 119 * 120 * @return the content stream, or {@code null} if no content is associated 121 * with this stream ID 122 * 123 * @cmis 1.0 124 */ 125 ContentStream getContentStream(String streamId); 126 127 /** 128 * Retrieves the content stream that is associated with the given stream ID. 129 * This is usually a rendition of the document. 130 * 131 * @param streamId 132 * the stream ID 133 * @param offset 134 * the offset of the stream or {@code null} to read the stream 135 * from the beginning 136 * @param length 137 * the maximum length of the stream or {@code null} to read to 138 * the end of the stream 139 * 140 * @return the content stream, or {@code null} if no content is associated 141 * with this stream ID 142 * 143 * @cmis 1.0 144 */ 145 ContentStream getContentStream(String streamId, BigInteger offset, BigInteger length); 146 147 /** 148 * Returns the content URL of the document if the binding supports content 149 * URLs. 150 * 151 * Depending on the repository and the binding, the server might not return 152 * the content but an error message. Authentication data is not attached. 153 * That is, a user may have to re-authenticate to get the content. 154 * 155 * @return the content URL of the document or {@code null} if the binding 156 * does not support content URLs 157 */ 158 public String getContentUrl(); 159 160 /** 161 * Returns the content URL of the document or a rendition if the binding 162 * supports content URLs. 163 * 164 * Depending on the repository and the binding, the server might not return 165 * the content but an error message. Authentication data is not attached. 166 * That is, a user may have to re-authenticate to get the content. 167 * 168 * @param streamId 169 * the ID of the rendition or {@code null} for the document 170 * 171 * @return the content URL of the document or rendition or {@code null} if 172 * the binding does not support content URLs 173 */ 174 public String getContentUrl(String streamId); 175 176 /** 177 * Sets a new content stream for the document and refreshes this object 178 * afterwards. If the repository created a new version, this new document is 179 * returned. Otherwise the current document is returned. 180 * <p> 181 * The stream in {@code contentStream} is consumed but not closed by this 182 * method. 183 * 184 * @param contentStream 185 * the content stream 186 * @param overwrite 187 * if this parameter is set to {@code false} and the document 188 * already has content, the repository throws a 189 * {@link CmisContentAlreadyExistsException} 190 * 191 * @return the updated document, or {@code null} if the repository did not 192 * return an object ID 193 * 194 * @see ObjectFactory#createContentStream(String, long, String, 195 * java.io.InputStream) 196 * 197 * @cmis 1.0 198 */ 199 Document setContentStream(ContentStream contentStream, boolean overwrite); 200 201 /** 202 * Sets a new content stream for the document. If the repository created a 203 * new version, the object ID of this new version is returned. Otherwise the 204 * object ID of the current document is returned. 205 * <p> 206 * The stream in {@code contentStream} is consumed but not closed by this 207 * method. 208 * 209 * @param contentStream 210 * the content stream 211 * @param overwrite 212 * if this parameter is set to {@code false} and the document 213 * already has content, the repository throws a 214 * {@link CmisContentAlreadyExistsException} 215 * @param refresh 216 * if this parameter is set to {@code true}, this object will be 217 * refreshed after the new content has been set 218 * 219 * @return the updated object ID, or {@code null} if the repository did not 220 * return an object ID 221 * 222 * @see ObjectFactory#createContentStream(String, long, String, 223 * java.io.InputStream) 224 * 225 * @cmis 1.0 226 */ 227 ObjectId setContentStream(ContentStream contentStream, boolean overwrite, boolean refresh); 228 229 /** 230 * Appends a content stream to the content stream of the document and 231 * refreshes this object afterwards. If the repository created a new 232 * version, this new document is returned. Otherwise the current document is 233 * returned. 234 * <p> 235 * The stream in {@code contentStream} is consumed but not closed by this 236 * method. 237 * 238 * @param contentStream 239 * the content stream 240 * @param isLastChunk 241 * indicates if this stream is the last chunk of the content 242 * 243 * @return the updated document, or {@code null} if the repository did not 244 * return an object ID 245 * 246 * @see ObjectFactory#createContentStream(String, long, String, 247 * java.io.InputStream) 248 * 249 * @cmis 1.1 250 */ 251 Document appendContentStream(ContentStream contentStream, boolean isLastChunk); 252 253 /** 254 * Appends a content stream to the content stream of the document. If the 255 * repository created a new version, the object ID of this new version is 256 * returned. Otherwise the object ID of the current document is returned. 257 * <p> 258 * The stream in {@code contentStream} is consumed but not closed by this 259 * method. 260 * 261 * @param contentStream 262 * the content stream 263 * @param isLastChunk 264 * indicates if this stream is the last chunk of the content 265 * @param refresh 266 * if this parameter is set to {@code true}, this object will be 267 * refreshed after the content stream has been appended 268 * 269 * @return the updated object ID, or {@code null} if the repository did not 270 * return an object ID 271 * 272 * @cmis 1.1 273 */ 274 ObjectId appendContentStream(ContentStream contentStream, boolean isLastChunk, boolean refresh); 275 276 /** 277 * Removes the current content stream from the document and refreshes this 278 * object afterwards. If the repository created a new version, this new 279 * document is returned. Otherwise the current document is returned. 280 * 281 * @return the updated document, or {@code null} if the repository did not 282 * return an object ID 283 * 284 * @cmis 1.0 285 */ 286 Document deleteContentStream(); 287 288 /** 289 * Removes the current content stream from the document. If the repository 290 * created a new version, the object ID of this new version is returned. 291 * Otherwise the object ID of the current document is returned. 292 * 293 * @param refresh 294 * if this parameter is set to {@code true}, this object will be 295 * refreshed after the content stream has been deleted 296 * 297 * @return the updated document, or {@code null} if the repository did not 298 * return an object ID 299 * 300 * @cmis 1.0 301 */ 302 ObjectId deleteContentStream(boolean refresh); 303 304 /** 305 * Creates an {@link OutputStream} stream object that can be used to 306 * overwrite the current content of the document. 307 * 308 * @param filename 309 * the file name 310 * @param mimeType 311 * the MIME type 312 * @return the OutputStream object 313 * 314 * @cmis 1.1 315 */ 316 OutputStream createOverwriteOutputStream(String filename, String mimeType); 317 318 /** 319 * Creates an {@link OutputStream} stream object that can be used to 320 * overwrite the current content of the document. 321 * 322 * @param filename 323 * the file name 324 * @param mimeType 325 * the MIME type 326 * @param bufferSize 327 * buffer size in bytes 328 * @return the OutputStream object 329 * 330 * @cmis 1.1 331 */ 332 OutputStream createOverwriteOutputStream(String filename, String mimeType, int bufferSize); 333 334 /** 335 * Creates an {@link OutputStream} stream object that can be used to append 336 * content the current content of the document. 337 * 338 * @return the OutputStream object 339 * 340 * @cmis 1.1 341 */ 342 OutputStream createAppendOutputStream(); 343 344 /** 345 * Creates an {@link OutputStream} stream object that can be used to append 346 * content the current content of the document. 347 * 348 * @param bufferSize 349 * buffer size in bytes 350 * @return the OutputStream object 351 * 352 * @cmis 1.1 353 */ 354 OutputStream createAppendOutputStream(int bufferSize); 355 356 // versioning service 357 358 /** 359 * Checks out the document and returns the object ID of the PWC (private 360 * working copy). 361 * 362 * @return PWC object ID 363 * 364 * @cmis 1.0 365 */ 366 ObjectId checkOut(); 367 368 /** 369 * If this is a PWC (private working copy) the check out will be reversed. 370 * If this is not a PWC it an exception will be thrown. 371 * 372 * @cmis 1.0 373 */ 374 void cancelCheckOut(); 375 376 /** 377 * If this is a PWC (private working copy) it performs a check in. If this 378 * is not a PWC it an exception will be thrown. 379 * 380 * The stream in {@code contentStream} is consumed but not closed by this 381 * method. 382 * 383 * @return new document ID 384 * 385 * @cmis 1.0 386 */ 387 ObjectId checkIn(boolean major, Map<String, ?> properties, ContentStream contentStream, String checkinComment, 388 List<Policy> policies, List<Ace> addAces, List<Ace> removeAces); 389 390 /** 391 * If this is a PWC (private working copy) it performs a check in. If this 392 * is not a PWC it an exception will be thrown. 393 * 394 * The stream in {@code contentStream} is consumed but not closed by this 395 * method. 396 * 397 * @return new document ID 398 * 399 * @cmis 1.0 400 */ 401 ObjectId checkIn(boolean major, Map<String, ?> properties, ContentStream contentStream, String checkinComment); 402 403 /** 404 * Fetches the latest major or minor version of this document. 405 * 406 * @param major 407 * if {@code true} the latest major version will be returned, 408 * otherwise the very last version will be returned 409 * 410 * @return the latest document object 411 * 412 * @cmis 1.0 413 */ 414 Document getObjectOfLatestVersion(boolean major); 415 416 /** 417 * Fetches the latest major or minor version of this document using the 418 * given {@link OperationContext}. 419 * 420 * @param major 421 * if {@code true} the latest major version will be returned, 422 * otherwise the very last version will be returned 423 * 424 * @return the latest document object 425 * 426 * @cmis 1.0 427 */ 428 Document getObjectOfLatestVersion(boolean major, OperationContext context); 429 430 /** 431 * Fetches all versions of this document. 432 * <p> 433 * The behavior of this method is undefined if the document is not 434 * versionable and can be different for each repository. 435 * 436 * @return all versions of the version series, sorted by 437 * {@code cmis:creationDate} descending and preceded by the PWC, if 438 * one exists, not {@code null} 439 * 440 * @cmis 1.0 441 */ 442 List<Document> getAllVersions(); 443 444 /** 445 * Fetches all versions of this document using the given 446 * {@link OperationContext}. 447 * <p> 448 * The behavior of this method is undefined if the document is not 449 * versionable and can be different for each repository. 450 * 451 * @return all versions of the version series, sorted by 452 * {@code cmis:creationDate} descending and preceded by the PWC, if 453 * one exists, not {@code null} 454 * 455 * @cmis 1.0 456 */ 457 List<Document> getAllVersions(OperationContext context); 458 459 /** 460 * Creates a copy of this document, including content. 461 * 462 * @param targetFolderId 463 * the ID of the target folder, {@code null} to create an unfiled 464 * document 465 * 466 * @return the new document object 467 * 468 * @cmis 1.0 469 */ 470 Document copy(ObjectId targetFolderId); 471 472 /** 473 * Creates a copy of this document, including content. 474 * 475 * @param targetFolderId 476 * the ID of the target folder, {@code null} to create an unfiled 477 * document 478 * 479 * @return the new document object or {@code null} if the parameter 480 * {@code context} was set to {@code null} 481 * 482 * @cmis 1.0 483 */ 484 Document copy(ObjectId targetFolderId, Map<String, ?> properties, VersioningState versioningState, 485 List<Policy> policies, List<Ace> addACEs, List<Ace> removeACEs, OperationContext context); 486 487 }