001/*
002 * (C) Copyright 2006-2011 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 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.api.trash;
020
021import java.security.Principal;
022import java.util.Collections;
023import java.util.List;
024import java.util.Set;
025
026import org.nuxeo.common.utils.Path;
027import org.nuxeo.ecm.core.api.CoreSession;
028import org.nuxeo.ecm.core.api.DocumentModel;
029import org.nuxeo.ecm.core.api.DocumentModelList;
030import org.nuxeo.ecm.core.api.DocumentRef;
031
032/**
033 * Service containing the logic about deleting/purging/undeleting a document.
034 */
035public interface TrashService {
036
037    /***
038     * Event for a document trashed by the user. Triggers an async listener that trashes its children too.
039     *
040     * @since 10.1
041     */
042    String DOCUMENT_TRASHED = "documentTrashed";
043
044    /***
045     * Event for a document untrashed by the user. Triggers an async listener that untrashes its children too.
046     *
047     * @since 10.1
048     */
049    String DOCUMENT_UNTRASHED = "documentUntrashed";
050
051    /**
052     * Key for {@link DocumentModel#getContextData(String)} which skips the renaming during trash/untrash mechanism when
053     * the value is {@link Boolean#TRUE}.
054     *
055     * @since 10.1
056     */
057    String DISABLE_TRASH_RENAMING = "skipTrashRenaming";
058
059    /**
060     * Configuration property to enable backward compatibility to forward the call to the service on
061     * followTransition("deleted").
062     *
063     * @since 10.2
064     */
065    String IS_TRASHED_FROM_DELETE_TRANSITION = "org.nuxeo.isTrashed.from.deleteTransition";
066
067    /**
068     * @return whether or not the input {@link DocumentRef} is trashed.
069     * @since 10.1
070     */
071    boolean isTrashed(CoreSession session, DocumentRef doc);
072
073    /**
074     * Are all documents purgeable/undeletable?
075     * <p>
076     * Documents need to be in the trash for this to be true, in addition to the standard permission checks.
077     *
078     * @param docs the documents
079     * @param principal the current user (to check locks)
080     * @return {@code true} if the documents are purgeable/undeletable
081     */
082    boolean canPurgeOrUntrash(List<DocumentModel> docs, Principal principal);
083
084    /**
085     * Is document purgeable/untrashable?
086     * <p>
087     * Documents need to be in the trash for this to be true, in addition to the standard permission checks.
088     *
089     * @param doc the document
090     * @param principal the current user (to check locks)
091     * @return {@code true} if the documents are purgeable/untrashable
092     */
093    default boolean canPurgeOrUntrash(DocumentModel doc, Principal principal) {
094        return canPurgeOrUntrash(Collections.singletonList(doc), principal);
095    }
096
097    /**
098     * Gets the first non trashed ancestor.
099     * <p>
100     * This is used to find what safe document to redirect to when deleting one.
101     *
102     * @param doc the trashed document
103     * @param principal the current user
104     * @return the first non trashed ancestor
105     */
106    DocumentModel getAboveDocument(DocumentModel doc, Principal principal);
107
108    /**
109     * Moves documents to the trash.
110     * <p>
111     * Do nothing if the document current state is trashed.
112     * <p>
113     * Placeless documents are deleted immediately.
114     *
115     * @param docs the documents to trash
116     */
117    void trashDocuments(List<DocumentModel> docs);
118
119    /**
120     * Moves document to the trash.
121     * <p>
122     * Do nothing if the document current state is trashed.
123     * <p>
124     * Placeless documents are deleted immediately.
125     *
126     * @param doc the document to trash
127     * @since 10.1
128     */
129    default void trashDocument(DocumentModel doc) {
130        trashDocuments(Collections.singletonList(doc));
131    }
132
133    /**
134     * Purges (completely deletes) documents.
135     *
136     * @param session the session
137     * @param docRefs the documents to purge
138     */
139    void purgeDocuments(CoreSession session, List<DocumentRef> docRefs);
140
141    /**
142     * Purges (completely deletes) trashed documents under the given parent.
143     *
144     * @param parent The parent document of trashed documents.
145     * @since 10.1
146     */
147    void purgeDocumentsUnder(DocumentModel parent);
148
149    /**
150     * Unmoves documents from the trash.
151     * <p>
152     * Also fires async events to untrash the children.
153     *
154     * @param docs the documents to untrash
155     */
156    void untrashDocuments(List<DocumentModel> docs);
157
158    /**
159     * Unmoves document from the trash.
160     * <p>
161     * Also fires async events to untrash the children.
162     *
163     * @param doc the document to untrash
164     * @since 10.1
165     */
166    default void untrashDocument(DocumentModel doc) {
167        untrashDocuments(Collections.singletonList(doc));
168    }
169
170    /**
171     * Get all documents from the trash of the current document.
172     *
173     * @since 7.1
174     * @param parent The parent document of trash document.
175     * @return All documents in the trash of the current document.
176     */
177    DocumentModelList getDocuments(DocumentModel parent);
178
179    /**
180     * Mangles the name of a document to avoid collisions with non-trashed documents when it's in the trash.
181     *
182     * @param doc the document
183     * @since 7.3
184     */
185    String mangleName(DocumentModel doc);
186
187    /**
188     * Unmangles the name of a document in the trash to find its un-trashed name.
189     *
190     * @param doc the trashed document
191     * @return the unmangled name
192     * @since 7.3
193     */
194    String unmangleName(DocumentModel doc);
195
196    /**
197     * Features of the implementation of the service.
198     *
199     * @see TrashService#hasFeature
200     * @since 10.1
201     */
202    enum Feature {
203        /** Trashed state is deduced from lifeCycle. */
204        TRASHED_STATE_IS_DEDUCED_FROM_LIFECYCLE,
205        /** Trashed state currently in migration. */
206        TRASHED_STATE_IN_MIGRATION,
207        /** Trashed state is a dedicated property. */
208        TRASHED_STATE_IS_DEDICATED_PROPERTY,
209    }
210
211    /**
212     * Checks if a feature is available.
213     *
214     * @since 10.1
215     */
216    boolean hasFeature(Feature feature);
217
218}