Forum


1   /**
2    * Copyright (C) 2001 Yasna.com. All rights reserved.
3    *
4    * ===================================================================
5    * The Apache Software License, Version 1.1
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *       "This product includes software developed by
22   *        Yasna.com (http://www.yasna.com)."
23   *    Alternately, this acknowledgment may appear in the software itself,
24   *    if and wherever such third-party acknowledgments normally appear.
25   *
26   * 4. The names "Yazd" and "Yasna.com" must not be used to
27   *    endorse or promote products derived from this software without
28   *    prior written permission. For written permission, please
29   *    contact yazd@yasna.com.
30   *
31   * 5. Products derived from this software may not be called "Yazd",
32   *    nor may "Yazd" appear in their name, without prior written
33   *    permission of Yasna.com.
34   *
35   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38   * DISCLAIMED.  IN NO EVENT SHALL YASNA.COM OR
39   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46   * SUCH DAMAGE.
47   * ====================================================================
48   *
49   * This software consists of voluntary contributions made by many
50   * individuals on behalf of Yasna.com. For more information
51   * on Yasna.com, please see <http://www.yasna.com>.
52   */
53  
54  /**
55   * Copyright (C) 2000 CoolServlets.com. All rights reserved.
56   *
57   * ===================================================================
58   * The Apache Software License, Version 1.1
59   *
60   * Redistribution and use in source and binary forms, with or without
61   * modification, are permitted provided that the following conditions
62   * are met:
63   *
64   * 1. Redistributions of source code must retain the above copyright
65   *    notice, this list of conditions and the following disclaimer.
66   *
67   * 2. Redistributions in binary form must reproduce the above copyright
68   *    notice, this list of conditions and the following disclaimer in
69   *    the documentation and/or other materials provided with the
70   *    distribution.
71   *
72   * 3. The end-user documentation included with the redistribution,
73   *    if any, must include the following acknowledgment:
74   *       "This product includes software developed by
75   *        CoolServlets.com (http://www.coolservlets.com)."
76   *    Alternately, this acknowledgment may appear in the software itself,
77   *    if and wherever such third-party acknowledgments normally appear.
78   *
79   * 4. The names "Jive" and "CoolServlets.com" must not be used to
80   *    endorse or promote products derived from this software without
81   *    prior written permission. For written permission, please
82   *    contact webmaster@coolservlets.com.
83   *
84   * 5. Products derived from this software may not be called "Jive",
85   *    nor may "Jive" appear in their name, without prior written
86   *    permission of CoolServlets.com.
87   *
88   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
89   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
90   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
91   * DISCLAIMED.  IN NO EVENT SHALL COOLSERVLETS.COM OR
92   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
93   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
94   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
95   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
96   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
97   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
98   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
99   * SUCH DAMAGE.
100  * ====================================================================
101  *
102  * This software consists of voluntary contributions made by many
103  * individuals on behalf of CoolServlets.com. For more information
104  * on CoolServlets.com, please see <http://www.coolservlets.com>.
105  */
106 
107 package com.Yasna.forum;
108 
109 import com.Yasna.forum.Exceptions.RapidPostingException;
110 import com.Yasna.forum.Exceptions.UserBlackListedException;
111 import com.Yasna.forum.util.ClientIP;
112 
113 import java.util.Date  ;
114 import java.util.Iterator  ;
115 import java.util.Enumeration  ;
116 
117 /**
118  * A top level container for discussions. It contains a list of threads, each
119  * of which contains a tree of messages.
120  */
121 public interface Forum {
122 
123    //used for sorting the threads
124     public static final int SORT_BY_CREATE_DATE = 0;
125     public static final int SORT_BY_MODIFIED_DATE = 1;
126 
127     /**
128      * Returns the unique id of the forum.
129      *
130      * @return the unique id of the forum.
131      */
132     public int getID();
133 
134     /**
135      * Returns the name of the forum. Every forum name in the system must be
136      * unique. However, this restriction allows one to lookup a forum by name
137      * as well as by ID.
138      *
139      * @return the name of the forum.
140      * @see ForumFactory#getForum(String)
141      */
142     public String   getName();
143 
144     /**
145      * Sets the name of a the forum. Every forum name in the system must be
146      * unique. However, this restriction allows one to lookup a forum by name
147      * as well as by ID.<p>
148      *
149      * An exception will be thrown if a forum with the same name as the new
150      * name already exists.
151      *
152      * @param name the name of the forum.
153      * @throws UnauthorizedException if does not have ADMIN permissions.
154      * @throws ForumAlreadyExistsException if a forum with the specified name
155      *      already exists.
156      */
157     public void setName(String   name) throws UnauthorizedException,
158             ForumAlreadyExistsException;
159 
160     /**
161      * Returns the description of the forum.
162      *
163      * @return the description of the forum.
164      */
165     public String   getDescription();
166 
167     /**
168      * Sets the description of the forum.
169      *
170      * @param description the description of the forum.
171      * @throws UnauthorizedException if does not have ADMIN permissions.
172      */
173     public void setDescription(String   description) throws UnauthorizedException;
174 
175     /**
176      * Returns the Date that the forum was created.
177      *
178      * @return the Date the forum was created.
179      */
180     public Date   getCreationDate();
181 
182     /**
183      * Sets the creation date of the forum. In most cases, the creation date
184      * will default to when the forum was entered into the system. However,
185      * the creation date needs to be set manually when importing data.
186      * In other words, skin authors should ignore this method since it only
187      * intended for system maintenance.
188      *
189      * @param creationDate the date the forum was created.
190      * @throws UnauthorizedException if does not have ADMIN permissions.
191      */
192     public void setCreationDate(Date   creationDate) throws UnauthorizedException;
193 
194     /**
195      * Returns the Date that the forum was last modified. In other words, the
196      * date of the most recent message or thread in the forum.
197      *
198      * @return the Date the forum was last modified.
199      */
200     public Date   getModifiedDate();
201 
202     /**
203      * Sets the date the forum was last modified. In most cases, last modifed
204      * will default to when the forum data was last changed. However,
205      * the last modified date needs to be set manually when importing data.
206      * In other words, skin authors should ignore this method since it only
207      * intended for system maintenance.
208      *
209      * @param modifiedDate the date the forum was modified.
210      * @throws UnauthorizedException if does not have ADMIN permissions.
211      */
212     public void setModifiedDate(Date   modifiedDate) throws UnauthorizedException;
213 
214     /**
215      * Returns an extended property of the forum. Each forum can have an
216      * arbitrary number of extended properties. This allows for enhanced
217      * functionality that is not part of the base interface.
218      *
219      * @param name the name of the property to get.
220      */
221     public String   getProperty(String   name);
222 
223     /**
224      * Sets an extended property of the forum. Each forum can have an
225      * arbitrary number of extended properties. This allows for enhanced
226      * functionality that is not part of the base interface.
227      *
228      * @param name the name of the property to set.
229      * @param value the new value for the property.
230      */
231     public void setProperty(String   name, String   value) throws UnauthorizedException;
232 
233     /**
234      * Returns an Enumeration of all the names of the forum properties.
235      *
236      * @return an Enumeration of all the names of the forum properties.
237      */
238     public Enumeration   propertyNames();
239 
240     /**
241      * Returns true if this forum is moderated. When a forum is moderated,
242      * posted messages and threads must first be approved by a user with
243      * moderator permissions.<p>
244      *
245      * @return true if the forum is moderated.
246      */
247     public boolean isModerated();
248 
249     /**
250      * Sets whether the forum is moderated. When a forum is moderated,
251      * posted messages and threads must first be approved by a user with
252      * moderator permissions.<p>
253      *
254      *
255      * @param moderated when true forum is moderated
256      * @throws UnauthorizedException if does not have ADMIN permissions.
257      */
258     public void setModerated(boolean moderated)
259             throws UnauthorizedException;
260 
261     /**
262      * Factory method to create a Thread.
263      *
264      * @param rootMessage the root message of the thread.
265      *
266      * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
267      */
268     public abstract ForumThread createThread(ForumMessage rootMessage,ThreadType type) throws
269             UnauthorizedException;
270 
271     /**
272      * Factory method to create a Message.
273      *
274      * @param user the user for the message.
275      * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
276      */
277     public abstract ForumMessage createMessage(User user,ClientIP clientIP)
278             throws UnauthorizedException,RapidPostingException, UserBlackListedException;
279     /**
280      * Factory method to create a Dummy Message. This is used to display how
281      * a message looks after it is filtered.
282      *
283      * @param user the user for the message.
284      * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
285      */
286     public abstract ForumMessage createDummyMessage(User user)
287             throws UnauthorizedException;
288 
289     /**
290      * Adds a thread to the forum.
291      *
292      * @param thread the thread to add to the forum.
293      * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
294      */
295     public void addThread(ForumThread thread) throws UnauthorizedException;
296 
297     /**
298      * Deletes a thread. Once a thread is deleted, the thread object should
299      * no longer be used.
300      *
301      * @param thread the thread to delete.
302      * @throws UnauthorizedException if does not have ADMIN permissions.
303      */
304     public void deleteThread(ForumThread thread) throws UnauthorizedException;
305 
306     /**
307      * Moves a thread from one forum to another. For this to work, the thread
308      * must exist in the forum that this method is invoked on, and the user
309      * calling this method must have ADMIN permissions for the forum this method
310      * is invoked on and <code>newForum</code>.<p>
311      *
312      * The main purpose of this method is to allow admins to move non-topical
313      * threads into a more appropriate forum.
314      *
315      * @param thread the thread to move to another forum.
316      * @param newForum the forum to move the thread to.
317      * @throws UnauthorizedException if does not have ADMIN permissions for the
318      *      this forum and <code>newForum</code>.
319      * @throws IllegalArgumentException if <code>thread</code> does not belong
320      *      to the forum that this method was invoked on.
321      */
322     public void moveThread(ForumThread thread, Forum newForum)
323             throws UnauthorizedException, IllegalArgumentException  ;
324 
325     /**
326      * Returns the thread specified by id. The method will return null
327      * if the thread is not in the forum.
328      */
329     public ForumThread getThread(int threadID)
330             throws ForumThreadNotFoundException;
331 
332     /**
333      * Returns a Iterator for the forum to move through the threads.
334      */
335     public Iterator   threads();
336 
337     /**
338      * Returns a ListIterator for the forum to move through the threads.
339      *
340      * @param startIndex the index you'd like to start the iterator at.
341      * @param sortBy used to sort messages - create/modified date.
342      */
343     public Iterator   threads(int startIndex, int numResults, int sortBy);
344 
345     /**
346      * Returns the number of threads in the forum.
347      */
348     public int getThreadCount();
349 
350     /**
351      * Returns the number of messages in the forum.
352      */
353     public int getMessageCount();
354 
355     /**
356      * Creates a query object to search the forum. This method is considered
357      * a first stab at searching in Yazd, and will almost certainly be
358      * modified in the near future.
359      */
360     public Query createQuery();
361 
362     /**
363      * Grants a user a particular permission for the forum. Valid permission
364      * types for a forum are <code>ForumPermissions.ADMIN</code>
365      *
366      * @param user the User to grant a permission to.
367      * @param permissionType the type of permission to grant the user.
368      * @throws UnauthorizedException if does not have ADMIN permissions.
369      */
370     public void addUserPermission(User user, int permissionType)
371             throws UnauthorizedException;
372 
373     /**
374      * Revokes a particular permission from a user for the forum.
375      *
376      * @param user the User to revoke a permission from.
377      * @param permissionType the type of permission to revoke from the user.
378      * @throws UnauthorizedException if does not have ADMIN permissions.
379      * @see ForumPermissions
380      */
381     public void removeUserPermission(User user, int permissionType)
382             throws UnauthorizedException;
383 
384     /**
385      * Returns all the userID's of users with a particular permission.
386      *
387      * @param permissionType the type of permission to check.
388      * @throws UnauthorizedException if does not have ADMIN permissions.
389      * @see ForumPermissions
390      */
391     public int [] usersWithPermission(int permissionType)
392             throws UnauthorizedException;
393 
394     /**
395      * Grants a group a particular permission for the forum.
396      *
397      * @throws UnauthorizedException if does not have ADMIN permissions.
398      * @see ForumPermissions
399      */
400     public void addGroupPermission(Group group, int permissionType)
401             throws UnauthorizedException;
402 
403     /**
404      * Revokes a particular permission from a group for the forum.
405      *
406      * @throws UnauthorizedException if does not have ADMIN permissions.
407      */
408     public void removeGroupPermission(Group group, int permissionType)
409             throws UnauthorizedException;
410 
411     /**
412      * Returns all the groupID's of groups with a particular permission.
413      *
414      * @throws UnauthorizedException if does not have ADMIN permissions.
415      */
416     public int[] groupsWithPermission(int permissionType)
417             throws UnauthorizedException;
418 
419     /**
420      * Applies all of the currently active filters to a message.
421      *
422      * @param message the ForumMessage to apply filters to.
423      */
424     public ForumMessage applyFilters(ForumMessage message);
425 
426     /**
427      * Returns an array of the currently active ForumMessageFilters.
428      *
429      * @throws UnauthorizedException if does not have ADMIN permissions.
430      */
431     public ForumMessageFilter[] getForumMessageFilters()
432             throws UnauthorizedException;
433 
434     /**
435      * Adds a new ForumMessageFilter to the end of the filter list.
436      *
437      * @param filter ForumMessageFilter to add to the filter list.
438      *
439      * @throws UnauthorizedException if does not have ADMIN permissions.
440      */
441     public void addForumMessageFilter(ForumMessageFilter filter)
442             throws UnauthorizedException;
443 
444     /**
445      * Inserts a new ForumMessageFilter at specified index in the filter list.
446      *
447      * @param filter ForumMessageFilter to add to the filter list.
448      * @param index position in filter list to insert new filter.
449      *
450      * @throws UnauthorizedException if does not have ADMIN permissions.
451      */
452     public void addForumMessageFilter(ForumMessageFilter filter, int index)
453             throws UnauthorizedException;
454 
455     /**
456      * Removes a ForumMessageFilter at the specified index in the filter list.
457      *
458      * @param index position in filter list to remove filter from.
459      *
460      * @throws UnauthorizedException if does not have ADMIN permissions.
461      */
462     public void removeForumMessageFilter(int index)
463             throws UnauthorizedException;
464 
465     /**
466      * Returns the permissions for the forum that correspond to the
467      * passed-in Authorization.
468      *
469      * @param authorization the auth token to lookup permissions for.
470      */
471     public abstract ForumPermissions getPermissions(Authorization authorization);
472 
473     /**
474      * Returns true if the handle on the object has the permission specified.
475      * A list of possible permissions can be found in the ForumPermissions
476      * class. Certain methods of this class are restricted to certain
477      * permissions as specified in the method comments.
478      *
479      * @see ForumPermissions
480      */
481     public boolean hasPermission(int type);
482 
483     /**
484      * This method returns true if this forum is used for discussions around an article page.
485      * @return true if this forum is for articles
486      */
487     public boolean isArticleForum();
488 
489     public void addArticleMap(String   pageKey,ForumThread thread) throws UnauthorizedException;
490     public int forumOrder();
491     public void setForumOrder(int param) throws UnauthorizedException;
492 
493 }
494 
495 
496
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags