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