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