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