001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Florent Guillaume
011 */
012package org.nuxeo.ecm.core.trash;
013
014import java.security.Principal;
015import java.util.List;
016import java.util.Set;
017
018import org.nuxeo.common.utils.Path;
019import org.nuxeo.ecm.core.api.CoreSession;
020import org.nuxeo.ecm.core.api.DocumentModel;
021import org.nuxeo.ecm.core.api.DocumentModelList;
022import org.nuxeo.ecm.core.api.DocumentRef;
023
024/**
025 * Service containing the logic about deleting/purging/undeleting a document.
026 */
027public interface TrashService {
028
029    /**
030     * Can a child of the folder be deleted?
031     *
032     * @param folder the folder
033     * @return {@code true} if the folder allows its children to be deleted
034     */
035    boolean folderAllowsDelete(DocumentModel folder);
036
037    /**
038     * Is at least one doc deletable according to its container?
039     *
040     * @param docs the documents
041     * @return {@code true} if one doc is in a folder that allows its children to be deleted
042     */
043    boolean checkDeletePermOnParents(List<DocumentModel> docs);
044
045    /**
046     * Is at least one doc deletable?
047     *
048     * @param docs the documents
049     * @param principal the current user (to check locks)
050     * @param checkProxies {@code true} to count proxies as non-deletable
051     * @return {@code true} if at least one doc is deletable
052     */
053    boolean canDelete(List<DocumentModel> docs, Principal principal, boolean checkProxies);
054
055    /**
056     * Are all documents purgeable/undeletable?
057     * <p>
058     * Documents need to be in the deleted lifecycle state for this to be true, in addition to the standard permission
059     * checks.
060     *
061     * @param docs the documents
062     * @param principal the current user (to check locks)
063     * @return {@code true} if the documents are purgeable/undeletable
064     */
065    boolean canPurgeOrUndelete(List<DocumentModel> docs, Principal principal);
066
067    /**
068     * Gets the trash info for a list of documents.
069     *
070     * @param docs the documents
071     * @param principal the current user (to check locks)
072     * @param checkProxies {@code true} to count proxies as non-deletable
073     * @param checkDeleted {@code true} if documents have to be in the deleted state to be considered (otherwise
074     *            forbidden)
075     * @return the trash info
076     */
077    TrashInfo getTrashInfo(List<DocumentModel> docs, Principal principal, boolean checkProxies, boolean checkDeleted);
078
079    /**
080     * Gets the closest document's ancestor above all the paths.
081     * <p>
082     * This is used to find what safe document to redirect to when deleting some.
083     *
084     * @param doc the document
085     * @param paths the paths
086     * @return the closer document above doc and above all the paths
087     */
088    DocumentModel getAboveDocument(DocumentModel doc, Set<Path> paths);
089
090    /**
091     * Moves documents to the trash, or directly deletes them if their lifecycle does not allow trash use.
092     *
093     * Do nothing if the document current state is deleted.
094     *
095     * @param docs the documents to trash
096     */
097    void trashDocuments(List<DocumentModel> docs);
098
099    /**
100     * Purges (completely deletes) documents .
101     *
102     * @param session the session
103     * @param docRefs the documents to purge
104     */
105    void purgeDocuments(CoreSession session, List<DocumentRef> docRefs);
106
107    /**
108     * Undeletes documents (and ancestors if needed to make them visible).
109     * <p>
110     * Also fires async events to undelete the children.
111     *
112     * @param docs the documents to undelete
113     * @return the set of ancestors whose children have been undeleted (for UI notification)
114     */
115    Set<DocumentRef> undeleteDocuments(List<DocumentModel> docs);
116
117    /**
118     * Get all documents from the trash of the current document.
119     *
120     * @since 7.1
121     * @param currentDoc The current/parent document of trash document.
122     * @return All documents in the trash of the current document.
123     */
124    DocumentModelList getDocuments(DocumentModel currentDoc);
125
126    /**
127     * Mangles the name of a document to avoid collisions with non-trashed documents when it's in the trash.
128     *
129     * @param doc the document
130     * @return
131     * @since 7.3
132     */
133    String mangleName(DocumentModel doc);
134
135    /**
136     * Unmangles the name of a document in the trash to find its un-trashed name.
137     *
138     * @param doc the trashed document
139     * @return the unmangled name
140     * @since 7.3
141     */
142    String unmangleName(DocumentModel doc);
143
144}