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