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.math.BigInteger;
23 import java.util.Collection;
24 import java.util.List;
25 import java.util.Locale;
26 import java.util.Map;
27 import java.util.Set;
28
29 import org.apache.chemistry.opencmis.commons.data.Ace;
30 import org.apache.chemistry.opencmis.commons.data.Acl;
31 import org.apache.chemistry.opencmis.commons.data.BulkUpdateObjectIdAndChangeToken;
32 import org.apache.chemistry.opencmis.commons.data.ContentStream;
33 import org.apache.chemistry.opencmis.commons.data.RepositoryInfo;
34 import org.apache.chemistry.opencmis.commons.definitions.TypeDefinition;
35 import org.apache.chemistry.opencmis.commons.enums.AclPropagation;
36 import org.apache.chemistry.opencmis.commons.enums.IncludeRelationships;
37 import org.apache.chemistry.opencmis.commons.enums.RelationshipDirection;
38 import org.apache.chemistry.opencmis.commons.enums.UnfileObject;
39 import org.apache.chemistry.opencmis.commons.enums.VersioningState;
40 import org.apache.chemistry.opencmis.commons.exceptions.CmisBaseException;
41 import org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
42 import org.apache.chemistry.opencmis.commons.spi.CmisBinding;
43
44 /**
45 * A session is a connection to a CMIS repository with a specific user.
46 * <p>
47 * CMIS itself is stateless. OpenCMIS uses the concept of a session to cache
48 * data across calls and to deal with user authentication. The session object is
49 * also used as entry point to all CMIS operations and objects. Because a
50 * session is only a client side concept, the session object needs not to be
51 * closed or released when it's not needed anymore.
52 * <p>
53 * Not all operations provided by this API might be supported by the connected
54 * repository. Either OpenCMIS or the repository will throw an exception if an
55 * unsupported operation is called. The capabilities of the repository can be
56 * discovered by evaluating the repository info (see
57 * {@link #getRepositoryInfo()}).
58 * <p>
59 * Almost all methods might throw exceptions derived from
60 * {@link CmisBaseException} which is a runtime exception. See the CMIS
61 * specification for a list of all operations and their exceptions. Note that
62 * some incompliant repositories might throw other exception than you expect.
63 * <p>
64 * Refer to the <a href="http://docs.oasis-open.org/cmis/CMIS/v1.0/os/">CMIS 1.0
65 * specification</a> or the
66 * <a href="http://docs.oasis-open.org/cmis/CMIS/v1.0/os/">CMIS 1.1
67 * specification</a> for details about the domain model, terms, concepts, base
68 * types, properties, IDs and query names, query language, etc.
69 * </p>
70 */
71 public interface Session extends Serializable {
72
73 /**
74 * Clears all cached data.
75 */
76 void clear();
77
78 // session context
79
80 /**
81 * Returns the underlying binding object.
82 *
83 * @return the binding object, not {@code null}
84 */
85 CmisBinding getBinding();
86
87 /**
88 * Returns the session parameters that were used to create this session.
89 *
90 * @return the session parameters, a unmodifiable Map, not {@code null}
91 */
92 Map<String, String> getSessionParameters();
93
94 /**
95 * Returns the current default operation parameters for filtering, paging
96 * and caching.
97 *
98 * <p>
99 * <em>Please note:</em> The returned object is not thread-safe and should
100 * only be modified right after the session has been created and before the
101 * session object has been used. In order to change the default context in
102 * thread-safe manner, create a new {@link OperationContext} object and use
103 * {@link #setDefaultContext(OperationContext)} to apply it.
104 * </p>
105 *
106 * @return the default operation context, not {@code null}
107 */
108 OperationContext getDefaultContext();
109
110 /**
111 * Sets the current session parameters for filtering, paging and caching.
112 *
113 * @param context
114 * the {@code OperationContext} to be used for the session; if
115 * {@code null}, a default context is used
116 */
117 void setDefaultContext(OperationContext context);
118
119 /**
120 * Creates a new operation context object.
121 *
122 * @return the newly created operation context object
123 */
124 OperationContext createOperationContext();
125
126 /**
127 * Creates a new operation context object with the given properties.
128 *
129 * @param filter
130 * the property filter, a comma separated string of <em>query
131 * names</em> or "*" for all properties or {@code null} to let
132 * the repository determine a set of properties
133 * @param includeAcls
134 * indicates whether ACLs should be included or not
135 * @param includeAllowableActions
136 * indicates whether Allowable Actions should be included or not
137 * @param includePolicies
138 * indicates whether policies should be included or not
139 * @param includeRelationships
140 * enum that indicates if and which relationships should be
141 * includes
142 * @param renditionFilter
143 * the rendition filter or {@code null} for no renditions
144 * @param includePathSegments
145 * indicates whether path segment or the relative path segment
146 * should be included or not
147 * @param orderBy
148 * the object order, a comma-separated list of <em>query
149 * names</em> and the ascending modifier "ASC" or the descending
150 * modifier "DESC" for each query name
151 * @param cacheEnabled
152 * flag that indicates if the object cache should be used
153 * @param maxItemsPerPage
154 * the max items per batch
155 *
156 * @return the newly created operation context object
157 *
158 * @see OperationContext
159 */
160 OperationContext createOperationContext(Set<String> filter, boolean includeAcls, boolean includeAllowableActions,
161 boolean includePolicies, IncludeRelationships includeRelationships, Set<String> renditionFilter,
162 boolean includePathSegments, String orderBy, boolean cacheEnabled, int maxItemsPerPage);
163
164 /**
165 * Creates an object ID from a String.
166 *
167 * @return the object ID object
168 */
169 ObjectId createObjectId(String id);
170
171 // localization
172
173 /**
174 * Get the current locale to be used for this session.
175 *
176 * @return the current locale, may be {@code null}
177 */
178 Locale getLocale();
179
180 // services
181
182 /**
183 * Returns the repository info of the repository associated with this
184 * session.
185 *
186 * @return the repository info, not {@code null}
187 *
188 * @cmis 1.0
189 */
190 RepositoryInfo getRepositoryInfo();
191
192 /**
193 * Gets a factory object that provides methods to create the objects used by
194 * this API.
195 *
196 * @return the repository info, not {@code null}
197 */
198 ObjectFactory getObjectFactory();
199
200 // types
201
202 /**
203 * Gets the definition of a type.
204 *
205 * @param typeId
206 * the ID of the type
207 *
208 * @return the type definition
209 *
210 * @throws CmisObjectNotFoundException
211 * if a type with the given type ID doesn't exist
212 *
213 * @cmis 1.0
214 */
215 ObjectType getTypeDefinition(String typeId);
216
217 /**
218 * Gets the definition of a type.
219 *
220 * @param typeId
221 * the ID of the type
222 * @param useCache
223 * specifies if the type definition should be first looked up in
224 * the type definition cache, if it is set to {@code false} or
225 * the type definition is not in the cache, the type definition
226 * is loaded from the repository
227 *
228 * @return the type definition
229 *
230 * @throws CmisObjectNotFoundException
231 * if a type with the given type ID doesn't exist
232 *
233 * @cmis 1.0
234 */
235 ObjectType getTypeDefinition(String typeId, boolean useCache);
236
237 /**
238 * Gets the type children of a type.
239 *
240 * @param typeId
241 * the type ID or {@code null} to request the base types
242 * @param includePropertyDefinitions
243 * indicates whether the property definitions should be included
244 * or not
245 * @return the type iterator, not {@code null}
246 *
247 * @throws CmisObjectNotFoundException
248 * if a type with the given type ID doesn't exist
249 *
250 * @cmis 1.0
251 */
252 ItemIterable<ObjectType> getTypeChildren(String typeId, boolean includePropertyDefinitions);
253
254 /**
255 * Gets the type descendants of a type.
256 *
257 * @param typeId
258 * the type ID or {@code null} to request the base types
259 * @param depth
260 * the tree depth, must be greater than 0 or -1 for infinite
261 * depth
262 * @param includePropertyDefinitions
263 * indicates whether the property definitions should be included
264 * or not
265 * @return the tree of types
266 *
267 * @throws CmisObjectNotFoundException
268 * if a type with the given type ID doesn't exist
269 *
270 * @cmis 1.0
271 */
272 List<Tree<ObjectType>> getTypeDescendants(String typeId, int depth, boolean includePropertyDefinitions);
273
274 /**
275 * Creates a new type.
276 *
277 * @param type
278 * the type definition
279 *
280 * @return the new type definition
281 *
282 * @cmis 1.1
283 */
284 ObjectType createType(TypeDefinition type);
285
286 /**
287 * Updates an existing type.
288 *
289 * @param type
290 * the type definition updates
291 *
292 * @return the updated type definition
293 *
294 * @cmis 1.1
295 */
296 ObjectType updateType(TypeDefinition type);
297
298 /**
299 * Deletes a type.
300 *
301 * @param typeId
302 * the ID of the type to delete
303 *
304 * @cmis 1.1
305 */
306 void deleteType(String typeId);
307
308 // navigation
309
310 /**
311 * Gets the root folder of the repository.
312 *
313 * @return the root folder object, not {@code null}
314 *
315 * @cmis 1.0
316 */
317 Folder getRootFolder();
318
319 /**
320 * Gets the root folder of the repository with the given
321 * {@link OperationContext}.
322 *
323 * @return the root folder object, not {@code null}
324 *
325 * @cmis 1.0
326 */
327 Folder getRootFolder(OperationContext context);
328
329 /**
330 * Returns all checked out documents.
331 *
332 * @see Folder#getCheckedOutDocs()
333 *
334 * @cmis 1.0
335 */
336 ItemIterable<Document> getCheckedOutDocs();
337
338 /**
339 * Returns all checked out documents with the given {@link OperationContext}
340 * .
341 *
342 * @see Folder#getCheckedOutDocs(OperationContext)
343 *
344 * @cmis 1.0
345 */
346 ItemIterable<Document> getCheckedOutDocs(OperationContext context);
347
348 /**
349 * Returns a CMIS object from the session cache. If the object is not in the
350 * cache or the cache is turned off per default {@link OperationContext}, it
351 * will load the object from the repository and puts it into the cache.
352 * <p>
353 * This method might return a stale object if the object has been found in
354 * the cache and has been changed in or removed from the repository. Use
355 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
356 * update the object if necessary.
357 *
358 * @param objectId
359 * the object ID
360 *
361 * @return the requested object
362 *
363 * @throws CmisObjectNotFoundException
364 * if an object with the given ID doesn't exist
365 *
366 * @see #getObject(String)
367 *
368 * @cmis 1.0
369 */
370 CmisObject getObject(ObjectId objectId);
371
372 /**
373 * Returns a CMIS object from the session cache. If the object is not in the
374 * cache or the given {@link OperationContext} has caching turned off, it
375 * will load the object from the repository and puts it into the cache.
376 * <p>
377 * This method might return a stale object if the object has been found in
378 * the cache and has been changed in or removed from the repository. Use
379 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
380 * update the object if necessary.
381 *
382 * @param objectId
383 * the object ID
384 * @param context
385 * the {@link OperationContext} to use
386 *
387 * @return the requested object
388 *
389 * @throws CmisObjectNotFoundException
390 * if an object with the given ID doesn't exist
391 *
392 * @see #getObject(String, OperationContext)
393 *
394 * @cmis 1.0
395 */
396 CmisObject getObject(ObjectId objectId, OperationContext context);
397
398 /**
399 * Returns a CMIS object from the session cache. If the object is not in the
400 * cache or the cache is turned off per default {@link OperationContext}, it
401 * will load the object from the repository and puts it into the cache.
402 * <p>
403 * This method might return a stale object if the object has been found in
404 * the cache and has been changed in or removed from the repository. Use
405 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
406 * update the object if necessary.
407 *
408 * @param objectId
409 * the object ID
410 *
411 * @return the requested object
412 *
413 * @throws CmisObjectNotFoundException
414 * if an object with the given ID doesn't exist
415 *
416 * @see #getObject(ObjectId)
417 *
418 * @cmis 1.0
419 */
420 CmisObject getObject(String objectId);
421
422 /**
423 * Returns a CMIS object from the session cache. If the object is not in the
424 * cache or the given {@link OperationContext} has caching turned off, it
425 * will load the object from the repository and puts it into the cache.
426 * <p>
427 * This method might return a stale object if the object has been found in
428 * the cache and has been changed in or removed from the repository. Use
429 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
430 * update the object if necessary.
431 *
432 * @param objectId
433 * the object ID
434 * @param context
435 * the {@link OperationContext} to use
436 *
437 * @return the requested object
438 *
439 * @throws CmisObjectNotFoundException
440 * if an object with the given ID doesn't exist
441 *
442 * @see #getObject(ObjectId, OperationContext)
443 *
444 * @cmis 1.0
445 */
446 CmisObject getObject(String objectId, OperationContext context);
447
448 /**
449 * Returns a CMIS object from the session cache. If the object is not in the
450 * cache or the cache is turned off per default {@link OperationContext}, it
451 * will load the object from the repository and puts it into the cache.
452 * <p>
453 * This method might return a stale object if the object has been found in
454 * the cache and has been changed in or removed from the repository. Use
455 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
456 * update the object if necessary.
457 *
458 * @param path
459 * the object path
460 *
461 * @return the requested object
462 *
463 * @throws CmisObjectNotFoundException
464 * if an object with the given ID doesn't exist
465 *
466 * @cmis 1.0
467 */
468 CmisObject getObjectByPath(String path);
469
470 /**
471 * Returns a CMIS object from the session cache. If the object is not in the
472 * cache or the given {@link OperationContext} has caching turned off, it
473 * will load the object from the repository and puts it into the cache.
474 * <p>
475 * This method might return a stale object if the object has been found in
476 * the cache and has been changed in or removed from the repository. Use
477 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
478 * update the object if necessary.
479 *
480 * @param path
481 * the object path
482 * @param context
483 * the {@link OperationContext} to use
484 *
485 * @return the requested object
486 *
487 * @throws CmisObjectNotFoundException
488 * if an object with the given ID doesn't exist
489 *
490 * @cmis 1.0
491 */
492 CmisObject getObjectByPath(String path, OperationContext context);
493
494 /**
495 * Returns a CMIS object from the session cache. If the object is not in the
496 * cache or the cache is turned off per default {@link OperationContext}, it
497 * will load the object from the repository and puts it into the cache.
498 * <p>
499 * This method might return a stale object if the object has been found in
500 * the cache and has been changed in or removed from the repository. Use
501 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
502 * update the object if necessary.
503 *
504 * @param parentPath
505 * the path of the parent folder
506 * @param name
507 * the (path segment) name of the object in the folder
508 *
509 * @return the requested object
510 *
511 * @throws CmisObjectNotFoundException
512 * if an object with the given ID doesn't exist
513 *
514 * @cmis 1.0
515 */
516 CmisObject getObjectByPath(String parentPath, String name);
517
518 /**
519 * Returns a CMIS object from the session cache. If the object is not in the
520 * cache or the given {@link OperationContext} has caching turned off, it
521 * will load the object from the repository and puts it into the cache.
522 * <p>
523 * This method might return a stale object if the object has been found in
524 * the cache and has been changed in or removed from the repository. Use
525 * {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
526 * update the object if necessary.
527 *
528 * @param parentPath
529 * the path of the parent folder
530 * @param name
531 * the (path segment) name of the object in the folder
532 * @param context
533 * the {@link OperationContext} to use
534 *
535 * @return the requested object
536 *
537 * @throws CmisObjectNotFoundException
538 * if an object with the given ID doesn't exist
539 *
540 * @cmis 1.0
541 */
542 CmisObject getObjectByPath(String parentPath, String name, OperationContext context);
543
544 /**
545 * Returns the latest version in a version series.
546 *
547 * Some repositories throw an exception if the document is not versionable;
548 * others just return the unversioned document. To avoid surprises, check
549 * first whether the document is versionable or not.
550 *
551 * @param objectId
552 * the document ID of an arbitrary version in the version series
553 *
554 * @return the latest document version
555 *
556 * @cmis 1.0
557 */
558 Document getLatestDocumentVersion(ObjectId objectId);
559
560 /**
561 * Returns the latest version in a version series.
562 *
563 * Some repositories throw an exception if the document is not versionable;
564 * others just return the unversioned document. To avoid surprises, check
565 * first whether the document is versionable or not.
566 *
567 * @param objectId
568 * the document ID of an arbitrary version in the version series
569 * @param context
570 * the {@link OperationContext} to use
571 *
572 * @return the latest document version
573 *
574 * @cmis 1.0
575 */
576 Document getLatestDocumentVersion(ObjectId objectId, OperationContext context);
577
578 /**
579 * Returns the latest version in a version series.
580 *
581 * Some repositories throw an exception if the document is not versionable;
582 * others just return the unversioned document. To avoid surprises, check
583 * first whether the document is versionable or not.
584 *
585 * If {@code major} == {@code true} and the version series doesn't contain a
586 * major version, the repository is supposed to throw a
587 * {@link CmisObjectNotFoundException}.
588 *
589 * @param objectId
590 * the document ID of an arbitrary version in the version series
591 * @param major
592 * if {@code true} the latest major version will be returned,
593 * otherwise the very last version will be returned
594 * @param context
595 * the {@link OperationContext} to use
596 *
597 * @return the latest document version
598 *
599 * @cmis 1.0
600 */
601 Document getLatestDocumentVersion(ObjectId objectId, boolean major, OperationContext context);
602
603 /**
604 * Returns the latest version in a version series.
605 *
606 * Some repositories throw an exception if the document is not versionable;
607 * others just return the unversioned document. To avoid surprises, check
608 * first whether the document is versionable or not.
609 *
610 * @param objectId
611 * the document ID of an arbitrary version in the version series
612 *
613 * @return the latest document version
614 *
615 * @cmis 1.0
616 */
617 Document getLatestDocumentVersion(String objectId);
618
619 /**
620 * Returns the latest version in a version series.
621 *
622 * Some repositories throw an exception if the document is not versionable;
623 * others just return the unversioned document. To avoid surprises, check
624 * first whether the document is versionable or not.
625 *
626 * @param objectId
627 * the document ID of an arbitrary version in the version series
628 * @param context
629 * the {@link OperationContext} to use
630 *
631 * @return the latest document version
632 *
633 * @cmis 1.0
634 */
635 Document getLatestDocumentVersion(String objectId, OperationContext context);
636
637 /**
638 * Returns the latest version in a version series.
639 *
640 * Some repositories throw an exception if the document is not versionable;
641 * others just return the unversioned document. To avoid surprises, check
642 * first whether the document is versionable or not.
643 *
644 * If {@code major} == {@code true} and the version series doesn't contain a
645 * major version, the repository is supposed to throw a
646 * {@link CmisObjectNotFoundException}.
647 *
648 * @param objectId
649 * the document ID of an arbitrary version in the version series
650 * @param major
651 * if {@code true} the latest major version will be returned,
652 * otherwise the very last version will be returned
653 * @param context
654 * the {@link OperationContext} to use
655 *
656 * @return the latest document version
657 *
658 * @cmis 1.0
659 */
660 Document getLatestDocumentVersion(String objectId, boolean major, OperationContext context);
661
662 /**
663 * Checks if an object with given object ID exists in the repository and is
664 * visible for the current user.
665 *
666 * If the object doesn't exist (anymore), it is removed from the cache.
667 *
668 * @param objectId
669 * the object ID
670 * @return {@code true} if the object exists in the repository,
671 * {@code false} otherwise
672 *
673 * @cmis 1.0
674 */
675 boolean exists(ObjectId objectId);
676
677 /**
678 * Checks if an object with given object ID exists in the repository and is
679 * visible for the current user.
680 *
681 * If the object doesn't exist (anymore), it is removed from the cache.
682 *
683 * @param objectId
684 * the object ID
685 * @return {@code true} if the object exists in the repository,
686 * {@code false} otherwise
687 *
688 * @cmis 1.0
689 */
690 boolean exists(String objectId);
691
692 /**
693 * Checks if an object with given path exists in the repository and is
694 * visible for the current user.
695 *
696 * If the object doesn't exist (anymore), it is removed from the cache.
697 *
698 * @param path
699 * the path
700 * @return {@code true} if the object exists in the repository,
701 * {@code false} otherwise
702 *
703 * @cmis 1.0
704 */
705 boolean existsPath(String path);
706
707 /**
708 * Checks if an object with given path exists in the repository and is
709 * visible for the current user.
710 *
711 * If the object doesn't exist (anymore), it is removed from the cache.
712 *
713 * @param parentPath
714 * the path of the parent folder
715 * @param name
716 * the (path segment) name of the object in the folder
717 *
718 * @return the requested object
719 *
720 * @throws CmisObjectNotFoundException
721 * if an object with the given ID doesn't exist
722 *
723 * @cmis 1.0
724 */
725 boolean existsPath(String parentPath, String name);
726
727 /**
728 * Removes the given object from the cache.
729 *
730 * @param objectId
731 * object ID
732 *
733 * @see #removeObjectFromCache(String)
734 */
735 void removeObjectFromCache(ObjectId objectId);
736
737 /**
738 * Removes the given object from the cache.
739 *
740 * @param objectId
741 * object ID
742 */
743 void removeObjectFromCache(String objectId);
744
745 // discovery
746
747 /**
748 * Sends a query to the repository. Refer to the CMIS specification for the
749 * CMIS query language syntax.
750 *
751 * @param statement
752 * the query statement (CMIS query language)
753 * @param searchAllVersions
754 * specifies whether non-latest document versions should be
755 * included or not, {@code true} searches all document versions,
756 * {@code false} only searches latest document versions
757 *
758 * @return an {@link Iterable} to iterate over the query result
759 *
760 * @cmis 1.0
761 */
762 ItemIterable<QueryResult> query(String statement, boolean searchAllVersions);
763
764 /**
765 * Sends a query to the repository using the given {@link OperationContext}.
766 * (See CMIS spec "2.1.10 Query".)
767 *
768 * @param statement
769 * the query statement (CMIS query language)
770 * @param searchAllVersions
771 * specifies whether non-latest document versions should be
772 * included or not, {@code true} searches all document versions,
773 * {@code false} only searches latest document versions
774 * @param context
775 * the operation context to use
776 *
777 * @return an {@link Iterable} to iterate over the query result
778 *
779 * @cmis 1.0
780 */
781 ItemIterable<QueryResult> query(String statement, boolean searchAllVersions, OperationContext context);
782
783 /**
784 * Builds a CMIS query and returns the query results as an iterator of
785 * {@link CmisObject} objects.
786 *
787 * @param typeId
788 * the ID of the object type
789 * @param where
790 * the WHERE part of the query
791 * @param searchAllVersions
792 * specifies whether non-latest document versions should be
793 * included or not, {@code true} searches all document versions,
794 * {@code false} only searches latest document versions
795 * @param context
796 * the operation context to use
797 *
798 * @return an {@link Iterable} to iterate over the objects
799 *
800 * @cmis 1.0
801 */
802 ItemIterable<CmisObject> queryObjects(String typeId, String where, boolean searchAllVersions,
803 OperationContext context);
804
805 /**
806 * Creates a query statement.
807 * <p>
808 * Sample code:
809 *
810 * <pre>
811 * QueryStatement stmt = session
812 * .createQueryStatement("SELECT ?, ? FROM ? WHERE ? > TIMESTAMP ? AND IN_FOLDER(?) OR ? IN (?)");
813 * </pre>
814 *
815 * @param statement
816 * the query statement with placeholders ('?'), see
817 * {@link QueryStatement} for details
818 *
819 * @return a new query statement object
820 *
821 * @see QueryStatement
822 *
823 * @cmis 1.0
824 */
825 QueryStatement createQueryStatement(String statement);
826
827 /**
828 * Creates a query statement for a query of one primary type joined by zero
829 * or more secondary types.
830 * <p>
831 * Sample code:
832 *
833 * <pre>
834 * List<String> select = new ArrayList<String>();
835 * select.add("cmis:name");
836 * select.add("SecondaryStringProp");
837 *
838 * Map<String, String> from = new HashMap<String, String>();
839 * from.put("d", "cmis:document");
840 * from.put("s", "MySecondaryType");
841 *
842 * String where = "d.cmis:name LIKE ?";
843 *
844 * List<String> orderBy = new ArrayList<String>();
845 * orderBy.add("cmis:name");
846 * orderBy.add("SecondaryIntegerProp");
847 *
848 * QueryStatement stmt = session.createQueryStatement(select, from, where, orderBy);
849 * </pre>
850 *
851 * Generates something like this:
852 *
853 * <pre>
854 * SELECT d.cmis:name,s.SecondaryStringProp FROM cmis:document AS d JOIN MySecondaryType AS s ON d.cmis:objectId=s.cmis:objectId WHERE d.cmis:name LIKE ? ORDER BY d.cmis:name,s.SecondaryIntegerProp
855 * </pre>
856 *
857 * @param selectPropertyIds
858 * the property IDs in the SELECT statement, if {@code null} all
859 * properties are selected
860 * @param fromTypes
861 * a Map of type aliases (keys) and type IDs (values), the Map
862 * must contain exactly one primary type and zero or more
863 * secondary types
864 * @param whereClause
865 * an optional WHERE clause with placeholders ('?'), see
866 * {@link QueryStatement} for details
867 * @param orderByPropertyIds
868 * an optional list of properties IDs for the ORDER BY clause
869 *
870 * @return a new query statement object
871 *
872 * @see QueryStatement
873 *
874 * @cmis 1.0
875 */
876 QueryStatement createQueryStatement(Collection<String> selectPropertyIds, Map<String, String> fromTypes,
877 String whereClause, List<String> orderByPropertyIds);
878
879 /**
880 * Returns the content changes.
881 *
882 * @param changeLogToken
883 * the change log token to start from or {@code null} to start
884 * from the first available event in the repository
885 * @param includeProperties
886 * indicates whether changed properties should be included in the
887 * result or not
888 * @param maxNumItems
889 * maximum numbers of events
890 *
891 * @return the change events
892 *
893 * @cmis 1.0
894 */
895 ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems);
896
897 /**
898 * Returns the content changes.
899 *
900 * @param changeLogToken
901 * the change log token to start from or {@code null} to start
902 * from the first available event in the repository
903 * @param includeProperties
904 * indicates whether changed properties should be included in the
905 * result or not
906 * @param maxNumItems
907 * maximum numbers of events
908 * @param context
909 * the OperationContext
910 *
911 * @return the change events
912 *
913 * @cmis 1.0
914 */
915 ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems,
916 OperationContext context);
917
918 /**
919 * Returns an iterator of content changes, starting from the given change
920 * log token to the latest entry in the change log.
921 * <p>
922 * Note: Paging and skipping are not supported.
923 *
924 * @param changeLogToken
925 * the change log token to start from or {@code null} to start
926 * from the first available event in the repository
927 * @param includeProperties
928 * indicates whether changed properties should be included in the
929 * result or not
930 *
931 * @cmis 1.0
932 */
933 ItemIterable<ChangeEvent> getContentChanges(String changeLogToken, boolean includeProperties);
934
935 /**
936 * Returns an iterator of content changes, starting from the given change
937 * log token to the latest entry in the change log.
938 * <p>
939 * Note: Paging and skipping are not supported.
940 *
941 * @param changeLogToken
942 * the change log token to start from or {@code null} to start
943 * from the first available event in the repository
944 * @param includeProperties
945 * indicates whether changed properties should be included in the
946 * result or not
947 * @param context
948 * the OperationContext
949 *
950 * @cmis 1.0
951 */
952 ItemIterable<ChangeEvent> getContentChanges(final String changeLogToken, final boolean includeProperties,
953 OperationContext context);
954
955 /**
956 * Returns the latest change log token.
957 * <p>
958 * In contrast to the repository info, this change log token is not cached.
959 * This method requests the token from the repository every single time it
960 * is called.
961 *
962 * @return the latest change log token or {@code null} if the repository
963 * doesn't provide one
964 *
965 * @cmis 1.0
966 */
967 String getLatestChangeLogToken();
968
969 // create
970
971 /**
972 * Creates a new document.
973 *
974 * The stream in {@code contentStream} is consumed but not closed by this
975 * method.
976 *
977 * @return the object ID of the new document
978 *
979 * @see Folder#createDocument(Map, ContentStream, VersioningState, List,
980 * List, List, OperationContext)
981 *
982 * @cmis 1.0
983 */
984 ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
985 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
986
987 /**
988 * Creates a new document.
989 *
990 * The stream in {@code contentStream} is consumed but not closed by this
991 * method.
992 *
993 * @return the object ID of the new document
994 *
995 * @see Folder#createDocument(Map, ContentStream, VersioningState, List,
996 * List, List, OperationContext)
997 *
998 * @cmis 1.0
999 */
1000 ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
1001 VersioningState versioningState);
1002
1003 /**
1004 * Creates a new document from a source document.
1005 *
1006 * @return the object ID of the new document
1007 *
1008 * @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState,
1009 * List, List, List, OperationContext)
1010 *
1011 * @cmis 1.0
1012 */
1013 ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
1014 VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
1015
1016 /**
1017 * Creates a new document from a source document.
1018 *
1019 * @return the object ID of the new document
1020 *
1021 * @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState,
1022 * List, List, List, OperationContext)
1023 *
1024 * @cmis 1.0
1025 */
1026 ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
1027 VersioningState versioningState);
1028
1029 /**
1030 * Creates a new folder.
1031 *
1032 * @param properties
1033 * the folder properties
1034 * @param folderId
1035 * the folder ID of the parent folder, not {@code null}
1036 *
1037 * @return the object ID of the new folder
1038 *
1039 * @see Folder#createFolder(Map, List, List, List, OperationContext)
1040 *
1041 * @cmis 1.0
1042 */
1043 ObjectId createFolder(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
1044 List<Ace> removeAces);
1045
1046 /**
1047 * Creates a new folder.
1048 *
1049 * @param properties
1050 * the folder properties
1051 * @param folderId
1052 * the folder ID of the parent folder, not {@code null}
1053 *
1054 * @return the object ID of the new folder
1055 *
1056 * @see Folder#createFolder(Map, List, List, List, OperationContext)
1057 *
1058 * @cmis 1.0
1059 */
1060 ObjectId createFolder(Map<String, ?> properties, ObjectId folderId);
1061
1062 /**
1063 * Creates a folder path.
1064 *
1065 * All missing folders in the path are created. Existing folders are not
1066 * touched.
1067 *
1068 * @param newPath
1069 * the absolute path
1070 * @param typeId
1071 * the type ID of all folders that are being created
1072 *
1073 * @return the object ID of the deepest folder
1074 *
1075 * @cmis 1.0
1076 */
1077 ObjectId createPath(String newPath, String typeId);
1078
1079 /**
1080 * Creates a folder path.
1081 *
1082 * All missing folders in the path are created. Existing folders are not
1083 * touched.
1084 *
1085 * @param startFolderId
1086 * the ID of a folder in the path that the path creation should
1087 * start with, {@code null} for the root folder.
1088 * @param newPath
1089 * the absolute path
1090 * @param typeId
1091 * the type ID of all folders that are being created
1092 *
1093 * @return the object ID of the deepest folder
1094 *
1095 * @cmis 1.0
1096 */
1097 ObjectId createPath(ObjectId startFolderId, String newPath, String typeId);
1098
1099 /**
1100 * Creates a folder path.
1101 *
1102 * All missing folders in the path are created. Existing folders are not
1103 * touched.
1104 *
1105 * @param newPath
1106 * the absolute path
1107 * @param properties
1108 * the properties of all folders that are being created
1109 *
1110 * @return the object ID of the deepest folder
1111 *
1112 * @cmis 1.0
1113 */
1114 ObjectId createPath(String newPath, Map<String, ?> properties);
1115
1116 /**
1117 * Creates a folder path.
1118 *
1119 * All missing folders in the path are created. Existing folders are not
1120 * touched.
1121 *
1122 * @param startFolderId
1123 * the ID of a folder in the path that the path creation should
1124 * start with, {@code null} for the root folder
1125 * @param newPath
1126 * the absolute path
1127 * @param properties
1128 * the properties of all folders that are being created
1129 *
1130 * @return the object ID of the deepest folder
1131 *
1132 * @cmis 1.0
1133 */
1134 ObjectId createPath(ObjectId startFolderId, String newPath, Map<String, ?> properties);
1135
1136 /**
1137 * Creates a folder path.
1138 *
1139 * All missing folders in the path are created. Existing folders are not
1140 * touched.
1141 *
1142 * @param startFolderId
1143 * the ID of a folder in the path that the path creation should
1144 * start with, {@code null} for the root folder
1145 * @param newPath
1146 * the absolute path
1147 * @param properties
1148 * the properties of all folders that are being created
1149 *
1150 * @return the object ID of the deepest folder
1151 *
1152 * @cmis 1.0
1153 */
1154 ObjectId createPath(ObjectId startFolderId, String newPath, Map<String, ?> properties, List<Policy> policies,
1155 List<Ace> addAces, List<Ace> removeAces);
1156
1157 /**
1158 * Creates a new policy.
1159 *
1160 * @param properties
1161 * the policy properties
1162 * @param folderId
1163 * the folder ID of the parent folder, {@code null} for an
1164 * unfiled policy
1165 *
1166 * @return the object ID of the new policy
1167 *
1168 * @see Folder#createPolicy(Map, List, List, List, OperationContext)
1169 *
1170 * @cmis 1.0
1171 */
1172 ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
1173 List<Ace> removeAces);
1174
1175 /**
1176 * Creates a new policy.
1177 *
1178 * @param properties
1179 * the policy properties
1180 * @param folderId
1181 * the folder ID of the parent folder, {@code null} for an
1182 * unfiled policy
1183 *
1184 * @return the object ID of the new policy
1185 *
1186 * @see Folder#createPolicy(Map, List, List, List, OperationContext)
1187 *
1188 * @cmis 1.0
1189 */
1190 ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId);
1191
1192 /**
1193 * Creates a new item.
1194 *
1195 * @param properties
1196 * the item properties
1197 * @param folderId
1198 * the folder ID of the parent folder, {@code null} for an
1199 * unfiled item
1200 *
1201 * @return the object ID of the new policy
1202 *
1203 * @see Folder#createItem(Map, List, List, List, OperationContext)
1204 *
1205 * @cmis 1.1
1206 */
1207 ObjectId createItem(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
1208 List<Ace> removeAces);
1209
1210 /**
1211 * Creates a new item.
1212 *
1213 * @param properties
1214 * the item properties
1215 * @param folderId
1216 * the folder ID of the parent folder, {@code null} for an
1217 * unfiled item
1218 *
1219 * @return the object ID of the new item
1220 *
1221 * @see Folder#createItem(Map, List, List, List, OperationContext)
1222 *
1223 * @cmis 1.1
1224 */
1225 ObjectId createItem(Map<String, ?> properties, ObjectId folderId);
1226
1227 /**
1228 * Creates a new relationship.
1229 *
1230 * @param properties
1231 * the relationship properties
1232 *
1233 * @return the object ID of the new relationship
1234 *
1235 * @cmis 1.0
1236 */
1237 ObjectId createRelationship(Map<String, ?> properties, List<Policy> policies, List<Ace> addAces,
1238 List<Ace> removeAces);
1239
1240 /**
1241 * Creates a new relationship.
1242 *
1243 * @param properties
1244 * the relationship properties
1245 *
1246 * @return the object ID of the new relationship
1247 *
1248 * @cmis 1.0
1249 */
1250 ObjectId createRelationship(Map<String, ?> properties);
1251
1252 /**
1253 * Fetches the relationships from or to an object from the repository.
1254 *
1255 * @cmis 1.0
1256 */
1257 ItemIterable<Relationship> getRelationships(ObjectId objectId, boolean includeSubRelationshipTypes,
1258 RelationshipDirection relationshipDirection, ObjectType type, OperationContext context);
1259
1260 /**
1261 * Updates multiple objects in one request.
1262 *
1263 * @cmis 1.0
1264 */
1265 List<BulkUpdateObjectIdAndChangeToken> bulkUpdateProperties(List<CmisObject> objects, Map<String, ?> properties,
1266 List<String> addSecondaryTypeIds, List<String> removeSecondaryTypeIds);
1267
1268 /**
1269 * Deletes an object and, if it is a document, all versions in the version
1270 * series.
1271 *
1272 * @param objectId
1273 * the ID of the object
1274 *
1275 * @cmis 1.0
1276 */
1277 void delete(ObjectId objectId);
1278
1279 /**
1280 * Deletes an object.
1281 *
1282 * @param objectId
1283 * the ID of the object
1284 * @param allVersions
1285 * if this object is a document this parameter defines if only
1286 * this version or all versions should be deleted
1287 *
1288 * @cmis 1.0
1289 */
1290 void delete(ObjectId objectId, boolean allVersions);
1291
1292 /**
1293 * Deletes an object by path and, if it is a document, all versions in the
1294 * version series.
1295 *
1296 * @param path
1297 * the path of the object
1298 *
1299 * @cmis 1.0
1300 */
1301 public void deleteByPath(String path);
1302
1303 /**
1304 * Deletes an object by path and, if it is a document, all versions in the
1305 * version series.
1306 *
1307 * @param parentPath
1308 * the path of the parent folder
1309 * @param name
1310 * the (path segment) name of the object in the folder
1311 *
1312 * @cmis 1.0
1313 */
1314 void deleteByPath(String parentPath, String name);
1315
1316 /**
1317 * Deletes an object by path.
1318 *
1319 * @param path
1320 * the path of the object
1321 * @param allVersions
1322 * if this object is a document this parameter defines if only
1323 * this version or all versions should be deleted
1324 *
1325 * @cmis 1.0
1326 */
1327 void deleteByPath(String path, boolean allVersions);
1328
1329 /**
1330 * Deletes a folder and all subfolders.
1331 *
1332 * @param folderId
1333 * the ID of the folder
1334 * @param allVersions
1335 * if this object is a document this parameter defines if only
1336 * this version or all versions should be deleted
1337 * @param unfile
1338 * defines how objects should be unfiled
1339 * @param continueOnFailure
1340 * if {@code true} the repository tries to delete as many objects
1341 * as possible; if {@code false} the repository stops at the
1342 * first object that could not be deleted
1343 *
1344 * @return a list of object IDs which failed to be deleted
1345 *
1346 * @cmis 1.0
1347 */
1348 List<String> deleteTree(ObjectId folderId, boolean allVersions, UnfileObject unfile, boolean continueOnFailure);
1349
1350 /**
1351 * Deletes a folder and all subfolders by path.
1352 *
1353 * @param parentPath
1354 * the path of the parent folder
1355 * @param name
1356 * the (path segment) name of the folder in the parent folder
1357 * @param allVersions
1358 * if this object is a document this parameter defines if only
1359 * this version or all versions should be deleted
1360 * @param unfile
1361 * defines how objects should be unfiled
1362 * @param continueOnFailure
1363 * if {@code true} the repository tries to delete as many objects
1364 * as possible; if {@code false} the repository stops at the
1365 * first object that could not be deleted
1366 *
1367 * @return a list of object IDs which failed to be deleted
1368 *
1369 * @cmis 1.0
1370 */
1371 List<String> deleteTreebyPath(String parentPath, String name, boolean allVersions, UnfileObject unfile,
1372 boolean continueOnFailure);
1373
1374 /**
1375 * Deletes a folder and all subfolders by path.
1376 *
1377 * @param path
1378 * the path of the folder
1379 * @param allVersions
1380 * if this object is a document this parameter defines if only
1381 * this version or all versions should be deleted
1382 * @param unfile
1383 * defines how objects should be unfiled
1384 * @param continueOnFailure
1385 * if {@code true} the repository tries to delete as many objects
1386 * as possible; if {@code false} the repository stops at the
1387 * first object that could not be deleted
1388 *
1389 * @return a list of object IDs which failed to be deleted
1390 *
1391 * @cmis 1.0
1392 */
1393 List<String> deleteTreebyPath(String path, boolean allVersions, UnfileObject unfile, boolean continueOnFailure);
1394
1395 /**
1396 * Retrieves the main content stream of a document.
1397 *
1398 * @param docId
1399 * the ID of the document
1400 *
1401 * @return the content stream or {@code null} if the document has no content
1402 * stream
1403 *
1404 * @cmis 1.0
1405 */
1406 ContentStream getContentStream(ObjectId docId);
1407
1408 /**
1409 * Retrieves the content stream of a document.
1410 *
1411 * @param docId
1412 * the ID of the document
1413 * @param streamId
1414 * the stream ID or {@code null} for the main stream
1415 * @param offset
1416 * the offset of the stream or {@code null} to read the stream
1417 * from the beginning
1418 * @param length
1419 * the maximum length of the stream or {@code null} to read to
1420 * the end of the stream
1421 *
1422 * @return the content stream or {@code null} if the document has no content
1423 * stream
1424 *
1425 * @cmis 1.0
1426 */
1427 ContentStream getContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length);
1428
1429 /**
1430 * Retrieves the main content stream of a document.
1431 *
1432 * @param path
1433 * the path of the document
1434 *
1435 * @return the content stream or {@code null} if the document has no content
1436 * stream
1437 *
1438 * @cmis 1.0
1439 */
1440 ContentStream getContentStreamByPath(String path);
1441
1442 /**
1443 * Retrieves the content stream of a document.
1444 *
1445 * @param path
1446 * the path of the document
1447 * @param streamId
1448 * the stream ID or {@code null} for the main stream
1449 * @param offset
1450 * the offset of the stream or {@code null} to read the stream
1451 * from the beginning
1452 * @param length
1453 * the maximum length of the stream or {@code null} to read to
1454 * the end of the stream
1455 *
1456 * @return the content stream or {@code null} if the document has no content
1457 * stream
1458 *
1459 * @cmis 1.0
1460 */
1461 ContentStream getContentStreamByPath(String path, String streamId, BigInteger offset, BigInteger length);
1462
1463 /**
1464 * Fetches the ACL of an object from the repository.
1465 *
1466 * @param objectId
1467 * the ID the object
1468 * @param onlyBasicPermissions
1469 * if {@code true} the repository should express the ACL only
1470 * with the basic permissions defined in the CMIS specification;
1471 * if {@code false} the repository can express the ACL with basic
1472 * and repository specific permissions
1473 *
1474 * @return the ACL of the object
1475 *
1476 * @cmis 1.0
1477 */
1478 Acl getAcl(ObjectId objectId, boolean onlyBasicPermissions);
1479
1480 /**
1481 * Applies ACL changes to an object and dependent objects.
1482 *
1483 * Only direct ACEs can be added and removed.
1484 *
1485 * @param objectId
1486 * the ID the object
1487 * @param addAces
1488 * list of ACEs to be added or {@code null} if no ACEs should be
1489 * added
1490 * @param removeAces
1491 * list of ACEs to be removed or {@code null} if no ACEs should
1492 * be removed
1493 * @param aclPropagation
1494 * value that defines the propagation of the ACE changes;
1495 * {@code null} is equal to
1496 * {@link AclPropagation#REPOSITORYDETERMINED}
1497 *
1498 * @return the new ACL of the object
1499 *
1500 * @cmis 1.0
1501 */
1502 Acl applyAcl(ObjectId objectId, List<Ace> addAces, List<Ace> removeAces, AclPropagation aclPropagation);
1503
1504 /**
1505 * Removes the direct ACEs of an object and sets the provided ACEs.
1506 *
1507 * The changes are local to the given object and are not propagated to
1508 * dependent objects.
1509 *
1510 * @param objectId
1511 * the ID the object
1512 * @param aces
1513 * list of ACEs to be set
1514 *
1515 * @return the new ACL of the object
1516 *
1517 * @cmis 1.0
1518 */
1519 Acl setAcl(ObjectId objectId, List<Ace> aces);
1520
1521 /**
1522 * Applies a set of policies to an object.
1523 *
1524 * This operation is not atomic. If it fails some policies might already be
1525 * applied.
1526 *
1527 * @param objectId
1528 * the ID the object
1529 * @param policyIds
1530 * the IDs of the policies to be applied
1531 *
1532 * @cmis 1.0
1533 */
1534 void applyPolicy(ObjectId objectId, ObjectId... policyIds);
1535
1536 /**
1537 * Removes a set of policies from an object.
1538 *
1539 * This operation is not atomic. If it fails some policies might already be
1540 * removed.
1541 *
1542 * @param objectId
1543 * the ID the object
1544 * @param policyIds
1545 * the IDs of the policies to be removed
1546 *
1547 * @cmis 1.0
1548 */
1549 void removePolicy(ObjectId objectId, ObjectId... policyIds);
1550 }