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.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 * {@link TrashService} was already called. This is useful to bring backward mechanism on 061 * followTransition("deleted"). 062 * 063 * @since 10.1 064 */ 065 String IS_ALREADY_CALLED = "trashServiceAlreadyCalled"; 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 * Can a child of the folder be trashed? 075 * 076 * @param folder the folder 077 * @return {@code true} if the folder allows its children to be trashed 078 * @deprecated since 10.1 only used in JSF part, no replacement 079 */ 080 @Deprecated 081 boolean folderAllowsDelete(DocumentModel folder); 082 083 /** 084 * Is at least one doc deletable according to its container? 085 * 086 * @param docs the documents 087 * @return {@code true} if one doc is in a folder that allows its children to be trashed 088 * @deprecated since 10.1 only used in JSF part, no replacement 089 */ 090 @Deprecated 091 boolean checkDeletePermOnParents(List<DocumentModel> docs); 092 093 /** 094 * Is at least one doc deletable? 095 * 096 * @param docs the documents 097 * @param principal the current user (to check locks) 098 * @param checkProxies {@code true} to count proxies as non-deletable 099 * @return {@code true} if at least one doc is deletable 100 * @deprecated since 10.1 only used in JSF part, no replacement 101 */ 102 @Deprecated 103 boolean canDelete(List<DocumentModel> docs, Principal principal, boolean checkProxies); 104 105 /** 106 * Are all documents purgeable/undeletable? 107 * <p> 108 * Documents need to be in the trash for this to be true, in addition to the standard permission checks. 109 * 110 * @param docs the documents 111 * @param principal the current user (to check locks) 112 * @return {@code true} if the documents are purgeable/undeletable 113 * @deprecated since 10.1, use {@link #canPurgeOrUntrash(List, Principal)} 114 */ 115 @Deprecated 116 default boolean canPurgeOrUndelete(List<DocumentModel> docs, Principal principal) { 117 return canPurgeOrUntrash(docs, principal); 118 } 119 120 /** 121 * Are all documents purgeable/undeletable? 122 * <p> 123 * Documents need to be in the trash for this to be true, in addition to the standard permission checks. 124 * 125 * @param docs the documents 126 * @param principal the current user (to check locks) 127 * @return {@code true} if the documents are purgeable/undeletable 128 */ 129 boolean canPurgeOrUntrash(List<DocumentModel> docs, Principal principal); 130 131 /** 132 * Is document purgeable/untrashable? 133 * <p> 134 * Documents need to be in the trash for this to be true, in addition to the standard permission checks. 135 * 136 * @param doc the document 137 * @param principal the current user (to check locks) 138 * @return {@code true} if the documents are purgeable/untrashable 139 */ 140 default boolean canPurgeOrUntrash(DocumentModel doc, Principal principal) { 141 return canPurgeOrUntrash(Collections.singletonList(doc), principal); 142 } 143 144 /** 145 * Gets the trash info for a list of documents. 146 * 147 * @param docs the documents 148 * @param principal the current user (to check locks) 149 * @param checkProxies {@code true} to count proxies as non-deletable 150 * @param checkDeleted {@code true} if documents have to be in the trashed state to be considered (otherwise 151 * forbidden) 152 * @return the trash info 153 * @deprecated since 10.1 only used in JSF part, no replacement 154 */ 155 @Deprecated 156 TrashInfo getTrashInfo(List<DocumentModel> docs, Principal principal, boolean checkProxies, boolean checkDeleted); 157 158 /** 159 * Gets the closest document's ancestor above all the paths. 160 * <p> 161 * This is used to find what safe document to redirect to when deleting some. 162 * 163 * @param doc the document 164 * @param paths the paths 165 * @return the closer document above doc and above all the paths 166 * @deprecated since 10.1 only used in JSF part, use {@link #getAboveDocument(DocumentModel, Principal)} instead. 167 */ 168 @Deprecated 169 DocumentModel getAboveDocument(DocumentModel doc, Set<Path> paths); 170 171 /** 172 * Gets the first non trashed ancestor. 173 * <p> 174 * This is used to find what safe document to redirect to when deleting one. 175 * 176 * @param doc the trashed document 177 * @param principal the current user 178 * @return the first non trashed ancestor 179 */ 180 DocumentModel getAboveDocument(DocumentModel doc, Principal principal); 181 182 /** 183 * Moves documents to the trash. 184 * <p> 185 * Do nothing if the document current state is trashed. 186 * <p> 187 * Placeless documents are deleted immediately. 188 * 189 * @param docs the documents to trash 190 */ 191 void trashDocuments(List<DocumentModel> docs); 192 193 /** 194 * Moves document to the trash. 195 * <p> 196 * Do nothing if the document current state is trashed. 197 * <p> 198 * Placeless documents are deleted immediately. 199 * 200 * @param doc the document to trash 201 * @since 10.1 202 */ 203 default void trashDocument(DocumentModel doc) { 204 trashDocuments(Collections.singletonList(doc)); 205 } 206 207 /** 208 * Purges (completely deletes) documents. 209 * 210 * @param session the session 211 * @param docRefs the documents to purge 212 */ 213 void purgeDocuments(CoreSession session, List<DocumentRef> docRefs); 214 215 /** 216 * Purges (completely deletes) trashed documents under the given parent. 217 * 218 * @param parent The parent document of trashed documents. 219 * @since 10.1 220 */ 221 void purgeDocumentsUnder(DocumentModel parent); 222 223 /** 224 * Undeletes documents (and ancestors if needed to make them visible). 225 * <p> 226 * Also fires async events to untrash the children. 227 * 228 * @param docs the documents to undelete 229 * @return the set of ancestors whose children have been untrashed (for UI notification) 230 * @deprecated since 10.1 use {@link #untrashDocuments(List)} instead 231 */ 232 @Deprecated 233 Set<DocumentRef> undeleteDocuments(List<DocumentModel> docs); 234 235 /** 236 * Unmoves documents from the trash. 237 * <p> 238 * Also fires async events to untrash the children. 239 * 240 * @param docs the documents to untrash 241 */ 242 default void untrashDocuments(List<DocumentModel> docs) { 243 undeleteDocuments(docs); 244 } 245 246 /** 247 * Unmoves document from the trash. 248 * <p> 249 * Also fires async events to untrash the children. 250 * 251 * @param doc the document to untrash 252 * @since 10.1 253 */ 254 default void untrashDocument(DocumentModel doc) { 255 untrashDocuments(Collections.singletonList(doc)); 256 } 257 258 /** 259 * Get all documents from the trash of the current document. 260 * 261 * @since 7.1 262 * @param parent The parent document of trash document. 263 * @return All documents in the trash of the current document. 264 */ 265 DocumentModelList getDocuments(DocumentModel parent); 266 267 /** 268 * Mangles the name of a document to avoid collisions with non-trashed documents when it's in the trash. 269 * 270 * @param doc the document 271 * @since 7.3 272 */ 273 String mangleName(DocumentModel doc); 274 275 /** 276 * Unmangles the name of a document in the trash to find its un-trashed name. 277 * 278 * @param doc the trashed document 279 * @return the unmangled name 280 * @since 7.3 281 */ 282 String unmangleName(DocumentModel doc); 283 284 /** 285 * Features of the implementation of the service. 286 * 287 * @see TrashService#hasFeature 288 * @since 10.1 289 */ 290 enum Feature { 291 /** Trashed state is a dedicated property. */ 292 TRASHED_STATE_IS_DEDICATED_PROPERTY, 293 } 294 295 /** 296 * Checks if a feature is available. 297 * 298 * @since 10.1 299 */ 300 boolean hasFeature(Feature feature); 301 302}