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