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