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 }