001/*
002 * (C) Copyright 2006-2016 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Bogdan Stefanescu
018 *     Florent Guillaume
019 */
020
021package org.nuxeo.ecm.core.api;
022
023import java.io.Serializable;
024import java.security.Principal;
025import java.util.Arrays;
026import java.util.Collection;
027import java.util.List;
028import java.util.Map;
029
030import org.nuxeo.ecm.core.api.DocumentModel.DocumentModelRefresh;
031import org.nuxeo.ecm.core.api.event.DocumentEventTypes;
032import org.nuxeo.ecm.core.api.security.ACE;
033import org.nuxeo.ecm.core.api.security.ACP;
034import org.nuxeo.ecm.core.schema.DocumentType;
035import org.nuxeo.ecm.core.schema.types.Schema;
036
037/**
038 * A session to the Nuxeo Core.
039 *
040 * @see DocumentModel
041 * @see DocumentRef
042 * @author Bogdan Stefanescu
043 * @author Florent Guillaume
044 */
045public interface CoreSession extends AutoCloseable {
046
047    // used to pass properties to importDocument
048    String IMPORT_VERSION_VERSIONABLE_ID = "ecm:versionableId";
049
050    String IMPORT_VERSION_CREATED = "ecm:versionCreated";
051
052    String IMPORT_VERSION_LABEL = "ecm:versionLabel";
053
054    String IMPORT_VERSION_DESCRIPTION = "ecm:versionDescription";
055
056    String IMPORT_VERSION_IS_LATEST = "ecm:isLatestVersion";
057
058    String IMPORT_VERSION_IS_LATEST_MAJOR = "ecm:isLatestMajorVersion";
059
060    String IMPORT_IS_VERSION = "ecm:isVersion";
061
062    String IMPORT_VERSION_MAJOR = "ecm:majorVersion";
063
064    String IMPORT_VERSION_MINOR = "ecm:minorVersion";
065
066    String IMPORT_PROXY_TARGET_ID = "ecm:proxyTargetId";
067
068    String IMPORT_PROXY_VERSIONABLE_ID = "ecm:proxyVersionableId";
069
070    String IMPORT_LIFECYCLE_POLICY = "ecm:lifeCyclePolicy";
071
072    String IMPORT_LIFECYCLE_STATE = "ecm:lifeCycleState";
073
074    /**
075     * @deprecated since 5.4.2, use {@link #IMPORT_LOCK_OWNER} and {@link #IMPORT_LOCK_CREATED} instead
076     */
077    @Deprecated
078    String IMPORT_LOCK = "ecm:lock";
079
080    /** @since 5.4.2 */
081    String IMPORT_LOCK_OWNER = "ecm:lockOwner";
082
083    /**
084     * Lock creation time as a Calendar object.
085     *
086     * @since 5.4.2
087     */
088    String IMPORT_LOCK_CREATED = "ecm:lockCreated";
089
090    String IMPORT_CHECKED_IN = "ecm:isCheckedIn";
091
092    String IMPORT_BASE_VERSION_ID = "ecm:baseVersionId";
093
094    /** The document type to use to create a proxy by import. */
095    String IMPORT_PROXY_TYPE = "ecm:proxy";
096
097    /**
098     * Allow version write, Boolean parameter passed in context data at saveDocument time.
099     *
100     * @since 5.9.2
101     */
102    String ALLOW_VERSION_WRITE = "allowVersionWrite";
103
104    /**
105     * Closes this session.
106     *
107     * @since 5.9.3
108     */
109    @Override
110    void close();
111
112    /**
113     * Destroys any system resources held by this instance.
114     * <p>
115     * Called when the instance is no more needed.
116     */
117    void destroy();
118
119    /**
120     * Gets the document type object given its type name.
121     *
122     * @param type the document type name
123     * @return the type the doc type object
124     */
125    DocumentType getDocumentType(String type);
126
127    /**
128     * NOT PUBLIC, DO NOT CALL.
129     * <p>
130     * Connects the CoreSession to a low-level Session.
131     *
132     * @param repositoryName the repository name
133     * @param principal the principal
134     */
135    void connect(String repositoryName, NuxeoPrincipal principal);
136
137    /**
138     * Returns true if the session is currently connected to the repository.
139     */
140    boolean isLive(boolean onThread);
141
142    /**
143     * Cancels any pending change made through this session.
144     */
145    void cancel();
146
147    /**
148     * Saves any pending changes done until now through this session.
149     */
150    void save();
151
152    /**
153     * Gets the current session id.
154     * <p>
155     * If the client is not connected returns null.
156     *
157     * @return the session id or null if not connected
158     */
159    String getSessionId();
160
161    /**
162     * Returns {@code true} if all sessions in the current thread share the same state.
163     */
164    boolean isStateSharedByAllThreadSessions();
165
166    /**
167     * Gets the principal that created the client session.
168     *
169     * @return the principal
170     */
171    Principal getPrincipal();
172
173    /**
174     * Checks if the principal that created the client session has the given privilege on the referred document.
175     */
176    boolean hasPermission(DocumentRef docRef, String permission);
177
178    /**
179     * Checks if a given principal has the given privilege on the referred document.
180     */
181    boolean hasPermission(Principal principal, DocumentRef docRef, String permission);
182
183    /**
184     * Gets the root document of this repository.
185     *
186     * @return the root document. cannot be null
187     */
188    DocumentModel getRootDocument();
189
190    /**
191     * Gets a document model given its reference.
192     * <p>
193     * The default schemas are used to populate the returned document model. Default schemas are configured via the
194     * document type manager.
195     * <p>
196     * Any other data model not part of the default schemas will be lazily loaded as needed.
197     *
198     * @param docRef the document reference
199     * @return the document
200     * @throws DocumentNotFoundException if the document cannot be found
201     */
202    DocumentModel getDocument(DocumentRef docRef) throws DocumentNotFoundException;
203
204    /**
205     * Gets a list of documents given their references.
206     * <p>
207     * Documents that are not accessible are skipped.
208     *
209     * @throws DocumentNotFoundException if a document cannot be found
210     */
211    DocumentModelList getDocuments(DocumentRef[] docRefs) throws DocumentNotFoundException;
212
213    /**
214     * Gets a child document given its name and the parent reference.
215     * <p>
216     * Throws an exception if the document could not be found.
217     * <p>
218     * If the supplied id is null, returns the default child of the document if any, otherwise raises an exception.
219     * <p>
220     * If the parent is null or its path is null, then root is considered.
221     *
222     * @param parent the reference to the parent document
223     * @param name the name of the child document to retrieve
224     * @return the named child if exists
225     * @throws DocumentNotFoundException if there is no child with the given name
226     */
227    DocumentModel getChild(DocumentRef parent, String name);
228
229    /**
230     * Tests if the document has a child with the given name.
231     * <p>
232     * This operation silently ignores non-folder documents: If the document is not a folder then returns false.
233     *
234     * @param parent the document
235     * @param name the child name
236     * @return {@code true} if the document has a child with the given name
237     * @since 7.3
238     */
239    boolean hasChild(DocumentRef parent, String name);
240
241    /**
242     * Gets the children of the given parent.
243     *
244     * @param parent the parent reference
245     * @return the children if any, an empty list if no children or null if the specified parent document is not a
246     *         folder
247     */
248    DocumentModelList getChildren(DocumentRef parent);
249
250    /**
251     * Gets an iterator to the children of the given parent.
252     *
253     * @param parent the parent reference
254     * @return iterator over the children collection or null if the specified parent document is not a folder
255     */
256    DocumentModelIterator getChildrenIterator(DocumentRef parent);
257
258    /**
259     * Gets the children of the given parent filtered according to the given document type.
260     *
261     * @param parent the parent reference
262     * @param type the wanted document type
263     * @return the documents if any, an empty list if none were found or null if the parent document is not a folder
264     */
265    DocumentModelList getChildren(DocumentRef parent, String type);
266
267    /**
268     * Gets an iterator to the children of the given parent filtered according to the given document type.
269     */
270    DocumentModelIterator getChildrenIterator(DocumentRef parent, String type);
271
272    /**
273     * Gets the children of the given parent filtered according to the given document type and permission.
274     *
275     * @param parent the parent reference
276     * @param type the wanted document type
277     * @param perm the permission the user must have
278     * @return the documents if any, an empty list if none were found or null if the parent document is not a folder
279     */
280    DocumentModelList getChildren(DocumentRef parent, String type, String perm);
281
282    /**
283     * Same as {@link #getChildren(DocumentRef, String, String)} but the result is filtered and then sorted using the
284     * specified filter and sorter.
285     *
286     * @param parent the parent reference
287     * @param type the wanted type
288     * @param perm permission to check for. If null, defaults to READ
289     * @param filter the filter to use if any, null otherwise
290     * @param sorter the sorter to use if any, null otherwise
291     * @return the list of the children or an empty list if no children were found or null if the given parent is not a
292     *         folder
293     */
294    DocumentModelList getChildren(DocumentRef parent, String type, String perm, Filter filter, Sorter sorter);
295
296    /**
297     * Gets the references of the children. No permission is checked if perm is null.
298     *
299     * @param parentRef the parent reference
300     * @param perm the permission to check on the children (usually READ); if null, <b>no permission is checked</b>
301     * @return a list of children references
302     * @since 1.4.1
303     */
304    List<DocumentRef> getChildrenRefs(DocumentRef parentRef, String perm);
305
306    /**
307     * Gets the children of the given parent filtered according to the given document type and permission. Long result
308     * sets are loaded frame by frame transparently by the DocumentModelIterator.
309     */
310    DocumentModelIterator getChildrenIterator(DocumentRef parent, String type, String perm, Filter filter);
311
312    /**
313     * Same as {@link #getChildren(DocumentRef, String, String, Filter, Sorter)} without specific permission filtering.
314     *
315     * @param parent the parent reference
316     * @param type the wanted type
317     * @param filter the filter to use if any, null otherwise
318     * @param sorter the sorter to use if any, null otherwise
319     * @return the list of the children or an empty list if no children were found or null if the given parent is not a
320     *         folder
321     */
322    DocumentModelList getChildren(DocumentRef parent, String type, Filter filter, Sorter sorter);
323
324    /**
325     * Same as {@link CoreSession#getChildren(DocumentRef)} but returns only folder documents.
326     *
327     * @param parent the parent ref
328     * @return a list of children if any, an empty one if none or null if the given parent is not a folder
329     */
330    DocumentModelList getFolders(DocumentRef parent);
331
332    /**
333     * Same as {@link CoreSession#getFolders(DocumentRef)} but uses an optional filter and sorter on the result.
334     *
335     * @param parent the parent reference
336     * @param filter the filter to use or null if none
337     * @param sorter the sorter to use or null if none
338     * @return a list of children if any, an empty one if none or null if the given parent is not a folder
339     */
340    DocumentModelList getFolders(DocumentRef parent, Filter filter, Sorter sorter);
341
342    /**
343     * Same as {@link CoreSession#getChildren(DocumentRef)} but returns only non-folder documents.
344     *
345     * @param parent the parent reference
346     * @return a list of children if any, an empty one if none or null if the given parent is not a folder
347     */
348    DocumentModelList getFiles(DocumentRef parent);
349
350    /**
351     * Same as {@link #getFiles} but uses an optional filter and sorter on the result.
352     *
353     * @param parent the parent reference
354     * @param filter the filter to use or null if none
355     * @param sorter the sorter to use or null if none
356     * @return a list of children if any, an empty one if none or null if the given parent is not a folder
357     */
358    DocumentModelList getFiles(DocumentRef parent, Filter filter, Sorter sorter);
359
360    /**
361     * Returns the parent ref of the document referenced by {@code docRef} or {@code null} if this is the root document.
362     * <p>
363     * This method does not check the permissions on the parent document of this {@code CoreSession}'s {@code Principal}.
364     *
365     * @since 5.4.2
366     */
367    DocumentRef getParentDocumentRef(DocumentRef docRef);
368
369    /**
370     * Gets the parent document or null if this is the root document.
371     *
372     * @return the parent document or null if this is the root document
373     */
374    DocumentModel getParentDocument(DocumentRef docRef);
375
376    /**
377     * Gets the parent documents in path from the root to the given document or empty list if this is the root document.
378     * <p>
379     * Documents the principal is is not allowed to browse are filtered out the parents list.
380     *
381     * @return the list with parent documents or empty list if this is the root document
382     */
383    List<DocumentModel> getParentDocuments(DocumentRef docRef);
384
385    /**
386     * Tests if the document pointed by the given reference exists and is accessible.
387     * <p>
388     * This operation makes no difference between non-existence and permission problems.
389     * <p>
390     * If the parent is null or its path is null, then root is considered.
391     *
392     * @param docRef the reference to the document to test for existence
393     * @return true if the referenced document exists, false otherwise
394     */
395    boolean exists(DocumentRef docRef);
396
397    /**
398     * Tests if the document has any children.
399     * <p>
400     * This operation silently ignores non-folder documents: If the document is not a folder then returns false.
401     * <p>
402     * If the parent is null or its path is null, then root is considered.
403     *
404     * @param docRef the reference to the document to test
405     * @return true if document has children, false otherwise
406     */
407    boolean hasChildren(DocumentRef docRef);
408
409    /**
410     * Creates a document model using type name.
411     * <p>
412     * Used to fetch initial datamodels from the type definition.
413     * <p>
414     * DocumentModel creation notifies a {@link DocumentEventTypes#EMPTY_DOCUMENTMODEL_CREATED} so that core event
415     * listener can initialize its content with computed properties.
416     *
417     * @return the initial document model
418     */
419    DocumentModel createDocumentModel(String typeName);
420
421    /**
422     * Creates a document model using required information.
423     * <p>
424     * Used to fetch initial datamodels from the type definition.
425     * <p>
426     * DocumentModel creation notifies a {@link DocumentEventTypes#EMPTY_DOCUMENTMODEL_CREATED} so that core event
427     * listener can initialize its content with computed properties.
428     *
429     * @param parentPath the parent path
430     * @param name The destination name
431     * @param typeName the type name
432     * @return the initial document model
433     */
434    DocumentModel createDocumentModel(String parentPath, String name, String typeName);
435
436    /**
437     * Creates a document model using required information.
438     * <p>
439     * Used to fetch initial datamodels from the type definition.
440     * <p>
441     * DocumentModel creation notifies a {@link DocumentEventTypes#EMPTY_DOCUMENTMODEL_CREATED} so that core event
442     * listener can initialize its content with computed properties.
443     *
444     * @param typeName the type name
445     * @param options additional contextual data provided to core event listeners
446     * @return the initial document model
447     */
448    DocumentModel createDocumentModel(String typeName, Map<String, Object> options);
449
450    /**
451     * Creates a document using given document model for initialization.
452     * <p>
453     * The model contains path of the new document, its type and optionally the initial data models of the document.
454     * <p>
455     *
456     * @param model the document model to use for initialization
457     * @return the created document
458     */
459    DocumentModel createDocument(DocumentModel model);
460
461    /**
462     * Bulk creation of documents.
463     *
464     * @param docModels the document models to use for intialization
465     * @return the created documents
466     */
467    DocumentModel[] createDocument(DocumentModel[] docModels);
468
469    /**
470     * Low-level import of documents, reserved for the administrator.
471     * <p>
472     * This method is used to import documents with given ids, or directly import versions and proxies.
473     * <p>
474     * The id, parent, name and typeName must be present in each docModel.
475     * <p>
476     * The context data needs to be filled with values depending on the type of the document:
477     * <p>
478     * For a proxy (type = {@code "ecm:proxyType"}): {@link #IMPORT_PROXY_TARGET_ID} and
479     * {@link #IMPORT_PROXY_VERSIONABLE_ID}.
480     * <p>
481     * For a version (no parent): {@link #IMPORT_VERSION_VERSIONABLE_ID}, {@link #IMPORT_VERSION_CREATED},
482     * {@link #IMPORT_VERSION_LABEL} and {@link #IMPORT_VERSION_DESCRIPTION}.
483     * <p>
484     * For a live document: {@link #IMPORT_BASE_VERSION_ID} and {@link #IMPORT_CHECKED_IN} (Boolean).
485     * <p>
486     * For a live document or a version: {@link #IMPORT_LIFECYCLE_POLICY} , {@link #IMPORT_LIFECYCLE_STATE},
487     * {@link #IMPORT_VERSION_MAJOR} (Long) and {@link #IMPORT_VERSION_MINOR} (Long).
488     *
489     * @param docModels the documents to create
490     */
491    void importDocuments(List<DocumentModel> docModels);
492
493    /**
494     * Saves changes done on the given document model.
495     *
496     * @param docModel the document model that needs modified
497     */
498    DocumentModel saveDocument(DocumentModel docModel);
499
500    /**
501     * Bulk document saving.
502     *
503     * @param docModels the document models that needs to be saved
504     */
505    void saveDocuments(DocumentModel[] docModels);
506
507    /**
508     * Check if a document can be removed. This needs the REMOVE permission on the document and the REMOVE_CHILDREN
509     * permission on the parent.
510     * <p>
511     * For an archived version to be removeable, it must not be referenced from any proxy or be the base of a working
512     * document, and the REMOVE permission must be available on the working document (or the user must be an
513     * administrator if no working document exists).
514     *
515     * @param docRef the document
516     * @return true if the document can be removed
517     */
518    boolean canRemoveDocument(DocumentRef docRef);
519
520    /**
521     * Removes this document and all its children, if any.
522     *
523     * @param docRef the reference to the document to remove
524     */
525    void removeDocument(DocumentRef docRef);
526
527    /**
528     * Bulk method to remove documents.
529     * <p>
530     * This method is safe with respect to orderings: it doesn't fail if an ancestor of a document occurs before the
531     * document.
532     * </p>
533     *
534     * @param docRefs the refs to the document to remove
535     */
536    void removeDocuments(DocumentRef[] docRefs);
537
538    /**
539     * Removes all children from the given document.
540     *
541     * @param docRef the reference to the document to remove
542     */
543    void removeChildren(DocumentRef docRef);
544
545    /**
546     * Copies the source document to the destination folder under the given name. If the name is null the original name
547     * is preserved.
548     * <p>
549     * If the destination document is not a folder or it doesn't exists then throws an exception.
550     * <p>
551     * If the source is a proxy the destination will be a copy of the proxy.
552     *
553     * @param src the source document reference
554     * @param dst the destination folder reference
555     * @param name the new name of the file or null if the original name must be preserved
556     * @deprecated Since 8.2. Use {@link #copy(DocumentRef, DocumentRef, String, CopyOption...)} instead
557     */
558    @Deprecated
559    DocumentModel copy(DocumentRef src, DocumentRef dst, String name);
560
561    /**
562     * Copies the source document to the destination folder under the given name. If the name is null the original name
563     * is preserved.
564     * <p>
565     * If the destination document is not a folder or it doesn't exists then throws an exception.
566     * <p>
567     * If the source is a proxy the destination will be a copy of the proxy.
568     *
569     * @param src the source document reference
570     * @param dst the destination folder reference
571     * @param name the new name of the file or null if the original name must be preserved
572     * @param copyOptions the options for copy
573     */
574    DocumentModel copy(DocumentRef src, DocumentRef dst, String name, CopyOption... copyOptions);
575
576    /**
577     * Copies the source document to the destination folder under the given name. If the name is null the original name
578     * is preserved.
579     * <p>
580     * If the destination document is not a folder or it doesn't exists then throws an exception.
581     * <p>
582     * If the source is a proxy the destination will be a copy of the proxy.
583     *
584     * @param src the source document reference
585     * @param dst the destination folder reference
586     * @param name the new name of the file or null if the original name must be preserved
587     * @param resetLifeCycle the property that flagged whether reset destination document lifecycle or not
588     * @since 5.7
589     * @deprecated Since 8.2. Use {@link #copy(DocumentRef, DocumentRef, String, CopyOption...)} instead
590     */
591    @Deprecated
592    DocumentModel copy(DocumentRef src, DocumentRef dst, String name, boolean resetLifeCycle);
593
594    /**
595     * Bulk copy. Destination must be a folder document.
596     *
597     * @param src the documents to copy
598     * @param dst the destination folder
599     * @deprecated Since 8.2. Use {@link #copy(List, DocumentRef, CopyOption...)}
600     */
601    @Deprecated
602    List<DocumentModel> copy(List<DocumentRef> src, DocumentRef dst);
603
604    /**
605     * Bulk copy. Destination must be a folder document.
606     *
607     * @param src the documents to copy
608     * @param dst the destination folder
609     * @param copyOptions the options for copy
610     * @since 8.2
611     */
612    List<DocumentModel> copy(List<DocumentRef> src, DocumentRef dst, CopyOption... copyOptions);
613
614    /**
615     * Bulk copy. Destination must be a folder document.
616     *
617     * @param src the documents to copy
618     * @param dst the destination folder
619     * @param resetLifeCycle the property that flagged whether reset destination document lifecycle or not
620     * @since 5.7
621     * @deprecated Since 8.2. Use {@link #copy(List, DocumentRef, CopyOption...)} instead
622     */
623    @Deprecated
624    List<DocumentModel> copy(List<DocumentRef> src, DocumentRef dst, boolean resetLifeCycle);
625
626    /**
627     * Work like copy but in the case of a source proxy the destination will be a new document instead of a proxy.
628     *
629     * @see CoreSession#copy(DocumentRef, DocumentRef, String, CopyOption...)
630     * @param src the source document reference
631     * @param dst the destination folder reference
632     * @param name the new name of the file or null if the original name must be preserved
633     * @deprecated Since 8.2. Use {@link #copyProxyAsDocument(DocumentRef, DocumentRef, String, CopyOption...)} instead
634     */
635    @Deprecated
636    DocumentModel copyProxyAsDocument(DocumentRef src, DocumentRef dst, String name);
637
638    /**
639     * Work like copy but in the case of a source proxy the destination will be a new document instead of a proxy.
640     *
641     * @see CoreSession#copy(DocumentRef, DocumentRef, String, CopyOption...)
642     * @param src the source document reference
643     * @param dst the destination folder reference
644     * @param name the new name of the file or null if the original name must be preserved
645     * @param copyOptions the options for copy
646     * @since 8.2
647     */
648    DocumentModel copyProxyAsDocument(DocumentRef src, DocumentRef dst, String name, CopyOption... copyOptions);
649
650    /**
651     * Work like copy but in the case of a source proxy the destination will be a new document instead of a proxy.
652     *
653     * @param src the source document reference
654     * @param dst the destination folder reference
655     * @param name the new name of the file or null if the original name must be preserved
656     * @param resetLifeCycle the property that flagged whether reset destination document lifecycle or not
657     * @since 5.7
658     * @deprecated Since 8.2. Use {@link #copyProxyAsDocument(DocumentRef, DocumentRef, String, CopyOption...)} instead
659     */
660    @Deprecated
661    DocumentModel copyProxyAsDocument(DocumentRef src, DocumentRef dst, String name, boolean resetLifeCycle);
662
663    /**
664     * Bulk copyProxyAsDocument. Destination must be a folder document.
665     *
666     * @param src the documents to copy
667     * @param dst the destination folder
668     * @deprecated Since 8.2. Use {@link #copyProxyAsDocument(List, DocumentRef, CopyOption...)} instead
669     */
670    @Deprecated
671    List<DocumentModel> copyProxyAsDocument(List<DocumentRef> src, DocumentRef dst);
672
673    /**
674     * Bulk copyProxyAsDocument. Destination must be a folder document.
675     *
676     * @param src the documents to copy
677     * @param dst the destination folder
678     * @param copyOptions the options of copy
679     * @since 8.2
680     */
681    List<DocumentModel> copyProxyAsDocument(List<DocumentRef> src, DocumentRef dst, CopyOption... copyOptions);
682
683    /**
684     * Bulk copyProxyAsDocument. Destination must be a folder document.
685     *
686     * @param src the documents to copy
687     * @param dst the destination folder
688     * @param resetLifeCycle the property that flagged whether reset destination document lifecycle or not
689     * @since 5.7
690     * @deprecated Since 8.2. Use {@link #copyProxyAsDocument(List, DocumentRef, CopyOption...)} instead
691     */
692    @Deprecated
693    List<DocumentModel> copyProxyAsDocument(List<DocumentRef> src, DocumentRef dst, boolean resetLifeCycle);
694
695    /**
696     * Moves the source document to the destination folder under the given name. If the name is {@code null} or if there
697     * is a collision, a suitable new name is found.
698     * <p>
699     * If the destination document is not a folder or it doesn't exists then throws an exception.
700     *
701     * @param src the source document reference
702     * @param dst the destination folder reference
703     * @param name the new name of the file, or {@code null}
704     */
705    DocumentModel move(DocumentRef src, DocumentRef dst, String name);
706
707    /**
708     * Bulk move. Destination must be a folder document.
709     *
710     * @param src the documents to move
711     * @param dst the destination folder
712     */
713    void move(List<DocumentRef> src, DocumentRef dst);
714
715    /**
716     * Gets the document access control policy.
717     * <p>
718     * The returned ACP is the ACP defined on that document if any + the inherited ACL if any. If neither a local ACP
719     * nor inherited ACL exists null is returned.
720     * <p>
721     * Note that modifying the returned ACP will not affect in any way the stored document ACP. To modify the ACP you
722     * must explicitely set it by calling {@link CoreSession#setACP(DocumentRef, ACP, boolean)}
723     * <p>
724     * This method will always fetch a fresh ACP from the storage. The recommended way to get the ACP is to use
725     * {@link DocumentModel#getACP()} this way the ACP will be cached at the document model level and so you can use it
726     * for multiple permission checks without fetching it each time.
727     *
728     * @param docRef the doc ref to retrieve ACP or null if none
729     * @return the ACP
730     */
731    ACP getACP(DocumentRef docRef);
732
733    /**
734     * Sets the ACP for this document.
735     * <p>
736     * If the ACP contains an <code>INHERITED</code> ACL it will be discarded. Only ACLs relative to the current
737     * document may be changed.
738     * <p>
739     * If the <code>overwrite</code> argument is false, the ACP is merged with the existing one if any. The merge is
740     * done as follow:
741     * <ul>
742     * <li>If any ACL is that already exists on the document ACp is redefined by the new ACO then it will be replaced by
743     * the new one. So if you want to remove an ACl in this mode you need to specify an empty ACL.
744     * <li>If the new ACP contains an ACl that is not defined by the old one the it will be added to the merged ACP.
745     * <li>If the <code>owners</code> are specified then they will replace the existing ones if any. Otherwise the old
746     * owners are preserved if any. As for the ACL if you want to remove existing owners you need to specify an empty
747     * owner array (and not a null one)
748     * </ul>
749     * If the <code>overwrite</code> argument is true, the old ACP will be replaced by the new one.
750     * <p>
751     * This way if you can remove the existing ACP by specifying a null ACP and <code>overwrite</code> argument set to
752     * true.
753     * <p>
754     * Setting a null ACP when <code>overwrite</code> is false will do nothing.
755     */
756    void setACP(DocumentRef docRef, ACP acp, boolean overwrite);
757
758    /**
759     * Replace the {@code oldACE} with the {@code newACE} on the given {@code aclName}.
760     * <p>
761     *
762     * @since 7.4
763     */
764    void replaceACE(DocumentRef docRef, String aclName, ACE oldACE, ACE newACE);
765
766    /**
767     * Returns {@code true} if negative ACLs are allowed.
768     * <p>
769     * Negative ACLs are ACLs that include an ACE with a deny (isGranted=false). This does not include the full-blocking
770     * ACE for Everyone/Everything, which is always allowed.
771     *
772     * @return {@code true} if negative ACLs are allowed
773     * @since 6.0
774     */
775    boolean isNegativeAclAllowed();
776
777    /*
778     * Support for lazy loading
779     */
780
781    /**
782     * Retrieves a data model given a document reference and a schema.
783     * <p>
784     * For INTERNAL use by the core.
785     *
786     * @since 5.4.2
787     */
788    DataModel getDataModel(DocumentRef docRef, Schema schema);
789
790    // -------- Versioning API ---------------
791
792    /**
793     * Gets the last version of a document.
794     *
795     * @param docRef the reference to the document
796     * @return the version
797     * @deprecated use {@link #getLastDocumentVersion} instead
798     */
799    @Deprecated
800    VersionModel getLastVersion(DocumentRef docRef);
801
802    /**
803     * Gets the document corresponding to the last version for the given document.
804     *
805     * @param docRef the reference to the document
806     * @return the document model corresponding to the version
807     */
808    DocumentModel getLastDocumentVersion(DocumentRef docRef);
809
810    /**
811     * Gets the document reference corresponding to the last version for the given document.
812     *
813     * @param docRef the reference to the document
814     * @return the document reference corresponding to the last version
815     */
816    DocumentRef getLastDocumentVersionRef(DocumentRef docRef);
817
818    /**
819     * Gets the head (live) document for this document.
820     *
821     * @param docRef the reference to the document
822     * @return the version
823     */
824    DocumentModel getSourceDocument(DocumentRef docRef);
825
826    /**
827     * Gets the references of the versions of the document.
828     *
829     * @param docRef the reference to the document
830     * @return a list of version references
831     * @since 1.4.1
832     */
833    List<DocumentRef> getVersionsRefs(DocumentRef docRef);
834
835    /**
836     * Retrieves all the versions for a specified document.
837     *
838     * @param docRef the reference to the document
839     * @return the list of {@link DocumentModel} representing versions, empty list if none is found.
840     */
841    List<DocumentModel> getVersions(DocumentRef docRef);
842
843    /**
844     * Retrieves all the versions for a specified document.
845     *
846     * @param docRef the reference to the document
847     * @return the list of {@link VersionModel} representing versions, empty list if none is found.
848     */
849    List<VersionModel> getVersionsForDocument(DocumentRef docRef);
850
851    /**
852     * Gets a document version, given the versionable id and label.
853     * <p>
854     * The version model contains the label of the version to look for. On return, it is filled with the version's
855     * description and creation date.
856     * <p>
857     * Restricted to administrators.
858     *
859     * @param versionableId the versionable id
860     * @param versionModel the version model holding the label
861     * @return the version, or {@code null} if not found
862     * @deprecated use version ids directly
863     */
864    @Deprecated
865    DocumentModel getVersion(String versionableId, VersionModel versionModel);
866
867    /**
868     * Gets the version label for a document, according to the versioning service.
869     *
870     * @param docModel the document
871     * @return the version label
872     */
873    String getVersionLabel(DocumentModel docModel);
874
875    /**
876     * Returns a document that represents the specified version of the document.
877     *
878     * @param docRef the reference to the document
879     * @param version the version for which we want the corresponding document
880     */
881    DocumentModel getDocumentWithVersion(DocumentRef docRef, VersionModel version);
882
883    /**
884     * Restores the given document to the specified version.
885     *
886     * @param docRef the reference to the document
887     * @param versionRef the reference to the version
888     * @param skipSnapshotCreation {@code true} if the document should not be snapshotted before being restored
889     * @param skipCheckout {@code true} if the restored document should be kept in a checked-in state
890     * @since 5.4
891     */
892    DocumentModel restoreToVersion(DocumentRef docRef, DocumentRef versionRef, boolean skipSnapshotCreation,
893            boolean skipCheckout);
894
895    /**
896     * Restores the given document to the specified version permitting to skip the creation of the snapshot for current
897     * document.
898     *
899     * @param docRef the reference to the document
900     * @param version the version to which the document should be restored to - only the label is used for the moment
901     * @param skipSnapshotCreation indicates if skipping snapshot creation
902     * @deprecated use {@link #restoreToVersion(DocumentRef, DocumentRef, boolean, boolean)} instead
903     */
904    @Deprecated
905    DocumentModel restoreToVersion(DocumentRef docRef, VersionModel version, boolean skipSnapshotCreation);
906
907    /**
908     * Restores the given document to the specified version.
909     *
910     * @param docRef the reference to the document
911     * @param versionRef the reference to the version
912     * @since 5.4
913     */
914    DocumentModel restoreToVersion(DocumentRef docRef, DocumentRef versionRef);
915
916    /**
917     * Restores the given document to the specified version.
918     *
919     * @param docRef the reference to the document
920     * @param version the version to which the document should be restored to - only the label is used for the moment
921     * @deprecated use {@link #restoreToVersion(DocumentRef, DocumentRef)} instead
922     */
923    @Deprecated
924    DocumentModel restoreToVersion(DocumentRef docRef, VersionModel version);
925
926    /**
927     * Gets the version to which a checked in document is linked.
928     * <p>
929     * Returns {@code null} for a checked out document or a version or a proxy.
930     *
931     * @return the version, or {@code null}
932     */
933    DocumentRef getBaseVersion(DocumentRef docRef);
934
935    /**
936     * Checks out a versioned document.
937     *
938     * @param docRef the reference to the document
939     */
940    void checkOut(DocumentRef docRef);
941
942    /**
943     * Checks in a modified document, creating a new version.
944     *
945     * @param docRef the reference to the document
946     * @param version the version descriptor
947     * @return the version document just created
948     * @deprecated use {@link #checkIn(DocumentRef, VersioningOption, String)} instead
949     */
950    @Deprecated
951    DocumentModel checkIn(DocumentRef docRef, VersionModel version);
952
953    /**
954     * Checks in a modified document, creating a new version.
955     *
956     * @param docRef the reference to the document
957     * @param option whether to do create a new {@link VersioningOption#MINOR} or {@link VersioningOption#MAJOR} version
958     *            during check in
959     * @param checkinComment the checkin comment
960     * @return the version just created
961     * @since 5.4
962     */
963    DocumentRef checkIn(DocumentRef docRef, VersioningOption option, String checkinComment);
964
965    /**
966     * Returns whether the current document is checked-out or not.
967     *
968     * @param docRef the reference to the document
969     */
970    boolean isCheckedOut(DocumentRef docRef);
971
972    /**
973     * Gets the version series id for a document.
974     * <p>
975     * All documents and versions derived by a check in or checkout from the same original document share the same
976     * version series id.
977     *
978     * @param docRef the document reference
979     * @return the version series id
980     * @since 5.4
981     */
982    String getVersionSeriesId(DocumentRef docRef);
983
984    /**
985     * Gets the working copy (live document) for a proxy or a version.
986     *
987     * @param docRef the document reference
988     * @return the working copy, or {@code null} if not found
989     * @since 5.4
990     */
991    DocumentModel getWorkingCopy(DocumentRef docRef);
992
993    /**
994     * Creates a generic proxy to the given document inside the given folder.
995     * <p>
996     * The document may be a version, or a working copy (live document) in which case the proxy will be a "shortcut".
997     *
998     * @since 1.6.1 (5.3.1)
999     */
1000    DocumentModel createProxy(DocumentRef docRef, DocumentRef folderRef);
1001
1002    /** -------------------------- Query API --------------------------- * */
1003
1004    /**
1005     * Executes the given NXQL query an returns the result.
1006     *
1007     * @param query the query to execute
1008     * @return the query result
1009     */
1010    DocumentModelList query(String query);
1011
1012    /**
1013     * Executes the given NXQL query an returns the result.
1014     *
1015     * @param query the query to execute
1016     * @param max number of document to retrieve
1017     * @return the query result
1018     */
1019    DocumentModelList query(String query, int max);
1020
1021    /**
1022     * Executes the given NXQL query and returns the result that matches the filter.
1023     *
1024     * @param query the query to execute
1025     * @param filter the filter to apply to result
1026     * @return the query result
1027     */
1028    DocumentModelList query(String query, Filter filter);
1029
1030    /**
1031     * Executes the given NXQL query and returns the result that matches the filter.
1032     *
1033     * @param query the query to execute
1034     * @param filter the filter to apply to result
1035     * @param max number of document to retrieve
1036     * @return the query result
1037     */
1038    DocumentModelList query(String query, Filter filter, int max);
1039
1040    /**
1041     * Executes the given NXQL query and returns the result that matches the filter.
1042     *
1043     * @param query the query to execute
1044     * @param filter the filter to apply to result
1045     * @param limit the maximum number of documents to retrieve, or 0 for all of them
1046     * @param offset the offset (starting at 0) into the list of documents
1047     * @param countTotal if {@code true}, return a {@link DocumentModelList} that includes a total size of the
1048     *            underlying list (size if there was no limit or offset)
1049     * @return the query result
1050     */
1051    DocumentModelList query(String query, Filter filter, long limit, long offset, boolean countTotal);
1052
1053    /**
1054     * Executes the given NXQL query and returns the result that matches the filter.
1055     *
1056     * @param query the query to execute
1057     * @param filter the filter to apply to result
1058     * @param limit the maximum number of documents to retrieve, or 0 for all of them
1059     * @param offset the offset (starting at 0) into the list of documents
1060     * @param countUpTo if {@code -1}, count the total size without offset/limit.<br>
1061     *            If {@code 0}, don't count the total size.<br>
1062     *            If {@code n}, count the total number if there are less than n documents otherwise set the size to
1063     *            {@code -1}.
1064     * @return the query result
1065     * @since 5.6
1066     */
1067    DocumentModelList query(String query, Filter filter, long limit, long offset, long countUpTo);
1068
1069    /**
1070     * Executes the given query and returns the result that matches the filter.
1071     *
1072     * @param query the query to execute
1073     * @param queryType the query type, like "NXQL"
1074     * @param filter the filter to apply to result
1075     * @param limit the maximum number of documents to retrieve, or 0 for all of them
1076     * @param offset the offset (starting at 0) into the list of documents
1077     * @param countTotal if {@code true}, return a {@link DocumentModelList} that includes a total size of the
1078     *            underlying list (size if there was no limit or offset)
1079     * @return the query result
1080     * @since 5.5
1081     */
1082    DocumentModelList query(String query, String queryType, Filter filter, long limit, long offset, boolean countTotal);
1083
1084    /**
1085     * Executes the given query and returns the result that matches the filter.
1086     *
1087     * @param query the query to execute
1088     * @param queryType the query type, like "NXQL"
1089     * @param filter the filter to apply to result
1090     * @param limit the maximum number of documents to retrieve, or 0 for all of them
1091     * @param offset the offset (starting at 0) into the list of documents
1092     * @param countUpTo if {@code -1}, return a {@link DocumentModelList} that includes a total size of the underlying
1093     *            list (size if there was no limit or offset). <br>
1094     *            If {@code 0}, don't return the total size of the underlying list. <br>
1095     *            If {@code n}, return the total size of the underlying list when the size is smaller than {@code n}
1096     *            else return a total size of {@code -1}.
1097     * @return the query result
1098     * @since 5.6
1099     */
1100    DocumentModelList query(String query, String queryType, Filter filter, long limit, long offset, long countUpTo);
1101
1102    /**
1103     * Executes the given query and returns an iterable of maps containing the requested properties (which must be
1104     * closed when done).
1105     *
1106     * @param query the query to execute
1107     * @param queryType the query type, usually "NXQL"
1108     * @param params optional query-type-dependent parameters
1109     * @return an {@link IterableQueryResult}, which <b>must</b> be closed after use
1110     */
1111    IterableQueryResult queryAndFetch(String query, String queryType, Object... params);
1112
1113    /**
1114     * Executes the given query and returns an iterable of maps containing the requested properties (which must be
1115     * closed when done).
1116     * <p>
1117     * It's possible to specify {@code distinctDocuments = true} to get a maximum of one row of results per document,
1118     * this will behave differently only when the {@code WHERE} clause contains wildcards.
1119     *
1120     * @param query the query to execute
1121     * @param queryType the query type, usually "NXQL"
1122     * @param distinctDocuments if {@code true} then a maximum of one row per document will be returned
1123     * @param params optional query-type-dependent parameters
1124     * @return an {@link IterableQueryResult}, which <b>must</b> be closed after use
1125     * @since 7.10-HF04, 8.2
1126     */
1127    IterableQueryResult queryAndFetch(String query, String queryType, boolean distinctDocuments, Object... params);
1128
1129    /** -------------------------- Security API --------------------------- * */
1130
1131    /**
1132     * Retrieves the available security permissions existing in the system.
1133     * <p>
1134     *
1135     * @return a raw list of permission names, either basic or group names
1136     */
1137    // TODO: (Hardcoded at the moment. In the future wil get data from
1138    // LDAP/database.)
1139    List<String> getAvailableSecurityPermissions();
1140
1141    /**
1142     * Returns the life cycle of the document.
1143     *
1144     * @see org.nuxeo.ecm.core.lifecycle
1145     * @param docRef the document reference
1146     * @return the life cycle as a string
1147     */
1148    String getCurrentLifeCycleState(DocumentRef docRef);
1149
1150    /**
1151     * Returns the life cycle policy of the document.
1152     *
1153     * @see org.nuxeo.ecm.core.lifecycle
1154     * @param docRef the document reference
1155     * @return the life cycle policy
1156     */
1157    String getLifeCyclePolicy(DocumentRef docRef);
1158
1159    /**
1160     * Follows a given life cycle transition.
1161     * <p>
1162     * This will update the current life cycle of the document.
1163     *
1164     * @param docRef the document reference
1165     * @param transition the name of the transition to follow
1166     * @return a boolean representing the status if the operation
1167     * @throws LifeCycleException if the transition cannot be followed
1168     */
1169    boolean followTransition(DocumentRef docRef, String transition) throws LifeCycleException;
1170
1171    /**
1172     * Follows a given life cycle transition.
1173     * <p>
1174     * This will update the current life cycle of the document.
1175     *
1176     * @param doc the document model
1177     * @param transition the name of the transition to follow
1178     * @return a boolean representing the status if the operation
1179     * @throws LifeCycleException if the transition cannot be followed
1180     */
1181    boolean followTransition(DocumentModel doc, String transition) throws LifeCycleException;
1182
1183    /**
1184     * Gets the allowed state transitions for this document.
1185     *
1186     * @param docRef the document reference
1187     * @return a collection of state transitions as string
1188     */
1189    Collection<String> getAllowedStateTransitions(DocumentRef docRef);
1190
1191    /**
1192     * Reinitializes the life cycle state of the document to its default state.
1193     *
1194     * @param docRef the document
1195     * @since 5.4.2
1196     */
1197    void reinitLifeCycleState(DocumentRef docRef);
1198
1199    /**
1200     * Retrieves the given field value from the given schema for all the given documents.
1201     *
1202     * @param docRefs the document references
1203     * @param schema the schema
1204     * @param field the field name
1205     * @return the field values in the same order as the given docRefs
1206     */
1207    Object[] getDataModelsField(DocumentRef[] docRefs, String schema, String field);
1208
1209    /**
1210     * Creates an array with all parent refs starting from the given document up to the root. So the return value will
1211     * have [0] = parent ref; [1] = parent parent ref... etc.
1212     *
1213     * @return an array with ancestor documents ref
1214     */
1215    DocumentRef[] getParentDocumentRefs(DocumentRef docRef);
1216
1217    /**
1218     * Retrieves the given field value from the given schema for the given document along with all its parent documents.
1219     *
1220     * @param docRef the document reference
1221     * @param schema the schema
1222     * @param field the field name
1223     * @return an array with field values of all documents on the path from the given document to the root
1224     */
1225    Object[] getDataModelsFieldUp(DocumentRef docRef, String schema, String field);
1226
1227    /**
1228     * Gets the lock key on the given document if a lock exists or null otherwise.
1229     * <p>
1230     * A lock key has the form {@code someuser:Nov 29, 2010}.
1231     *
1232     * @param doc the document reference
1233     * @return the lock key if the document is locked, null otherwise
1234     * @deprecated since 5.4.2, use {@link #getLockInfo} instead
1235     */
1236    @Deprecated
1237    String getLock(DocumentRef doc);
1238
1239    /**
1240     * Sets a lock on the given document using the given key.
1241     * <p>
1242     * A lock key must have the form {@code someuser:Nov 29, 2010}.
1243     *
1244     * @param doc the document reference
1245     * @param key the lock key
1246     * @throws LockException if the document is already locked
1247     * @deprecated since 5.4.2, use {@link #setLock(DocumentRef)} instead
1248     */
1249    @Deprecated
1250    void setLock(DocumentRef doc, String key) throws LockException;
1251
1252    /**
1253     * Removes the lock if one exists.
1254     * <p>
1255     * The caller principal should be the same as the one who set the lock or to belongs to the administrator group,
1256     * otherwise an exception will be throw.
1257     * <p>
1258     * If the document was not locked, does nothing.
1259     *
1260     * @param docRef the document to unlock
1261     * @return the lock key that was removed
1262     * @deprecated since 5.4.2, use {@link #removeLock} instead
1263     */
1264    @Deprecated
1265    String unlock(DocumentRef docRef);
1266
1267    /**
1268     * Sets a lock on the given document.
1269     *
1270     * @param docRef the document reference
1271     * @return the lock info that was set
1272     * @throws LockException if the document is already locked
1273     * @since 5.4.2
1274     */
1275    Lock setLock(DocumentRef docRef) throws LockException;
1276
1277    /**
1278     * Gets the lock info on the given document.
1279     * <p>
1280     * Lock info is never cached, and needs to use a separate transaction in a separate thread, so care should be taken
1281     * to not call this method needlessly.
1282     *
1283     * @param docRef the document reference
1284     * @return the lock info if the document is locked, or {@code null} otherwise
1285     * @since 5.4.2
1286     */
1287    Lock getLockInfo(DocumentRef docRef);
1288
1289    /**
1290     * Removes the lock on the given document.
1291     * <p>
1292     * The caller principal should be the same as the one who set the lock or to belongs to the administrator group,
1293     * otherwise an exception will be throw.
1294     * <p>
1295     * If the document was not locked, does nothing.
1296     * <p>
1297     * Returns the previous lock info.
1298     *
1299     * @param docRef the document to unlock
1300     * @return the removed lock info, or {@code null} if there was no lock
1301     * @since 5.4.2
1302     * @throws LockException if the document is locked by someone else
1303     */
1304    Lock removeLock(DocumentRef docRef) throws LockException;
1305
1306    /**
1307     * Applies default Read permissions on root JCR Document for the given user or group name. It can only be called by
1308     * Administrators.
1309     * <p>
1310     * Usage: As an administrator, you may want to add new users or groups. This method needs to be called to grand
1311     * default reading permissions on the root document of the repository for the newly created users/groups.
1312     */
1313    void applyDefaultPermissions(String userOrGroupName);
1314
1315    /**
1316     * Checks if the given document is dirty.
1317     *
1318     * @param doc the doc reference
1319     * @return true if dirty false otherwise
1320     * @deprecated since 5.4, use {@link #isCheckedOut} instead
1321     */
1322    @Deprecated
1323    boolean isDirty(DocumentRef doc);
1324
1325    /**
1326     * Publishes the document in a section overwriting any existing proxy to the same document. This is simmilar to
1327     * publishDocument(docToPublish, section, true);
1328     *
1329     * @return The proxy document that was created
1330     * @since 1.4.1 for the case where docToPublish is a proxy
1331     */
1332    DocumentModel publishDocument(DocumentModel docToPublish, DocumentModel section);
1333
1334    /**
1335     * Publishes the document in a section.
1336     *
1337     * @return The proxy document that was created
1338     */
1339    DocumentModel publishDocument(DocumentModel docToPublish, DocumentModel section, boolean overwriteExistingProxy);
1340
1341    /**
1342     * Finds the proxies for a document. If the parent is not null, the search will be limited to its direct children.
1343     * <p>
1344     * If the document is a version, then only proxies to that version will be looked up.
1345     * <p>
1346     * If the document is a proxy, then all similar proxies (pointing to any version of the same versionable) are
1347     * retrieved.
1348     *
1349     * @param docRef the target document for the proxies
1350     * @param folderRef the folder where proxies are located or {@code null}
1351     * @return the list of the proxies. An empty list is returned if no proxy are found
1352     * @since 1.4.1 for the case where docRef is a proxy
1353     */
1354    DocumentModelList getProxies(DocumentRef docRef, DocumentRef folderRef);
1355
1356    /**
1357     * Gets all proxy versions to document docRef inside folder folderRef.
1358     * <p>
1359     * Intended to be used by UI clients to display information about proxies in sections.
1360     *
1361     * @param docRef the target document for the proxies
1362     * @param folderRef the folder where proxies are located
1363     * @return an array of the proxy versions, with an empty string being used for a live proxy. {@code null} is
1364     *         returned if no proxies are found the specified folder
1365     * @deprecated since 5.4, use {@link #getProxies} instead
1366     */
1367    @Deprecated
1368    String[] getProxyVersions(DocumentRef docRef, DocumentRef folderRef);
1369
1370    /**
1371     * Returns the type of his parent SuperSpace (workspace, section, etc.). SuperSpace is qualified by the SuperSpace
1372     * facet.
1373     */
1374    String getSuperParentType(DocumentModel doc);
1375
1376    /**
1377     * Returns the parent SuperSpace (workspace, section, etc.). SuperSpace is qualified by the SuperSpace facet.
1378     *
1379     * @return DocumentModel of SuperSpace
1380     */
1381    DocumentModel getSuperSpace(DocumentModel doc);
1382
1383    /**
1384     * Returns the repository name against which this core session is bound.
1385     *
1386     * @return the repository name used currently used as an identifier
1387     */
1388    String getRepositoryName();
1389
1390    /**
1391     * Gets system property of the specified type for the document ref.
1392     */
1393    <T extends Serializable> T getDocumentSystemProp(DocumentRef ref, String systemProperty, Class<T> type);
1394
1395    /**
1396     * Sets given value as a system property.
1397     */
1398    <T extends Serializable> void setDocumentSystemProp(DocumentRef ref, String systemProperty, T value);
1399
1400    /**
1401     * Given a parent document, order the source child before the destination child. The source and destination must be
1402     * name of child documents of the given parent document. (a document name can be retrieved using
1403     * <code>docModel.getName()</code>) To place the source document at the end of the children list use a null
1404     * destination node.
1405     *
1406     * @param parent the parent document
1407     * @param src the document to be moved (ordered)
1408     * @param dest the document before which the reordered document will be placed If null the source document will be
1409     *            placed at the end of the children list
1410     */
1411    void orderBefore(DocumentRef parent, String src, String dest);
1412
1413    /**
1414     * Internal method - it is used internally by {@link DocumentModel#refresh()}
1415     * <p>
1416     * Get fresh data from a document given a description of what kind of data should be refetched.
1417     * <p>
1418     * The refresh information is specified using a bit mask. See {@link DocumentModel} for all accepted flags.
1419     * <p>
1420     * When the flag {@link DocumentModel#REFRESH_CONTENT_IF_LOADED} is specified a third argument must be passed
1421     * representing the schema names for document parts to refresh. This argument is ignored if the flag is not
1422     * specified or no schema names are provided
1423     *
1424     * @param ref the document reference
1425     * @param refreshFlags refresh flags as defined in {@link DocumentModel}
1426     * @param schemas the schema names if a partial content refresh is required
1427     * @return a DocumentModelRefresh object
1428     */
1429    DocumentModelRefresh refreshDocument(DocumentRef ref, int refreshFlags, String[] schemas);
1430
1431    /**
1432     * Provides the full list of all permissions or groups of permissions that contain the given one (inclusive). It
1433     * makes the method {@link org.nuxeo.ecm.core.security.SecurityService#getPermissionsToCheck} available remote.
1434     *
1435     * @return the list, as an array of strings.
1436     */
1437    String[] getPermissionsToCheck(String permission);
1438
1439    /**
1440     * Find the first parent with the given {@code facet} and adapt it on the {@code adapterClass}.
1441     * <p>
1442     * This method does not check the permissions on the document to be adapted of this {@code CoreSession}'s
1443     * {@code Principal}, and so the adapter must not need other schemas from the {@code DocumentModel} except the
1444     * schemas related to the given facet.
1445     *
1446     * @return the first parent with the given {@code facet} adapted, or {@code null} if no parent found or the document
1447     *         does not support the given {@code adapterClass}.
1448     * @since 5.4.2
1449     */
1450    <T extends DetachedAdapter> T adaptFirstMatchingDocumentWithFacet(DocumentRef docRef, String facet,
1451            Class<T> adapterClass);
1452
1453    /**
1454     * Gets the fulltext extracted from the binary fields.
1455     *
1456     * @param ref the document reference
1457     * @return the fulltext map or {@code null} if not supported.
1458     * @since 5.9.3
1459     */
1460    Map<String, String> getBinaryFulltext(DocumentRef ref);
1461
1462    /** @since 8.2 */
1463    enum CopyOption {
1464
1465        RESET_LIFE_CYCLE,
1466
1467        RESET_CREATOR;
1468
1469        public static boolean isResetLifeCycle(CopyOption... options) {
1470            return options != null && Arrays.asList(options).contains(RESET_LIFE_CYCLE);
1471        }
1472
1473        public static boolean isResetCreator(CopyOption... options) {
1474            return options != null && Arrays.asList(options).contains(RESET_CREATOR);
1475        }
1476
1477    }
1478
1479}