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