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