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 sub-container model (e.g. for a folder the 329 * sub-container model name may be "subfolder"). 330 * 331 * @return the name of the sub-container 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 model entity with the primary key is in 509 * the Recycle Bin. 510 * 511 * @param classPK the primary key of the model entity 512 * @return <code>true</code> if the model entity is in the Recycle Bin; 513 * <code>false</code> otherwise 514 * @throws PortalException if a model entity with the primary key could not 515 * be found in the portal 516 * @throws SystemException if a system exception occurred 517 */ 518 public boolean isInTrash(long classPK) 519 throws PortalException, SystemException; 520 521 /** 522 * Returns <code>true</code> if the model entity with the primary key is in 523 * a container that is in the Recycle Bin. 524 * 525 * @param classPK the primary key of the model entity 526 * @return <code>true</code> if the model entity with the primary key is in 527 * a container that is in the Recycle Bin; <code>false</code> 528 * otherwise 529 * @throws PortalException if a model entity with the primary key could not 530 * be found in the portal 531 * @throws SystemException if a system exception occurred 532 */ 533 public boolean isInTrashContainer(long classPK) 534 throws PortalException, SystemException; 535 536 /** 537 * Returns <code>true</code> if the entity can be moved from one container 538 * model (such as a folder) to another. 539 * 540 * @return <code>true</code> if the entity can be moved from one container 541 * model to another; <code>false</code> otherwise 542 */ 543 public boolean isMovable(); 544 545 /** 546 * Returns <code>true</code> if the model entity can be restored to its 547 * original location. 548 * 549 * <p> 550 * This method usually returns <code>false</code> if the container (e.g. 551 * folder) of the model entity is no longer available (e.g. moved to the 552 * Recycle Bin or deleted). 553 * </p> 554 * 555 * @param classPK the primary key of the model entity 556 * @return <code>true</code> if the model entity can be restored to its 557 * original location; <code>false</code> otherwise 558 * @throws PortalException if a model entity with the primary key could not 559 * be found 560 * @throws SystemException if a system exception occurred 561 */ 562 public boolean isRestorable(long classPK) 563 throws PortalException, SystemException; 564 565 /** 566 * Moves the entity with the class primary key to the container model with 567 * the class primary key 568 */ 569 public void moveEntry( 570 long classPK, long containerModelId, ServiceContext serviceContext) 571 throws PortalException, SystemException; 572 573 /** 574 * Moves the model entity with the primary key out of the Recycle Bin to a 575 * new destination identified by the container model ID. 576 * 577 * @param classPK the primary key of the model entity 578 * @param containerModelId the primary key of the destination container 579 * model 580 * @param serviceContext the service context 581 * @throws PortalException if a model entity with the primary key or the 582 * destination container model with the primary key could not be 583 * found 584 * @throws SystemException if a system exception occurred 585 */ 586 public void moveTrashEntry( 587 long classPK, long containerModelId, ServiceContext serviceContext) 588 throws PortalException, SystemException; 589 590 /** 591 * Restores all the model entities with the primary keys. 592 * 593 * @param classPKs the primary keys of the model entities to restore 594 * @throws PortalException if any one of the model entities could not be 595 * found 596 * @throws SystemException if a system exception occurred 597 */ 598 public void restoreTrashEntries(long[] classPKs) 599 throws PortalException, SystemException; 600 601 /** 602 * Restores the model entity with the primary key. 603 * 604 * @param classPK the primary key of the model entity to restore 605 * @throws PortalException if a model entity with the primary key could not 606 * be found 607 * @throws SystemException if a system exception occurred 608 */ 609 public void restoreTrashEntry(long classPK) 610 throws PortalException, SystemException; 611 612 /** 613 * Updates the title of the model entity with the primary key. This method 614 * is called by {@link com.liferay.portlet.trash.action.EditEntryAction} 615 * before restoring the model entity via its restore rename action. 616 * 617 * @param classPK the primary key of the model entity 618 * @param title the title to be assigned 619 * @throws PortalException if a model entity with the primary key could not 620 * be found 621 * @throws SystemException if a system exception occurred 622 */ 623 public void updateTitle(long classPK, String title) 624 throws PortalException, SystemException; 625 626 }