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