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