001 /** 002 * Copyright (c) 2000-2013 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.ClassedModel; 020 import com.liferay.portal.model.ContainerModel; 021 import com.liferay.portal.model.SystemEvent; 022 import com.liferay.portal.model.TrashedModel; 023 import com.liferay.portal.security.permission.PermissionChecker; 024 import com.liferay.portal.service.ServiceContext; 025 import com.liferay.portlet.trash.model.TrashEntry; 026 027 import java.util.List; 028 029 import javax.portlet.PortletRequest; 030 031 /** 032 * The interface for managing the basic trash operations of the Recycle Bin, 033 * which include: 034 * 035 * <ul> 036 * <li> 037 * Deleting trash entries 038 * </li> 039 * <li> 040 * Moving trash entries out of the Recycle Bin to new destinations 041 * </li> 042 * <li> 043 * Restoring trash entries to their original locations 044 * </li> 045 * </ul> 046 * 047 * <p> 048 * These operations are supported for the following entities via their 049 * respective trash handlers: 050 * </p> 051 * 052 * <ul> 053 * <li> 054 * BlogsEntry via {@link com.liferay.portlet.blogs.trash.BlogsEntryTrashHandler} 055 * </li> 056 * <li> 057 * BookmarksEntry via {@link 058 * com.liferay.portlet.bookmarks.trash.BookmarksEntryTrashHandler} 059 * </li> 060 * <li> 061 * DLFileEntry via {@link 062 * com.liferay.portlet.documentlibrary.trash.DLFileEntryTrashHandler} 063 * </li> 064 * <li> 065 * DLFileShortcut via {@link 066 * com.liferay.portlet.documentlibrary.trash.DLFileShortcutTrashHandler} 067 * </li> 068 * <li> 069 * DLFolder via {@link 070 * com.liferay.portlet.documentlibrary.trash.DLFolderTrashHandler} 071 * </li> 072 * <li> 073 * MBThread via {@link 074 * com.liferay.portlet.messageboards.trash.MBThreadTrashHandler} 075 * </li> 076 * <li> 077 * WikiNode via {@link 078 * com.liferay.portlet.wiki.trash.WikiNodeTrashHandler} 079 * </li> 080 * <li> 081 * WikiPage via {@link 082 * com.liferay.portlet.wiki.trash.WikiPageTrashHandler} 083 * </li> 084 * </ul> 085 * 086 * @author Alexander Chow 087 * @author Zsolt Berentey 088 */ 089 public interface TrashHandler { 090 091 public SystemEvent addDeletionSystemEvent( 092 long userId, long groupId, long classPK, String classUuid, 093 String referrerClassName) 094 throws PortalException, SystemException; 095 096 public void checkDuplicateEntry( 097 long classPK, long containerModelId, String newName) 098 throws PortalException, SystemException; 099 100 /** 101 * Checks if a duplicate trash entry already exists in the destination 102 * container. 103 * 104 * <p> 105 * This method is used to check for duplicates when a trash entry is being 106 * restored or moved out of the Recycle Bin. 107 * </p> 108 * 109 * @param trashEntry the trash entry to check 110 * @param containerModelId the primary key of the destination (e.g. folder) 111 * @param newName the new name to be assigned to the trash entry 112 * (optionally <code>null</code> to forego renaming the trash entry) 113 * @throws PortalException if a duplicate trash entry already existed in the 114 * destination container 115 * @throws SystemException if a system exception occurred 116 */ 117 public void checkDuplicateTrashEntry( 118 TrashEntry trashEntry, long containerModelId, String newName) 119 throws PortalException, SystemException; 120 121 /** 122 * Deletes the model entity with the primary key. 123 * 124 * @param classPK the primary key of the model entity to delete 125 * @throws PortalException if a model entity with the primary key could not 126 * be found 127 * @throws SystemException if a system exception occurred 128 */ 129 public void deleteTrashEntry(long classPK) 130 throws PortalException, SystemException; 131 132 /** 133 * Returns the class name handled by this trash handler. 134 * 135 * @return the class name handled by this trash handler 136 */ 137 public String getClassName(); 138 139 /** 140 * Returns the container model with the primary key. 141 * 142 * @param containerModelId the primary key of the container model 143 * @return the container model with the primary key 144 * @throws PortalException if a container model with the primary key could 145 * not be found 146 * @throws SystemException if a system exception occurred 147 */ 148 public ContainerModel getContainerModel(long containerModelId) 149 throws PortalException, SystemException; 150 151 /** 152 * Returns the parent container model's class name. 153 */ 154 public String getContainerModelClassName(); 155 156 /** 157 * Returns the name of the container model (e.g. folder name). 158 * 159 * @return the name of the container model 160 */ 161 public String getContainerModelName(); 162 163 /** 164 * Returns a range of all the container models that are children of the 165 * parent container model identified by the container model ID. These 166 * container models must be able to contain the model entity identified by 167 * the primary key. 168 * 169 * <p> 170 * This method checks for the view permission when retrieving the container 171 * models. 172 * </p> 173 * 174 * <p> 175 * Useful when paginating results. Returns a maximum of <code>end - 176 * start</code> instances. The <code>start</code> and <code>end</code> 177 * values are not primary keys but, rather, indexes in the result set. Thus, 178 * <code>0</code> refers to the first result in the set. Setting both 179 * <code>start</code> and <code>end</code> to {@link 180 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 181 * result set. 182 * </p> 183 * 184 * @param classPK the primary key of a model entity the container models 185 * must be able to contain 186 * @param containerModelId the primary key of the parent container model 187 * @param start the lower bound of the range of results 188 * @param end the upper bound of the range of results (not inclusive) 189 * @return the range of matching container models 190 * @throws PortalException if a model entity with the primary key could not 191 * be found 192 * @throws SystemException if a system exception occurred 193 */ 194 public List<ContainerModel> getContainerModels( 195 long classPK, long containerModelId, int start, int end) 196 throws PortalException, SystemException; 197 198 /** 199 * Returns the number of container models that are children of the parent 200 * container model identified by the container model ID. These container 201 * models must be able to contain the model entity identified by the primary 202 * key. 203 * 204 * <p> 205 * This method checks for the view permission when counting the container 206 * models. 207 * </p> 208 * 209 * @param classPK the primary key of a model entity the container models 210 * must be able to contain 211 * @param containerModelId the primary key of the parent container model 212 * @return the number of matching container models 213 * @throws PortalException if a model entity with the primary key could not 214 * be found 215 * @throws SystemException if a system exception occurred 216 */ 217 public int getContainerModelsCount(long classPK, long containerModelId) 218 throws PortalException, SystemException; 219 220 /** 221 * Returns the language key to the localized message to display next to a 222 * trash entry listed in a search result, indicating that the trash entry 223 * was found in a trashed container (e.g. folder or message board thread) 224 * this trash handler is associated with. 225 * 226 * <p> 227 * If the language key (e.g. <code>found-in-deleted-folder-x</code>) used 228 * accepts a single parameter, the trash framework replaces that parameter 229 * with the trashed container's name. 230 * </p> 231 * 232 * @return the language key to the localized message to display next to a 233 * trash entry listed in a search result 234 */ 235 public String getDeleteMessage(); 236 237 /** 238 * Returns the parent container model of the model entity with the primary 239 * key. 240 * 241 * @param classPK the primary key of a model entity the container models 242 * must be able to contain 243 * @return the parent container model of the model entity with the primary 244 * key 245 * @throws PortalException if a portal exception occurred 246 * @throws SystemException if a system exception occurred 247 */ 248 public ContainerModel getParentContainerModel(long classPK) 249 throws PortalException, SystemException; 250 251 public ContainerModel getParentContainerModel(TrashedModel trashedModel) 252 throws PortalException, SystemException; 253 254 /** 255 * Returns all the parent container models of the model entity with the 256 * primary key ordered by hierarchy. 257 * 258 * <p> 259 * For example, if the primary key is for a file entry inside folder C, 260 * which is inside folder B, which is inside folder A; this method returns 261 * container models for folders A, B, and C. 262 * </p> 263 * 264 * @param classPK the primary key of a model entity the container models 265 * must be able to contain 266 * @return all the matching parent container models of the model entity 267 * @throws PortalException if a portal exception occurred 268 * @throws SystemException if a system exception occurred 269 */ 270 public List<ContainerModel> getParentContainerModels(long classPK) 271 throws PortalException, SystemException; 272 273 public String getRestoreContainedModelLink( 274 PortletRequest portletRequest, long classPK) 275 throws PortalException, SystemException; 276 277 /** 278 * Returns the link to the location to which the model entity was restored. 279 * 280 * @param portletRequest the portlet request 281 * @param classPK the primary key of the restored model entity 282 * @return the restore link 283 * @throws PortalException if a model entity with the primary key could not 284 * be found 285 * @throws SystemException if a system exception occurred 286 */ 287 public String getRestoreContainerModelLink( 288 PortletRequest portletRequest, long classPK) 289 throws PortalException, SystemException; 290 291 /** 292 * Returns the message describing the location to which the model entity was 293 * restored. 294 * 295 * @param portletRequest the portlet request 296 * @param classPK the primary key of the restored model entity 297 * @return the restore message 298 * @throws PortalException if a model entity with the primary key could not 299 * be found 300 * @throws SystemException if a system exception occurred 301 */ 302 public String getRestoreMessage(PortletRequest portletRequest, long classPK) 303 throws PortalException, SystemException; 304 305 /** 306 * Returns the name of the root container (e.g. "home"). 307 * 308 * @return the name of the root container 309 */ 310 public String getRootContainerModelName(); 311 312 /** 313 * Returns the name of the subcontainer model (e.g. for a folder the 314 * subcontainer model name may be "subfolder"). 315 * 316 * @return the name of the subcontainer model 317 */ 318 public String getSubcontainerModelName(); 319 320 public String getSystemEventClassName(); 321 322 /** 323 * Returns the name of the contained model. 324 * 325 * <p> 326 * For example, "files" may be the model name for a folder and "pages" may 327 * be the model name for a wiki node. 328 * </p> 329 * 330 * @return the name of the contained model 331 */ 332 public String getTrashContainedModelName(); 333 334 /** 335 * Returns the number of model entities (excluding container model entities) 336 * that are children of the parent container model identified by the primary 337 * key. 338 * 339 * <p> 340 * For example, for a folder with subfolders and documents, the number of 341 * documents (excluding those explicitely moved to the recycle bin) is 342 * returned. 343 * </p> 344 * 345 * @param classPK the primary key of a container model 346 * @return the number of model entities that are children of the parent 347 * container model identified by the primary key 348 * @throws PortalException if a portal exception occurred 349 * @throws SystemException if a system exception occurred 350 */ 351 public int getTrashContainedModelsCount(long classPK) 352 throws PortalException, SystemException; 353 354 /** 355 * Returns a range of all the trash renderers of model entities (excluding 356 * container models) that are children of the parent container model 357 * identified by the primary key. 358 * 359 * <p> 360 * For example, for a folder with subfolders and documents, a range of all 361 * the trash renderers of documents (excluding those explicitly moved to the 362 * recycle bin) is returned. 363 * </p> 364 * 365 * <p> 366 * Useful when paginating results. Returns a maximum of <code>end - 367 * start</code> instances. The <code>start</code> and <code>end</code> 368 * values are not primary keys but, rather, indexes in the result set. Thus, 369 * <code>0</code> refers to the first result in the set. Setting both 370 * <code>start</code> and <code>end</code> to {@link 371 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 372 * result set. 373 * </p> 374 * 375 * @param classPK the primary key of a container model 376 * @param start the lower bound of the range of results 377 * @param end the upper bound of the range of results (not inclusive) 378 * @return the range of trash renderers of model entities (excluding 379 * container models) that are children of the parent container model 380 * identified by the primary key 381 * @throws PortalException if a portal exception occurred 382 * @throws SystemException if a system exception occurred 383 */ 384 public List<TrashRenderer> getTrashContainedModelTrashRenderers( 385 long classPK, int start, int end) 386 throws PortalException, SystemException; 387 388 public ContainerModel getTrashContainer(long classPK) 389 throws PortalException, SystemException; 390 391 /** 392 * Returns the name of the container model. 393 * 394 * <p> 395 * For example, "folder" may be the container model name for a file entry. 396 * </p> 397 * 398 * @return the name of the container model 399 */ 400 public String getTrashContainerModelName(); 401 402 /** 403 * Returns the number of container models that are children of the parent 404 * container model identified by the primary key. 405 * 406 * <p> 407 * For example, for a folder with subfolders and documents, the number of 408 * folders (excluding those explicitly moved to the recycle bin) is 409 * returned. 410 * </p> 411 * 412 * @param classPK the primary key of a container model 413 * @return the number of container models that are children of the parent 414 * container model identified by the primary key 415 * @throws PortalException if a portal exception occurred 416 * @throws SystemException if a system exception occurred 417 */ 418 public int getTrashContainerModelsCount(long classPK) 419 throws PortalException, SystemException; 420 421 /** 422 * Returns a range of all the trash renderers of model entities that are 423 * children of the parent container model identified by the primary key. 424 * 425 * <p> 426 * For example, for a folder with subfolders and documents, the range of 427 * renderers representing folders (excluding those explicitly moved to the 428 * recycle bin) is returned. 429 * </p> 430 * 431 * <p> 432 * Useful when paginating results. Returns a maximum of <code>end - 433 * start</code> instances. The <code>start</code> and <code>end</code> 434 * values are not primary keys but, rather, indexes in the result set. Thus, 435 * <code>0</code> refers to the first result in the set. Setting both 436 * <code>start</code> and <code>end</code> to {@link 437 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 438 * result set. 439 * </p> 440 * 441 * @param classPK the primary key of a container model 442 * @param start the lower bound of the range of results 443 * @param end the upper bound of the range of results (not inclusive) 444 * @return the range of matching trash renderers of model entities 445 * @throws PortalException if a portal exception occurred 446 * @throws SystemException if a system exception occurred 447 */ 448 public List<TrashRenderer> getTrashContainerModelTrashRenderers( 449 long classPK, int start, int end) 450 throws PortalException, SystemException; 451 452 public TrashEntry getTrashEntry(long classPK) 453 throws PortalException, SystemException; 454 455 /** 456 * Returns the trash renderer associated to the model entity with the 457 * primary key. 458 * 459 * @param classPK the primary key of the model entity 460 * @return the trash renderer associated to the model entity 461 * @throws PortalException if a model entity with the primary key could not 462 * be found 463 * @throws SystemException if a system exception occurred 464 */ 465 public TrashRenderer getTrashRenderer(long classPK) 466 throws PortalException, SystemException; 467 468 /** 469 * Returns <code>true</code> if the user has the required permission to 470 * perform the trash action on the model entity with the primary key. 471 * 472 * <p> 473 * This method is a mapper for special Recycle Bin operations that are not 474 * real permissions. The implementations of this method should translate 475 * these virtual permissions to real permission checks. 476 * </p> 477 * 478 * @param permissionChecker the permission checker 479 * @param groupId the primary key of the group 480 * @param classPK the primary key of the model entity 481 * @param trashActionId the trash action permission to check 482 * @return <code>true</code> if the user has the required permission; 483 * <code>false</code> otherwise 484 * @throws PortalException if a model entity with the primary key could not 485 * be found 486 * @throws SystemException if a system exception occurred 487 */ 488 public boolean hasTrashPermission( 489 PermissionChecker permissionChecker, long groupId, long classPK, 490 String trashActionId) 491 throws PortalException, SystemException; 492 493 /** 494 * Returns <code>true</code> if the entity is a container model. 495 * 496 * @return <code>true</code> if the entity is a container model; 497 * <code>false</code> otherwise 498 */ 499 public boolean isContainerModel(); 500 501 /** 502 * Returns <code>true</code> if the entity can be deleted from the Recycle 503 * Bin. 504 * 505 * @return <code>true</code> if the entity can be deleted from the Recycle 506 * Bin. 507 */ 508 public boolean isDeletable(); 509 510 /** 511 * Returns <code>true</code> if the model entity with the primary key is in 512 * the Recycle Bin. 513 * 514 * @param classPK the primary key of the model entity 515 * @return <code>true</code> if the model entity is in the Recycle Bin; 516 * <code>false</code> otherwise 517 * @throws PortalException if a model entity with the primary key could not 518 * be found in the portal 519 * @throws SystemException if a system exception occurred 520 */ 521 public boolean isInTrash(long classPK) 522 throws PortalException, SystemException; 523 524 /** 525 * Returns <code>true</code> if the model entity with the primary key is in 526 * a container that is in the Recycle Bin. 527 * 528 * @param classPK the primary key of the model entity 529 * @return <code>true</code> if the model entity with the primary key is in 530 * a container that is in the Recycle Bin; <code>false</code> 531 * otherwise 532 * @throws PortalException if a model entity with the primary key could not 533 * be found in the portal 534 * @throws SystemException if a system exception occurred 535 */ 536 public boolean isInTrashContainer(long classPK) 537 throws PortalException, SystemException; 538 539 /** 540 * Returns <code>true</code> if the entity can be moved from one container 541 * model (such as a folder) to another. 542 * 543 * @return <code>true</code> if the entity can be moved from one container 544 * model to another; <code>false</code> otherwise 545 */ 546 public boolean isMovable(); 547 548 /** 549 * Returns <code>true</code> if the model entity can be restored to its 550 * original location. 551 * 552 * <p> 553 * This method usually returns <code>false</code> if the container (e.g. 554 * folder) of the model entity is no longer available (e.g. moved to the 555 * Recycle Bin or deleted). 556 * </p> 557 * 558 * @param classPK the primary key of the model entity 559 * @return <code>true</code> if the model entity can be restored to its 560 * original location; <code>false</code> otherwise 561 * @throws PortalException if a model entity with the primary key could not 562 * be found 563 * @throws SystemException if a system exception occurred 564 */ 565 public boolean isRestorable(long classPK) 566 throws PortalException, SystemException; 567 568 public boolean isTrashEntry( 569 TrashEntry trashEntry, ClassedModel classedModel); 570 571 /** 572 * Moves the entity with the class primary key to the container model with 573 * the class primary key 574 * 575 * @param userId the user ID 576 * @param classPK the primary key of the model entity 577 * @param containerModelId the primary key of the destination container 578 * model 579 * @param serviceContext the service context to be applied 580 * @throws PortalException if a model entity with the primary key or the 581 * destination container model with the primary key could not be 582 * found 583 * @throws SystemException if a system exception occurred 584 */ 585 public void moveEntry( 586 long userId, long classPK, long containerModelId, 587 ServiceContext serviceContext) 588 throws PortalException, SystemException; 589 590 /** 591 * Moves the model entity with the primary key out of the Recycle Bin to a 592 * new destination identified by the container model ID. 593 * 594 * @param userId the user ID 595 * @param classPK the primary key of the model entity 596 * @param containerModelId the primary key of the destination container 597 * model 598 * @param serviceContext the service context to be applied 599 * @throws PortalException if a model entity with the primary key or the 600 * destination container model with the primary key could not be 601 * found 602 * @throws SystemException if a system exception occurred 603 */ 604 public void moveTrashEntry( 605 long userId, long classPK, long containerModelId, 606 ServiceContext serviceContext) 607 throws PortalException, SystemException; 608 609 /** 610 * Restores the model entity that is related to the model entity with the 611 * class name and class PK. For example, {@link 612 * com.liferay.portlet.wiki.trash.WikiPageTrashHandler#restoreRelatedTrashEntry( 613 * String, long)} restores the attachment related to the wiki page with the 614 * class name and class PK. 615 * 616 * @param className the class name of the model entity with a related model 617 * entity to restore 618 * @param classPK the primary key of the model entity with a related model 619 * entity to restore 620 * @throws PortalException if a model entity with the primary key could not 621 * be found 622 * @throws SystemException if a system exception occurred 623 */ 624 public void restoreRelatedTrashEntry(String className, long classPK) 625 throws PortalException, SystemException; 626 627 /** 628 * Restores the model entity with the primary key. 629 * 630 * @param userId the user ID 631 * @param classPK the primary key of the model entity to restore 632 * @throws PortalException if a model entity with the primary key could not 633 * be found 634 * @throws SystemException if a system exception occurred 635 */ 636 public void restoreTrashEntry(long userId, long classPK) 637 throws PortalException, SystemException; 638 639 /** 640 * Updates the title of the model entity with the primary key. This method 641 * is called by {@link com.liferay.portlet.trash.action.EditEntryAction} 642 * before restoring the model entity via its restore rename action. 643 * 644 * @param classPK the primary key of the model entity 645 * @param title the title to be assigned 646 * @throws PortalException if a model entity with the primary key could not 647 * be found 648 * @throws SystemException if a system exception occurred 649 */ 650 public void updateTitle(long classPK, String title) 651 throws PortalException, SystemException; 652 653 }