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.model.Group;
021    import com.liferay.portal.security.permission.PermissionChecker;
022    import com.liferay.portal.service.ServiceContext;
023    import com.liferay.portlet.trash.model.TrashEntry;
024    
025    import java.util.Date;
026    import java.util.List;
027    
028    import javax.portlet.PortletRequest;
029    
030    /**
031     * The interface for managing the basic trash operations of the Recycle Bin,
032     * which include:
033     *
034     * <ul>
035     * <li>
036     * Deleting trash entries
037     * </li>
038     * <li>
039     * Moving trash entries out of the Recycle Bin to new destinations
040     * </li>
041     * <li>
042     * Restoring trash entries to their original locations
043     * </li>
044     * </ul>
045     *
046     * <p>
047     * These operations are supported for the following entities via their
048     * respective trash handlers:
049     * </p>
050     *
051     * <ul>
052     * <li>
053     * BlogsEntry via {@link com.liferay.portlet.blogs.trash.BlogsEntryTrashHandler}
054     * </li>
055     * <li>
056     * BookmarksEntry via {@link
057     * com.liferay.portlet.bookmarks.trash.BookmarksEntryTrashHandler}
058     * </li>
059     * <li>
060     * DLFileEntry via {@link
061     * com.liferay.portlet.documentlibrary.trash.DLFileEntryTrashHandler}
062     * </li>
063     * <li>
064     * DLFileShortcut via {@link
065     * com.liferay.portlet.documentlibrary.trash.DLFileShortcutTrashHandler}
066     * </li>
067     * <li>
068     * DLFolder via {@link
069     * com.liferay.portlet.documentlibrary.trash.DLFolderTrashHandler}
070     * </li>
071     * <li>
072     * MBThread via {@link
073     * com.liferay.portlet.messageboards.trash.MBThreadTrashHandler}
074     * </li>
075     * <li>
076     * WikiNode via {@link
077     * com.liferay.portlet.wiki.trash.WikiNodeTrashHandler}
078     * </li>
079     * <li>
080     * WikiPage via {@link
081     * com.liferay.portlet.wiki.trash.WikiPageTrashHandler}
082     * </li>
083     * </ul>
084     *
085     * @author Alexander Chow
086     * @author Zsolt Berentey
087     */
088    public interface TrashHandler {
089    
090            /**
091             * Checks if a duplicate trash entry already exists in the destination
092             * container.
093             *
094             * <p>
095             * This method is used to check for duplicates when a trash entry is being
096             * restored or moved out of the Recycle Bin.
097             * </p>
098             *
099             * @param  trashEntry the trash entry to check
100             * @param  containerModelId the primary key of the destination (e.g. folder)
101             * @param  newName the new name to be assigned to the trash entry
102             *         (optionally <code>null</code> to forego renaming the trash entry)
103             * @throws PortalException if a duplicate trash entry already existed in the
104             *         destination container
105             * @throws SystemException if a system exception occurred
106             */
107            public void checkDuplicateTrashEntry(
108                            TrashEntry trashEntry, long containerModelId, String newName)
109                    throws PortalException, SystemException;
110    
111            /**
112             * Deletes the group's attachments that were trashed before the given date.
113             *
114             * @param  group ID the primary key of the group
115             * @param  date the date from which attachments will be deleted
116             * @throws PortalException if any one of the attachment file paths were
117             *         invalid
118             * @throws SystemException if a system exception occurred
119             */
120            public void deleteTrashAttachments(Group group, Date date)
121                    throws PortalException, SystemException;
122    
123            /**
124             * Deletes all the model entities with the primary keys.
125             *
126             * @param  classPKs the primary keys of the model entities to delete
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)
132                    throws PortalException, SystemException;
133    
134            /**
135             * Deletes all the model entities with the primary keys, optionally checking
136             * permission before deleting each model entity.
137             *
138             * @param  classPKs the primary keys of the model entities to delete
139             * @param  checkPermission whether to check permission before deleting each
140             *         model entity
141             * @throws PortalException if any one of the model entities could not be
142             *         found
143             * @throws SystemException if a system exception occurred
144             */
145            public void deleteTrashEntries(long[] classPKs, boolean checkPermission)
146                    throws PortalException, SystemException;
147    
148            /**
149             * Deletes the model entity with the primary key.
150             *
151             * @param  classPK the primary key of the model entity to delete
152             * @throws PortalException if a model entity with the primary key could not
153             *         be found
154             * @throws SystemException if a system exception occurred
155             */
156            public void deleteTrashEntry(long classPK)
157                    throws PortalException, SystemException;
158    
159            /**
160             * Deletes the model entity with the primary key.
161             *
162             * @param  classPK the primary key of the model entity to delete
163             * @param  checkPermission whether to check permission before deleting the
164             *         model entity
165             * @throws PortalException if a model entity with the primary key could not
166             *         be found
167             * @throws SystemException if a system exception occurred
168             */
169            public void deleteTrashEntry(long classPK, boolean checkPermission)
170                    throws PortalException, SystemException;
171    
172            /**
173             * Returns the class name handled by this trash handler.
174             *
175             * @return the class name handled by this trash handler
176             */
177            public String getClassName();
178    
179            /**
180             * Returns the container model with the primary key.
181             *
182             * @param  containerModelId the primary key of the container model
183             * @return the container model with the primary key
184             * @throws PortalException if a container model with the primary key could
185             *         not be found
186             * @throws SystemException if a system exception occurred
187             */
188            public ContainerModel getContainerModel(long containerModelId)
189                    throws PortalException, SystemException;
190    
191            /**
192             * Returns the name of the container model (e.g. folder name).
193             *
194             * @return the name of the container model
195             */
196            public String getContainerModelName();
197    
198            /**
199             * Returns a range of all the container models that are children of the
200             * parent container model identified by the container model ID. These
201             * container models must be able to contain the model entity identified by
202             * the primary key.
203             *
204             * <p>
205             * This method checks for the view permission when retrieving the container
206             * models.
207             * </p>
208             *
209             * <p>
210             * Useful when paginating results. Returns a maximum of <code>end -
211             * start</code> instances. The <code>start</code> and <code>end</code>
212             * values are not primary keys but, rather, indexes in the result set. Thus,
213             * <code>0</code> refers to the first result in the set. Setting both
214             * <code>start</code> and <code>end</code> to {@link
215             * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full
216             * result set.
217             * </p>
218             *
219             * @param  classPK the primary key of a model entity the container models
220             *         must be able to contain
221             * @param  containerModelId the primary key of the parent container model
222             * @param  start the lower bound of the range of results
223             * @param  end the upper bound of the range of results (not inclusive)
224             * @return the range of matching container models
225             * @throws PortalException if a model entity with the primary key could not
226             *         be found
227             * @throws SystemException if a system exception occurred
228             */
229            public List<ContainerModel> getContainerModels(
230                            long classPK, long containerModelId, int start, int end)
231                    throws PortalException, SystemException;
232    
233            /**
234             * Returns the number of container models that are children of the parent
235             * container model identified by the container model ID. These container
236             * models must be able to contain the model entity identified by the primary
237             * key.
238             *
239             * <p>
240             * This method checks for the view permission when counting the container
241             * models.
242             * </p>
243             *
244             * @param  classPK the primary key of a model entity the container models
245             *         must be able to contain
246             * @param  containerModelId the primary key of the parent container model
247             * @return the number of matching container models
248             * @throws PortalException if a model entity with the primary key could not
249             *         be found
250             * @throws SystemException if a system exception occurred
251             */
252            public int getContainerModelsCount(long classPK, long containerModelId)
253                    throws PortalException, SystemException;
254    
255            /**
256             * Returns the language key to the localized message to display next to a
257             * trash entry listed in a search result, indicating that the trash entry
258             * was found in a trashed container (e.g. folder or message board thread)
259             * this trash handler is associated with.
260             *
261             * <p>
262             * If the language key (e.g. <code>found-in-deleted-folder-x</code>) used
263             * accepts a single parameter, the trash framework replaces that parameter
264             * with the trashed container's name.
265             * </p>
266             *
267             * @return the language key to the localized message to display next to a
268             *         trash entry listed in a search result
269             */
270            public String getDeleteMessage();
271    
272            /**
273             * Returns the link to the location to which the model entity was restored.
274             *
275             * @param  portletRequest the portlet request
276             * @param  classPK the primary key of the restored model entity
277             * @return the restore link
278             * @throws PortalException if a model entity with the primary key could not
279             *         be found
280             * @throws SystemException if a system exception occurred
281             */
282            public String getRestoreLink(PortletRequest portletRequest, long classPK)
283                    throws PortalException, SystemException;
284    
285            /**
286             * Returns the message describing the location to which the model entity was
287             * restored.
288             *
289             * @param  portletRequest the portlet request
290             * @param  classPK the primary key of the restored model entity
291             * @return the restore message
292             * @throws PortalException if a model entity with the primary key could not
293             *         be found
294             * @throws SystemException if a system exception occurred
295             */
296            public String getRestoreMessage(PortletRequest portletRequest, long classPK)
297                    throws PortalException, SystemException;
298    
299            /**
300             * Returns the name of the root container (e.g. "home").
301             *
302             * @return the name of the root container
303             */
304            public String getRootContainerModelName();
305    
306            /**
307             * Returns the name of the sub-container model (e.g. for a folder the
308             * sub-container model name may be "subfolder").
309             *
310             * @return the name of the sub-container model
311             */
312            public String getSubcontainerModelName();
313    
314            /**
315             * Returns the trash renderer associated to the model entity with the
316             * primary key.
317             *
318             * @param  classPK the primary key of the model entity
319             * @return the trash renderer associated to the model entity
320             * @throws PortalException if a model entity with the primary key could not
321             *         be found
322             * @throws SystemException if a system exception occurred
323             */
324            public TrashRenderer getTrashRenderer(long classPK)
325                    throws PortalException, SystemException;
326    
327            /**
328             * Returns <code>true</code> if the user has the required permission to
329             * perform the trash action on the model entity with the primary key.
330             *
331             * <p>
332             * This method is a mapper for special Recycle Bin operations that are not
333             * real permissions. The implementations of this method should translate
334             * these virtual permissions to real permission checks.
335             * </p>
336             *
337             * @param  permissionChecker the permission checker
338             * @param  groupId the primary key of the group
339             * @param  classPK the primary key of the model entity
340             * @param  trashActionId the trash action permission to check
341             * @return <code>true</code> if the user has the required permission;
342             *         <code>false</code> otherwise
343             * @throws PortalException if a model entity with the primary key could not
344             *         be found
345             * @throws SystemException if a system exception occurred
346             */
347            public boolean hasTrashPermission(
348                            PermissionChecker permissionChecker, long groupId, long classPK,
349                            String trashActionId)
350                    throws PortalException, SystemException;
351    
352            /**
353             * Returns <code>true</code> if the model entity with the primary key is in
354             * the Recycle Bin.
355             *
356             * @param  classPK the primary key of the model entity
357             * @return <code>true</code> if the model entity is in the Recycle Bin;
358             *         <code>false</code> otherwise
359             * @throws PortalException if a model entity with the primary key could not
360             *         be found in the portal
361             * @throws SystemException if a system exception occurred
362             */
363            public boolean isInTrash(long classPK)
364                    throws PortalException, SystemException;
365    
366            /**
367             * Returns <code>true</code> if the model entity can be restored to its
368             * original location.
369             *
370             * <p>
371             * This method usually returns <code>false</code> if the container (e.g.
372             * folder) of the model entity is no longer available (e.g. moved to the
373             * Recycle Bin or deleted).
374             * </p>
375             *
376             * @param  classPK the primary key of the model entity
377             * @return <code>true</code> if the model entity can be restored to its
378             *         original location; <code>false</code> otherwise
379             * @throws PortalException if a model entity with the primary key could not
380             *         be found
381             * @throws SystemException if a system exception occurred
382             */
383            public boolean isRestorable(long classPK)
384                    throws PortalException, SystemException;
385    
386            /**
387             * Moves the model entity with the primary key out of the Recycle Bin to a
388             * new destination identified by the container model ID.
389             *
390             * @param  classPK the primary key of the model entity
391             * @param  containerModelId the primary key of the destination container
392             *         model
393             * @param  serviceContext the service context
394             * @return the moved model entity
395             * @throws PortalException if a model entity with the primary key or the
396             *         destination container model with the primary key could not be
397             *         found
398             * @throws SystemException if a system exception occurred
399             */
400            public TrashEntry moveTrashEntry(
401                            long classPK, long containerModelId, ServiceContext serviceContext)
402                    throws PortalException, SystemException;
403    
404            /**
405             * Restores all the model entities with the primary keys.
406             *
407             * @param  classPKs the primary keys of the model entities to restore
408             * @throws PortalException if any one of the model entities could not be
409             *         found
410             * @throws SystemException if a system exception occurred
411             */
412            public void restoreTrashEntries(long[] classPKs)
413                    throws PortalException, SystemException;
414    
415            /**
416             * Restores the model entity with the primary key.
417             *
418             * @param  classPK the primary key of the model entity to restore
419             * @throws PortalException if a model entity with the primary key could not
420             *         be found
421             * @throws SystemException if a system exception occurred
422             */
423            public void restoreTrashEntry(long classPK)
424                    throws PortalException, SystemException;
425    
426            /**
427             * Updates the title of the model entity with the primary key. This method
428             * is called by {@link com.liferay.portlet.trash.action.EditEntryAction}
429             * before restoring the model entity via its restore rename action.
430             *
431             * @param  classPK the primary key of the model entity
432             * @param  title the title to be assigned
433             * @throws PortalException if a model entity with the primary key could not
434             *         be found
435             * @throws SystemException if a system exception occurred
436             */
437            public void updateTitle(long classPK, String title)
438                    throws PortalException, SystemException;
439    
440    }