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