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