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 import java.util.concurrent.Future;
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.definitions.TypeDefinition;
31 import org.apache.chemistry.opencmis.commons.enums.AclPropagation;
32 import org.apache.chemistry.opencmis.commons.enums.UnfileObject;
33 import org.apache.chemistry.opencmis.commons.enums.VersioningState;
34 import org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
35
36 /**
37 * This interface provides asynchronous CMIS operations.
38 */
39 public interface AsyncSession {
40
41 /**
42 * Returns the session object.
43 *
44 * @return the session object, not {@code null}
45 */
46 Session getSession();
47
48 // --- types ---
49
50 /**
51 * Gets the definition of a type.
52 *
53 * @param typeId
54 * the ID of the type
55 *
56 * @return the type definition
57 *
58 * @throws CmisObjectNotFoundException
59 * if a type with the given type ID doesn't exist
60 *
61 * @cmis 1.0
62 */
63 Future<ObjectType> getTypeDefinition(String typeId);
64
65 /**
66 * Creates a new type.
67 *
68 * @param type
69 * the type definition
70 *
71 * @return the new type definition
72 *
73 * @cmis 1.1
74 */
75 Future<ObjectType> createType(TypeDefinition type);
76
77 /**
78 * Updates an existing type.
79 *
80 * @param type
81 * the type definition updates
82 *
83 * @return the updated type definition
84 *
85 * @cmis 1.1
86 */
87 Future<ObjectType> updateType(TypeDefinition type);
88
89 /**
90 * Deletes a type.
91 *
92 * @param typeId
93 * the ID of the type to delete
94 *
95 * @cmis 1.1
96 */
97 Future<?> deleteType(String typeId);
98
99 // --- objects ---
100
101 /**
102 * Returns a CMIS object from the session cache. If the object is not in the
103 * cache or the cache is turned off per default {@link OperationContext}, it
104 * will load the object from the repository and puts it into the cache.
105 * <p>
106 * This method might return a stale object if the object has been found in
107 * the cache and has been changed in or removed from the repository. Use
108 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
109 * update the object if necessary.
110 *
111 * @param objectId
112 * the object ID
113 *
114 * @return the requested object
115 *
116 * @cmis 1.0
117 */
118 Future<CmisObject> getObject(ObjectId objectId);
119
120 /**
121 * Returns a CMIS object from the session cache. If the object is not in the
122 * cache or the given {@link OperationContext} has caching turned off, it
123 * will load the object from the repository and puts it into the cache.
124 * <p>
125 * This method might return a stale object if the object has been found in
126 * the cache and has been changed in or removed from the repository. Use
127 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
128 * update the object if necessary.
129 *
130 * @param objectId
131 * the object ID
132 * @param context
133 * the {@link OperationContext} to use
134 *
135 * @return the requested object
136 *
137 * @cmis 1.0
138 */
139 Future<CmisObject> getObject(ObjectId objectId, OperationContext context);
140
141 /**
142 * Returns a CMIS object from the session cache. If the object is not in the
143 * cache or the cache is turned off per default {@link OperationContext}, it
144 * will load the object from the repository and puts it into the cache.
145 * <p>
146 * This method might return a stale object if the object has been found in
147 * the cache and has been changed in or removed from the repository. Use
148 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
149 * update the object if necessary.
150 *
151 * @param objectId
152 * the object ID
153 *
154 * @return the requested object
155 *
156 * @cmis 1.0
157 */
158 Future<CmisObject> getObject(String objectId);
159
160 /**
161 * Returns a CMIS object from the session cache. If the object is not in the
162 * cache or the given {@link OperationContext} has caching turned off, it
163 * will load the object from the repository and puts it into the cache.
164 * <p>
165 * This method might return a stale object if the object has been found in
166 * the cache and has been changed in or removed from the repository. Use
167 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
168 * update the object if necessary.
169 *
170 * @param objectId
171 * the object ID
172 * @param context
173 * the {@link OperationContext} to use
174 *
175 * @return the requested object
176 *
177 * @cmis 1.0
178 */
179 Future<CmisObject> getObject(String objectId, OperationContext context);
180
181 /**
182 * Returns a CMIS object from the session cache. If the object is not in the
183 * cache or the cache is turned off per default {@link OperationContext}, it
184 * will load the object from the repository and puts it into the cache.
185 * <p>
186 * This method might return a stale object if the object has been found in
187 * the cache and has been changed in or removed from the repository. Use
188 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
189 * update the object if necessary.
190 *
191 * @param path
192 * the object path
193 *
194 * @cmis 1.0
195 */
196 Future<CmisObject> getObjectByPath(String path);
197
198 /**
199 * Returns a CMIS object from the session cache. If the object is not in the
200 * cache or the given {@link OperationContext} has caching turned off, it
201 * will load the object from the repository and puts it into the cache.
202 * <p>
203 * This method might return a stale object if the object has been found in
204 * the cache and has been changed in or removed from the repository. Use
205 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
206 * update the object if necessary.
207 *
208 * @param path
209 * the object path
210 * @param context
211 * the {@link OperationContext} to use
212 *
213 * @return the requested object
214 *
215 * @cmis 1.0
216 */
217 Future<CmisObject> getObjectByPath(String path, OperationContext context);
218
219 /**
220 * Returns a CMIS object from the session cache. If the object is not in the
221 * cache or the cache is turned off per default {@link OperationContext}, it
222 * will load the object from the repository and puts it into the cache.
223 * <p>
224 * This method might return a stale object if the object has been found in
225 * the cache and has been changed in or removed from the repository. Use
226 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
227 * update the object if necessary.
228 *
229 * @param parentPath
230 * the path of the parent folder
231 * @param name
232 * the (path segment) name of the object in the folder
233 *
234 * @return the requested object
235 *
236 * @cmis 1.0
237 */
238 Future<CmisObject> getObjectByPath(String parentPath, String name);
239
240 /**
241 * Returns a CMIS object from the session cache. If the object is not in the
242 * cache or the given {@link OperationContext} has caching turned off, it
243 * will load the object from the repository and puts it into the cache.
244 * <p>
245 * This method might return a stale object if the object has been found in
246 * the cache and has been changed in or removed from the repository. Use
247 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
248 * update the object if necessary.
249 *
250 * @param parentPath
251 * the path of the parent folder
252 * @param name
253 * the (path segment) name of the object in the folder
254 * @param context
255 * the {@link OperationContext} to use
256 *
257 * @return the requested object
258 *
259 * @cmis 1.0
260 */
261 Future<CmisObject> getObjectByPath(String parentPath, String name, OperationContext context);
262
263 /**
264 * Returns the latest version in a version series.
265 *
266 * @param objectId
267 * the document ID of an arbitrary version in the version series
268 *
269 * @return the latest document version
270 *
271 * @cmis 1.0
272 */
273 Future<Document> getLatestDocumentVersion(ObjectId objectId);
274
275 /**
276 * Returns the latest version in a version series.
277 *
278 * @param objectId
279 * the document ID of an arbitrary version in the version series
280 * @param context
281 * the {@link OperationContext} to use
282 *
283 * @return the latest document version
284 *
285 * @cmis 1.0
286 */
287 Future<Document> getLatestDocumentVersion(ObjectId objectId, OperationContext context);
288
289 /**
290 * Returns the latest version in a version series.
291 *
292 * @param objectId
293 * the document ID of an arbitrary version in the version series
294 * @param major
295 * if {@code true} the latest major version will be returned,
296 * otherwise the very last version will be returned
297 * @param context
298 * the {@link OperationContext} to use
299 *
300 * @return the latest document version
301 *
302 * @cmis 1.0
303 */
304 Future<Document> getLatestDocumentVersion(ObjectId objectId, boolean major, OperationContext context);
305
306 /**
307 * /** Returns the latest version in a version series.
308 *
309 * @param objectId
310 * the document ID of an arbitrary version in the version series
311 *
312 * @return the latest document version
313 *
314 * @cmis 1.0
315 */
316 Future<Document> getLatestDocumentVersion(String objectId);
317
318 /**
319 * Returns the latest version in a version series.
320 *
321 * @param objectId
322 * the document ID of an arbitrary version in the version series
323 * @param context
324 * the {@link OperationContext} to use
325 *
326 * @return the latest document version
327 *
328 * @cmis 1.0
329 */
330 Future<Document> getLatestDocumentVersion(String objectId, OperationContext context);
331
332 /**
333 * Returns the latest version in a version series.
334 *
335 * @param objectId
336 * the document ID of an arbitrary version in the version series
337 * @param major
338 * if {@code true} the latest major version will be returned,
339 * otherwise the very last version will be returned
340 * @param context
341 * the {@link OperationContext} to use
342 *
343 * @return the latest document version
344 *
345 * @cmis 1.0
346 */
347 Future<Document> getLatestDocumentVersion(String objectId, boolean major, OperationContext context);
348
349 // --- create ---
350
351 /**
352 * Creates a new document.
353 *
354 * The stream in {@code contentStream} is consumed but not closed by this
355 * method.
356 *
357 * @return the object ID of the new document
358 *
359 * @cmis 1.0
360 */
361 Future<ObjectId> createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
362 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
363
364 /**
365 * Creates a new document.
366 *
367 * The stream in {@code contentStream} is consumed but not closed by this
368 * method.
369 *
370 * @return the object ID of the new document
371 *
372 * @cmis 1.0
373 */
374 Future<ObjectId> createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
375 VersioningState versioningState);
376
377 /**
378 * Creates a new document from a source document.
379 *
380 * @return the object ID of the new document
381 *
382 * @cmis 1.0
383 */
384 Future<ObjectId> createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
385 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
386
387 /**
388 * Creates a new document from a source document.
389 *
390 * @return the object ID of the new document
391 *
392 * @cmis 1.0
393 */
394 Future<ObjectId> createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
395 VersioningState versioningState);
396
397 /**
398 * Creates a new folder.
399 *
400 * @return the object ID of the new folder
401 *
402 * @cmis 1.0
403 */
404 Future<ObjectId> createFolder(Map<String, ?> properties, ObjectId folderId, List<Policy> policies,
405 List<Ace> addAces, List<Ace> removeAces);
406
407 /**
408 * Creates a new folder.
409 *
410 * @return the object ID of the new folder
411 *
412 * @cmis 1.0
413 */
414 Future<ObjectId> createFolder(Map<String, ?> properties, ObjectId folderId);
415
416 /**
417 * Creates a new policy.
418 *
419 * @return the object ID of the new policy
420 *
421 * @cmis 1.0
422 */
423 Future<ObjectId> createPolicy(Map<String, ?> properties, ObjectId folderId, List<Policy> policies,
424 List<Ace> addAces, List<Ace> removeAces);
425
426 /**
427 * Creates a new policy.
428 *
429 * @return the object ID of the new policy
430 *
431 * @cmis 1.0
432 */
433 Future<ObjectId> createPolicy(Map<String, ?> properties, ObjectId folderId);
434
435 /**
436 * Creates a new item.
437 *
438 * @return the object ID of the new policy
439 *
440 * @cmis 1.1
441 */
442 Future<ObjectId> createItem(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
443 List<Ace> removeAces);
444
445 /**
446 * Creates a new item.
447 *
448 * @return the object ID of the new item
449 *
450 * @cmis 1.1
451 */
452 Future<ObjectId> createItem(Map<String, ?> properties, ObjectId folderId);
453
454 /**
455 * Creates a new relationship.
456 *
457 * @return the object ID of the new relationship
458 *
459 * @cmis 1.0
460 */
461 Future<ObjectId> createRelationship(Map<String, ?> properties, List<Policy> policies, List<Ace> addAces,
462 List<Ace> removeAces);
463
464 /**
465 * Creates a new relationship.
466 *
467 * @return the object ID of the new relationship
468 *
469 * @cmis 1.0
470 */
471 Future<ObjectId> createRelationship(Map<String, ?> properties);
472
473 // --- content ---
474
475 /**
476 * Retrieves the content stream of a document.
477 *
478 * @param docId
479 * the ID of the document
480 * @param streamId
481 * the stream ID
482 * @param offset
483 * the offset of the stream or {@code null} to read the stream
484 * from the beginning
485 * @param length
486 * the maximum length of the stream or {@code null} to read to
487 * the end of the stream
488 *
489 * @return the content stream or {@code null} if the document has no content
490 * stream
491 *
492 * @cmis 1.0
493 */
494 Future<ContentStream> getContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length);
495
496 /**
497 * Retrieves the main content stream of a document.
498 *
499 * @param docId
500 * the ID of the document
501 *
502 * @return the content stream or {@code null} if the document has no content
503 * stream
504 *
505 * @cmis 1.0
506 */
507 Future<ContentStream> getContentStream(ObjectId docId);
508
509 /**
510 * Reads the document content and writes it to an output stream.
511 *
512 * The output stream is not closed.
513 *
514 * @param docId
515 * the ID of the document
516 * @param streamId
517 * the stream ID
518 * @param offset
519 * the offset of the stream or {@code null} to read the stream
520 * from the beginning
521 * @param length
522 * the maximum length of the stream or {@code null} to read to
523 * the end of the stream
524 *
525 * @return the content stream object (the input stream is closed) or
526 * {@code null} if the document has no content stream
527 *
528 * @cmis 1.0
529 */
530 Future<ContentStream> storeContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length,
531 OutputStream target);
532
533 /**
534 * Reads the document content and writes it to an output stream.
535 *
536 * The output stream is not closed.
537 *
538 * @param docId
539 * the ID of the document
540 *
541 * @return the content stream object (the input stream is closed) or
542 * {@code null} if the document has no content stream
543 *
544 * @cmis 1.0
545 */
546 Future<ContentStream> storeContentStream(ObjectId docId, OutputStream target);
547
548 // --- delete ---
549
550 /**
551 * Deletes an object.
552 *
553 * @param objectId
554 * the ID of the object
555 * @param allVersions
556 * if this object is a document this parameter defines if only
557 * this version or all versions should be deleted
558 *
559 * @cmis 1.0
560 */
561 Future<?> delete(ObjectId objectId, boolean allVersions);
562
563 /**
564 * Deletes an object and, if it is a document, all versions in the version
565 * series.
566 *
567 * @param objectId
568 * the ID of the object
569 *
570 * @cmis 1.0
571 */
572 Future<?> delete(ObjectId objectId);
573
574 /**
575 * Deletes a folder and all subfolders.
576 *
577 * @param folderId
578 * the ID of the folder
579 * @param allVersions
580 * if this object is a document this parameter defines if only
581 * this version or all versions should be deleted
582 * @param unfile
583 * defines how objects should be unfiled
584 * @param continueOnFailure
585 * if {@code true} the repository tries to delete as many objects
586 * as possible; if {@code false} the repository stops at the
587 * first object that could not be deleted
588 *
589 * @return a list of object IDs which failed to be deleted
590 *
591 * @cmis 1.0
592 */
593 Future<List<String>> deleteTree(ObjectId folderId, boolean allVersions, UnfileObject unfile,
594 boolean continueOnFailure);
595
596 // --- ACL ---
597
598 /**
599 * Applies ACL changes to an object and dependent objects.
600 *
601 * Only direct ACEs can be added and removed.
602 *
603 * @param objectId
604 * the ID the object
605 * @param addAces
606 * list of ACEs to be added or {@code null} if no ACEs should be
607 * added
608 * @param removeAces
609 * list of ACEs to be removed or {@code null} if no ACEs should
610 * be removed
611 * @param aclPropagation
612 * value that defines the propagation of the ACE changes;
613 * {@code null} is equal to
614 * {@link AclPropagation#REPOSITORYDETERMINED}
615 *
616 * @return the new ACL of the object
617 *
618 * @cmis 1.0
619 */
620 Future<Acl> applyAcl(ObjectId objectId, List<Ace> addAces, List<Ace> removeAces, AclPropagation aclPropagation);
621
622 /**
623 * Removes the direct ACEs of an object and sets the provided ACEs.
624 *
625 * The changes are local to the given object and are not propagated to
626 * dependent objects.
627 *
628 * @param objectId
629 * the ID the object
630 * @param aces
631 * list of ACEs to be set
632 *
633 * @return the new ACL of the object
634 *
635 * @cmis 1.0
636 */
637 Future<Acl> setAcl(ObjectId objectId, List<Ace> aces);
638
639 // --- policy ---
640
641 /**
642 * Applies a set of policies to an object.
643 *
644 * This operation is not atomic. If it fails some policies might already be
645 * applied.
646 *
647 * @param objectId
648 * the ID the object
649 * @param policyIds
650 * the IDs of the policies to be applied
651 *
652 * @cmis 1.0
653 */
654 Future<?> applyPolicy(ObjectId objectId, ObjectId... policyIds);
655
656 /**
657 * Removes a set of policies from an object.
658 *
659 * This operation is not atomic. If it fails some policies might already be
660 * removed.
661 *
662 * @param objectId
663 * the ID the object
664 * @param policyIds
665 * the IDs of the policies to be removed
666 *
667 * @cmis 1.0
668 */
669 Future<?> removePolicy(ObjectId objectId, ObjectId... policyIds);
670 }