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