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