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