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