KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > nemesis > forum > Forum


1 /*
2  * NEMESIS-FORUM.
3  * Copyright (C) 2002 David Laurent(lithium2@free.fr). All rights reserved.
4  *
5  * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
6  *
7  * Copyright (C) 2001 Yasna.com. All rights reserved.
8  *
9  * Copyright (C) 2000 CoolServlets.com. All rights reserved.
10  *
11  * NEMESIS-FORUM. is free software; you can redistribute it and/or
12  * modify it under the terms of the Apache Software License, Version 1.1,
13  * or (at your option) any later version.
14  *
15  * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
16  * application are parts of NEMESIS-FORUM and are distributed under
17  * same terms of licence.
18  *
19  *
20  * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
21  * and software developed by CoolServlets.com (http://www.coolservlets.com).
22  * and software developed by Yasna.com (http://www.yasna.com).
23  *
24  */

25
26 package org.nemesis.forum;
27
28 import java.util.Date JavaDoc;
29 import java.util.Enumeration JavaDoc;
30 import java.util.Iterator JavaDoc;
31
32 import org.nemesis.forum.exception.ForumAlreadyExistsException;
33 import org.nemesis.forum.exception.ForumMessageNotFoundException;
34 import org.nemesis.forum.exception.ForumThreadNotFoundException;
35 import org.nemesis.forum.exception.UnauthorizedException;
36
37
38 /**
39  * A top level container for discussions. It contains a list of threads, each
40  * of which contains a tree of messages.
41  */

