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