001 /** 002 * Copyright (c) 2000-2012 Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.portal.kernel.trash; 016 017 import com.liferay.portal.kernel.exception.PortalException; 018 import com.liferay.portal.kernel.exception.SystemException; 019 import com.liferay.portal.model.ContainerModel; 020 import com.liferay.portal.model.Group; 021 import com.liferay.portal.security.permission.PermissionChecker; 022 import com.liferay.portal.service.ServiceContext; 023 import com.liferay.portlet.trash.model.TrashEntry; 024 025 import java.util.Date; 026 import java.util.List; 027 028 import javax.portlet.PortletRequest; 029 030 /** 031 * The interface for managing the basic trash operations of the Recycle Bin, 032 * which include: 033 * 034 * <ul> 035 * <li> 036 * Deleting trash entries 037 * </li> 038 * <li> 039 * Moving trash entries out of the Recycle Bin to new destinations 040 * </li> 041 * <li> 042 * Restoring trash entries to their original locations 043 * </li> 044 * </ul> 045 * 046 * <p> 047 * These operations are supported for the following entities via their 048 * respective trash handlers: 049 * </p> 050 * 051 * <ul> 052 * <li> 053 * BlogsEntry via {@link com.liferay.portlet.blogs.trash.BlogsEntryTrashHandler} 054 * </li> 055 * <li> 056 * BookmarksEntry via {@link 057 * com.liferay.portlet.bookmarks.trash.BookmarksEntryTrashHandler} 058 * </li> 059 * <li> 060 * DLFileEntry via {@link 061 * com.liferay.portlet.documentlibrary.trash.DLFileEntryTrashHandler} 062 * </li> 063 * <li> 064 * DLFileShortcut via {@link 065 * com.liferay.portlet.documentlibrary.trash.DLFileShortcutTrashHandler} 066 * </li> 067 * <li> 068 * DLFolder via {@link 069 * com.liferay.portlet.documentlibrary.trash.DLFolderTrashHandler} 070 * </li> 071 * <li> 072 * MBThread via {@link 073 * com.liferay.portlet.messageboards.trash.MBThreadTrashHandler} 074 * </li> 075 * <li> 076 * WikiNode via {@link 077 * com.liferay.portlet.wiki.trash.WikiNodeTrashHandler} 078 * </li> 079 * <li> 080 * WikiPage via {@link 081 * com.liferay.portlet.wiki.trash.WikiPageTrashHandler} 082 * </li> 083 * </ul> 084 * 085 * @author Alexander Chow 086 * @author Zsolt Berentey 087 */ 088 public interface TrashHandler { 089 090 /** 091 * Checks if a duplicate trash entry already exists in the destination 092 * container. 093 * 094 * <p> 095 * This method is used to check for duplicates when a trash entry is being 096 * restored or moved out of the Recycle Bin. 097 * </p> 098 * 099 * @param trashEntry the trash entry to check 100 * @param containerModelId the primary key of the destination (e.g. folder) 101 * @param newName the new name to be assigned to the trash entry 102 * (optionally <code>null</code> to forego renaming the trash entry) 103 * @throws PortalException if a duplicate trash entry already existed in the 104 * destination container 105 * @throws SystemException if a system exception occurred 106 */ 107 public void checkDuplicateTrashEntry( 108 TrashEntry trashEntry, long containerModelId, String newName) 109 throws PortalException, SystemException; 110 111 /** 112 * Deletes the group's attachments that were trashed before the given date. 113 * 114 * @param group ID the primary key of the group 115 * @param date the date from which attachments will be deleted 116 * @throws PortalException if any one of the attachment file paths were 117 * invalid 118 * @throws SystemException if a system exception occurred 119 */ 120 public void deleteTrashAttachments(Group group, Date date) 121 throws PortalException, SystemException; 122 123 /** 124 * Deletes all the model entities with the primary keys. 125 * 126 * @param classPKs the primary keys of the model entities to delete 127 * @throws PortalException if any one of the model entities could not be 128 * found 129 * @throws SystemException if a system exception occurred 130 */ 131 public void deleteTrashEntries(long[] classPKs) 132 throws PortalException, SystemException; 133 134 /** 135 * Deletes all the model entities with the primary keys, optionally checking 136 * permission before deleting each model entity. 137 * 138 * @param classPKs the primary keys of the model entities to delete 139 * @param checkPermission whether to check permission before deleting each 140 * model entity 141 * @throws PortalException if any one of the model entities could not be 142 * found 143 * @throws SystemException if a system exception occurred 144 */ 145 public void deleteTrashEntries(long[] classPKs, boolean checkPermission) 146 throws PortalException, SystemException; 147 148 /** 149 * Deletes the model entity with the primary key. 150 * 151 * @param classPK the primary key of the model entity to delete 152 * @throws PortalException if a model entity with the primary key could not 153 * be found 154 * @throws SystemException if a system exception occurred 155 */ 156 public void deleteTrashEntry(long classPK) 157 throws PortalException, SystemException; 158 159 /** 160 * Deletes the model entity with the primary key. 161 * 162 * @param classPK the primary key of the model entity to delete 163 * @param checkPermission whether to check permission before deleting the 164 * model entity 165 * @throws PortalException if a model entity with the primary key could not 166 * be found 167 * @throws SystemException if a system exception occurred 168 */ 169 public void deleteTrashEntry(long classPK, boolean checkPermission) 170 throws PortalException, SystemException; 171 172 /** 173 * Returns the class name handled by this trash handler. 174 * 175 * @return the class name handled by this trash handler 176 */ 177 public String getClassName(); 178 179 /** 180 * Returns the container model with the primary key. 181 * 182 * @param containerModelId the primary key of the container model 183 * @return the container model with the primary key 184 * @throws PortalException if a container model with the primary key could 185 * not be found 186 * @throws SystemException if a system exception occurred 187 */ 188 public ContainerModel getContainerModel(long containerModelId) 189 throws PortalException, SystemException; 190 191 /** 192 * Returns the name of the container model (e.g. folder name). 193 * 194 * @return the name of the container model 195 */ 196 public String getContainerModelName(); 197 198 /** 199 * Returns a range of all the container models that are children of the 200 * parent container model identified by the container model ID. These 201 * container models must be able to contain the model entity identified by 202 * the primary key. 203 * 204 * <p> 205 * This method checks for the view permission when retrieving the container 206 * models. 207 * </p> 208 * 209 * <p> 210 * Useful when paginating results. Returns a maximum of <code>end - 211 * start</code> instances. The <code>start</code> and <code>end</code> 212 * values are not primary keys but, rather, indexes in the result set. Thus, 213 * <code>0</code> refers to the first result in the set. Setting both 214 * <code>start</code> and <code>end</code> to {@link 215 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 216 * result set. 217 * </p> 218 * 219 * @param classPK the primary key of a model entity the container models 220 * must be able to contain 221 * @param containerModelId the primary key of the parent container model 222 * @param start the lower bound of the range of results 223 * @param end the upper bound of the range of results (not inclusive) 224 * @return the range of matching container models 225 * @throws PortalException if a model entity with the primary key could not 226 * be found 227 * @throws SystemException if a system exception occurred 228 */ 229 public List<ContainerModel> getContainerModels( 230 long classPK, long containerModelId, int start, int end) 231 throws PortalException, SystemException; 232 233 /** 234 * Returns the number of container models that are children of the parent 235 * container model identified by the container model ID. These container 236 * models must be able to contain the model entity identified by the primary 237 * key. 238 * 239 * <p> 240 * This method checks for the view permission when counting the container 241 * models. 242 * </p> 243 * 244 * @param classPK the primary key of a model entity the container models 245 * must be able to contain 246 * @param containerModelId the primary key of the parent container model 247 * @return the number of matching container models 248 * @throws PortalException if a model entity with the primary key could not 249 * be found 250 * @throws SystemException if a system exception occurred 251 */ 252 public int getContainerModelsCount(long classPK, long containerModelId) 253 throws PortalException, SystemException; 254 255 /** 256 * Returns the language key to the localized message to display next to a 257 * trash entry listed in a search result, indicating that the trash entry 258 * was found in a trashed container (e.g. folder or message board thread) 259 * this trash handler is associated with. 260 * 261 * <p> 262 * If the language key (e.g. <code>found-in-deleted-folder-x</code>) used 263 * accepts a single parameter, the trash framework replaces that parameter 264 * with the trashed container's name. 265 * </p> 266 * 267 * @return the language key to the localized message to display next to a 268 * trash entry listed in a search result 269 */ 270 public String getDeleteMessage(); 271 272 /** 273 * Returns the link to the location to which the model entity was restored. 274 * 275 * @param portletRequest the portlet request 276 * @param classPK the primary key of the restored model entity 277 * @return the restore link 278 * @throws PortalException if a model entity with the primary key could not 279 * be found 280 * @throws SystemException if a system exception occurred 281 */ 282 public String getRestoreLink(PortletRequest portletRequest, long classPK) 283 throws PortalException, SystemException; 284 285 /** 286 * Returns the message describing the location to which the model entity was 287 * restored. 288 * 289 * @param portletRequest the portlet request 290 * @param classPK the primary key of the restored model entity 291 * @return the restore message 292 * @throws PortalException if a model entity with the primary key could not 293 * be found 294 * @throws SystemException if a system exception occurred 295 */ 296 public String getRestoreMessage(PortletRequest portletRequest, long classPK) 297 throws PortalException, SystemException; 298 299 /** 300 * Returns the name of the root container (e.g. "home"). 301 * 302 * @return the name of the root container 303 */ 304 public String getRootContainerModelName(); 305 306 /** 307 * Returns the name of the sub-container model (e.g. for a folder the 308 * sub-container model name may be "subfolder"). 309 * 310 * @return the name of the sub-container model 311 */ 312 public String getSubcontainerModelName(); 313 314 /** 315 * Returns the trash renderer associated to the model entity with the 316 * primary key. 317 * 318 * @param classPK the primary key of the model entity 319 * @return the trash renderer associated to the model entity 320 * @throws PortalException if a model entity with the primary key could not 321 * be found 322 * @throws SystemException if a system exception occurred 323 */ 324 public TrashRenderer getTrashRenderer(long classPK) 325 throws PortalException, SystemException; 326 327 /** 328 * Returns <code>true</code> if the user has the required permission to 329 * perform the trash action on the model entity with the primary key. 330 * 331 * <p> 332 * This method is a mapper for special Recycle Bin operations that are not 333 * real permissions. The implementations of this method should translate 334 * these virtual permissions to real permission checks. 335 * </p> 336 * 337 * @param permissionChecker the permission checker 338 * @param groupId the primary key of the group 339 * @param classPK the primary key of the model entity 340 * @param trashActionId the trash action permission to check 341 * @return <code>true</code> if the user has the required permission; 342 * <code>false</code> otherwise 343 * @throws PortalException if a model entity with the primary key could not 344 * be found 345 * @throws SystemException if a system exception occurred 346 */ 347 public boolean hasTrashPermission( 348 PermissionChecker permissionChecker, long groupId, long classPK, 349 String trashActionId) 350 throws PortalException, SystemException; 351 352 /** 353 * Returns <code>true</code> if the model entity with the primary key is in 354 * the Recycle Bin. 355 * 356 * @param classPK the primary key of the model entity 357 * @return <code>true</code> if the model entity is in the Recycle Bin; 358 * <code>false</code> otherwise 359 * @throws PortalException if a model entity with the primary key could not 360 * be found in the portal 361 * @throws SystemException if a system exception occurred 362 */ 363 public boolean isInTrash(long classPK) 364 throws PortalException, SystemException; 365 366 /** 367 * Returns <code>true</code> if the model entity can be restored to its 368 * original location. 369 * 370 * <p> 371 * This method usually returns <code>false</code> if the container (e.g. 372 * folder) of the model entity is no longer available (e.g. moved to the 373 * Recycle Bin or deleted). 374 * </p> 375 * 376 * @param classPK the primary key of the model entity 377 * @return <code>true</code> if the model entity can be restored to its 378 * original location; <code>false</code> otherwise 379 * @throws PortalException if a model entity with the primary key could not 380 * be found 381 * @throws SystemException if a system exception occurred 382 */ 383 public boolean isRestorable(long classPK) 384 throws PortalException, SystemException; 385 386 /** 387 * Moves the model entity with the primary key out of the Recycle Bin to a 388 * new destination identified by the container model ID. 389 * 390 * @param classPK the primary key of the model entity 391 * @param containerModelId the primary key of the destination container 392 * model 393 * @param serviceContext the service context 394 * @return the moved model entity 395 * @throws PortalException if a model entity with the primary key or the 396 * destination container model with the primary key could not be 397 * found 398 * @throws SystemException if a system exception occurred 399 */ 400 public TrashEntry moveTrashEntry( 401 long classPK, long containerModelId, ServiceContext serviceContext) 402 throws PortalException, SystemException; 403 404 /** 405 * Restores all the model entities with the primary keys. 406 * 407 * @param classPKs the primary keys of the model entities to restore 408 * @throws PortalException if any one of the model entities could not be 409 * found 410 * @throws SystemException if a system exception occurred 411 */ 412 public void restoreTrashEntries(long[] classPKs) 413 throws PortalException, SystemException; 414 415 /** 416 * Restores the model entity with the primary key. 417 * 418 * @param classPK the primary key of the model entity to restore 419 * @throws PortalException if a model entity with the primary key could not 420 * be found 421 * @throws SystemException if a system exception occurred 422 */ 423 public void restoreTrashEntry(long classPK) 424 throws PortalException, SystemException; 425 426 /** 427 * Updates the title of the model entity with the primary key. This method 428 * is called by {@link com.liferay.portlet.trash.action.EditEntryAction} 429 * before restoring the model entity via its restore rename action. 430 * 431 * @param classPK the primary key of the model entity 432 * @param title the title to be assigned 433 * @throws PortalException if a model entity with the primary key could not 434 * be found 435 * @throws SystemException if a system exception occurred 436 */ 437 public void updateTitle(long classPK, String title) 438 throws PortalException, SystemException; 439 440 }