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