42 public interface Forum {
43
44     /**
45      * Returns the unique id of the forum.
46      *
47      * @return the unique id of the forum.
48      */

49     public int getID();
50
51     /**
52      * Returns the name of the forum. Every forum name in the system must be
53      * unique. However, this restriction allows one to lookup a forum by name
54      * as well as by ID.
55      *
56      * @return the name of the forum.
57      * @see ForumFactory#getForum(String)
58      */

59     public String JavaDoc getName();
60
61     /**
62      * Sets the name of a the forum. Every forum name in the system must be
63      * unique. However, this restriction allows one to lookup a forum by name
64      * as well as by ID.<p>
65      *
66      * An exception will be thrown if a forum with the same name as the new
67      * name already exists.
68      *
69      * @param name the name of the forum.
70      * @throws UnauthorizedException if does not have ADMIN permissions.
71      * @throws ForumAlreadyExistsException if a forum with the specified name
72      * already exists.
73      */

74     public void setName(String JavaDoc name) throws UnauthorizedException,
75             ForumAlreadyExistsException;
76
77     /**
78      * Returns the description of the forum.
79      *
80      * @return the description of the forum.
81      */

82     public String JavaDoc getDescription();
83
84     /**
85      * Sets the description of the forum.
86      *
87      * @param description the description of the forum.
88      * @throws UnauthorizedException if does not have ADMIN permissions.
89      */

90     public void setDescription(String JavaDoc description) throws UnauthorizedException;
91
92     /**
93      * Returns the Date that the forum was created.
94      *
95      * @return the Date the forum was created.
96      */

97     public Date JavaDoc getCreationDate();
98
99     /**
100      * Sets the creation date of the forum. In most cases, the creation date
101      * will default to when the forum was entered into the system. However,
102      * the creation date needs to be set manually when importing data.
103      * In other words, skin authors should ignore this method since it only
104      * intended for system maintenance.
105      *
106      * @param creationDate the date the forum was created.
107      * @throws UnauthorizedException if does not have ADMIN permissions.
108      */

109     public void setCreationDate(Date JavaDoc creationDate) throws UnauthorizedException;
110
111     /**
112      * Returns the Date that the forum was last modified. In other words, the
113      * date of the most recent message or thread in the forum.
114      *
115      * @return the Date the forum was last modified.
116      */

117     public Date JavaDoc getModifiedDate();
118
119     /**
120      * Sets the date the forum was last modified. In most cases, last modifed
121      * will default to when the forum data was last changed. However,
122      * the last modified date needs to be set manually when importing data.
123      * In other words, skin authors should ignore this method since it only
124      * intended for system maintenance.
125      *
126      * @param modifiedDate the date the forum was modified.
127      * @throws UnauthorizedException if does not have ADMIN permissions.
128      */

129     public void setModifiedDate(Date JavaDoc modifiedDate) throws UnauthorizedException;
130     
131     public Message getMessage(int messageID) throws ForumMessageNotFoundException;
132     
133     
134     /**
135      * Returns an extended property of the forum. Each forum can have an
136      * arbitrary number of extended properties. This allows for enhanced
137      * functionality that is not part of the base interface.
138      *
139      * @param name the name of the property to get.
140      * @param the value of the property specified by name.
141      */

142     public String JavaDoc getProperty(String JavaDoc name);
143
144     /**
145      * Sets an extended property of the forum. Each forum can have an
146      * arbitrary number of extended properties. This allows for enhanced
147      * functionality that is not part of the base interface.
148      *
149      * @param name the name of the property to set.
150      * @param value the new value for the property.
151      */

152     public void setProperty(String JavaDoc name, String JavaDoc value) throws UnauthorizedException;
153
154     /**
155      * Returns an Enumeration of all the names of the forum properties.
156      *
157      * @return an Enumeration of all the names of the forum properties.
158      */

159     public Enumeration JavaDoc propertyNames();
160
161     /**
162      * Returns true if this forum is moderated. When a forum is moderated,
163      * posted messages and threads must first be approved by a user with
164      * moderator permissions.<p>
165      *
166      * @return Constants.MODERATION_THREAD
167      * or Constants.MODERATION_MESSAGE or Constants.MODERATION_NONE
168      */

169     public int getModerationType();
170
171     /**
172      * Sets whether the forum is moderated. When a forum is moderated,
173      * posted messages and threads must first be approved by a user with
174      * moderator permissions.<p>
175      *
176      * @param type should be either Constants.MODERATION_THREAD
177      * or Constants.MODERATION_MESSAGE
178      * or Constants.MODERATION_NONE
179      * @throws UnauthorizedException if does not have ADMIN permissions.
180      */

181     public void setModerationType(int type)
182             throws UnauthorizedException;
183
184     /**
185      * Factory method to create a Thread.
186      *
187      * @param forum the forum to create the thread in.
188      * @param rootMessage the root message of the thread.
189      *
190      * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
191      */

192     public abstract ForumThread createThread(Message rootMessage) throws
193             UnauthorizedException;
194
195     /**
196      * Factory method to create a Message.
197      *
198      * @param user the user for the message.
199      * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
200      */

201     public abstract Message createMessage(User user)
202             throws UnauthorizedException;
203
204     /**
205      * Adds a thread to the forum.
206      *
207      * @param thread the thread to add to the forum.
208      * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
209      */

210     public void addThread(ForumThread thread) throws UnauthorizedException;
211
212     /**
213      * Deletes a thread. Once a thread is deleted, the thread object should
214      * no longer be used.
215      *
216      * @param thread the thread to delete.
217      * @throws UnauthorizedException if does not have ADMIN permissions.
218      */

219     public void deleteThread(ForumThread thread) throws UnauthorizedException;
220
221     /**
222      * Moves a thread from one forum to another. For this to work, the thread
223      * must exist in the forum that this method is invoked on, and the user
224      * calling this method must have ADMIN permissions for the forum this method
225      * is invoked on and <code>newForum</code>.<p>
226      *
227      * The main purpose of this method is to allow admins to move non-topical
228      * threads into a more appropriate forum.
229      *
230      * @param thread the thread to move to another forum.
231      * @param newForum the forum to move the thread to.
232      * @throws UnauthorizedException if does not have ADMIN permissions for the
233      * this forum and <code>newForum</code>.
234      * @throws IllegalArgumentException if <code>thread</code> does not belong
235      * to the forum that this method was invoked on.
236      */

237     public void moveThread(ForumThread thread, Forum newForum)
238             throws UnauthorizedException, IllegalArgumentException JavaDoc;
239
240     /**
241      * Returns the thread specified by id. The method will return null
242      * if the thread is not in the forum.
243      */

244     public ForumThread getThread(int threadID)
245             throws ForumThreadNotFoundException;
246     
247     
248     /**
249      * Returns a Iterator for the forum to move through the threads.
250      */

251     public Iterator JavaDoc threads();
252     
253     /**
254      * Returns a Iterator for the forum to move through the threads.
255      */

256     public Iterator JavaDoc threads(boolean approved);
257
258     /**
259      * Returns a ListIterator for the forum to move through the threads.
260      *
261      * @param startIndex the index you'd like to start the iterator at.
262      * @param numResuls the max number of results iterator will hold.
263      */

264     public Iterator JavaDoc threads(int startIndex, int numResults);
265     
266     /**
267      * Returns a ListIterator for the forum to move through the threads.
268      *
269      * @param startIndex the index you'd like to start the iterator at.
270      * @param numResuls the max number of results iterator will hold.
271      */

272     public Iterator JavaDoc threads(boolean approved,int startIndex, int numResults);
273
274     /**
275      * Returns the number of threads in the forum.
276      */

277     public int getThreadCount();
278
279     /**
280      * Returns the number of messages in the forum.
281      */

282     public int getMessageCount();
283     
284     /**
285      * @author dlaurent
286      * Returns the number of messages in the forum.
287      * approved or not
288      */

289     public int getMessageCount(boolean approved);
290     
291
292
293     
294     /**
295      * @author dlaurent
296      * Returns the number of messages in the forum.
297      * approved or not
298      */

299     public int getThreadCount(boolean approved);
300
301
302
303     /**
304      * Grants a user a particular permission for the forum. Valid permission
305      * types for a forum are <code>ForumPermissions.ADMIN</code>
306      *
307      * @param user the User to grant a permission to.
308      * @param permissionType the type of permission to grant the user.
309      * @throws UnauthorizedException if does not have ADMIN permissions.
310      */

311     public void addUserPermission(User user, int permissionType)
312             throws UnauthorizedException;
313
314     /**
315      * Revokes a particular permission from a user for the forum.
316      *
317      * @param user the User to revoke a permission from.
318      * @param permissionType the type of permission to revoke from the user.
319      * @throws UnauthorizedException if does not have ADMIN permissions.
320      * @see ForumPermissions
321      */

322     public void removeUserPermission(User user, int permissionType)
323             throws UnauthorizedException;
324
325     /**
326      * Returns all the userID's of users with a particular permission.
327      *
328      * @param permissionType the type of permission to check.
329      * @throws UnauthorizedException if does not have ADMIN permissions.
330      * @see ForumPermissions
331      */

332     public int [] usersWithPermission(int permissionType)
333             throws UnauthorizedException;
334
335     /**
336      * Grants a group a particular permission for the forum.
337      *
338      * @throws UnauthorizedException if does not have ADMIN permissions.
339      * @see ForumPermissions
340      */

341     public void addGroupPermission(Group group, int permissionType)
342             throws UnauthorizedException;
343
344     /**
345      * Revokes a particular permission from a group for the forum.
346      *
347      * @throws UnauthorizedException if does not have ADMIN permissions.
348      */

349     public void removeGroupPermission(Group group, int permissionType)
350             throws UnauthorizedException;
351
352     /**
353      * Returns all the groupID's of groups with a particular permission.
354      *
355      * @throws UnauthorizedException if does not have ADMIN permissions.
356      */

357     public int[] groupsWithPermission(int permissionType)
358             throws UnauthorizedException;
359
360     /**
361      * Applies all of the currently active filters to a message.
362      *
363      * @param message the ForumMessage to apply filters to.
364      */

365     public Message applyFilters(Message message);
366
367     /**
368      * Returns an array of the currently active ForumMessageFilters.
369      *
370      * @throws UnauthorizedException if does not have ADMIN permissions.
371      */

372     public MessageFilter[] getForumMessageFilters()
373             throws UnauthorizedException;
374
375     /**
376      * Adds a new ForumMessageFilter to the end of the filter list.
377      *
378      * @param filter ForumMessageFilter to add to the filter list.
379      *
380      * @throws UnauthorizedException if does not have ADMIN permissions.
381      */

382     public void addForumMessageFilter(MessageFilter filter)
383             throws UnauthorizedException;
384
385     /**
386      * Inserts a new ForumMessageFilter at specified index in the filter list.
387      *
388      * @param filter ForumMessageFilter to add to the filter list.
389      * @param index position in filter list to insert new filter.
390      *
391      * @throws UnauthorizedException if does not have ADMIN permissions.
392      */

393     public void addForumMessageFilter(MessageFilter filter, int index)
394             throws UnauthorizedException;
395
396     /**
397      * Removes a ForumMessageFilter at the specified index in the filter list.
398      *
399      * @param index position in filter list to remove filter from.
400      *
401      * @throws UnauthorizedException if does not have ADMIN permissions.
402      */

403     public void removeForumMessageFilter(int index)
404             throws UnauthorizedException;
405
406     /**
407      * Returns the permissions for the forum that correspond to the
408      * passed-in Authorization.
409      *
410      * @param authorization the auth token to lookup permissions for.
411      */

412     public abstract ForumPermissions getPermissions(Authorization authorization);
413
414     /**
415      * Returns true if the handle on the object has the permission specified.
416      * A list of possible permissions can be found in the ForumPermissions
417      * class. Certain methods of this class are restricted to certain
418      * permissions as specified in the method comments.
419      *
420      * @see ForumPermissions
421      */

422     public boolean hasPermission(int type);
423 }
424
425
426
Popular Tags