001: /**
002: * Copyright (C) 2001 Yasna.com. All rights reserved.
003: *
004: * ===================================================================
005: * The Apache Software License, Version 1.1
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The end-user documentation included with the redistribution,
020: * if any, must include the following acknowledgment:
021: * "This product includes software developed by
022: * Yasna.com (http://www.yasna.com)."
023: * Alternately, this acknowledgment may appear in the software itself,
024: * if and wherever such third-party acknowledgments normally appear.
025: *
026: * 4. The names "Yazd" and "Yasna.com" must not be used to
027: * endorse or promote products derived from this software without
028: * prior written permission. For written permission, please
029: * contact yazd@yasna.com.
030: *
031: * 5. Products derived from this software may not be called "Yazd",
032: * nor may "Yazd" appear in their name, without prior written
033: * permission of Yasna.com.
034: *
035: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL YASNA.COM OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: *
049: * This software consists of voluntary contributions made by many
050: * individuals on behalf of Yasna.com. For more information
051: * on Yasna.com, please see <http://www.yasna.com>.
052: */
053:
054: /**
055: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
056: *
057: * ===================================================================
058: * The Apache Software License, Version 1.1
059: *
060: * Redistribution and use in source and binary forms, with or without
061: * modification, are permitted provided that the following conditions
062: * are met:
063: *
064: * 1. Redistributions of source code must retain the above copyright
065: * notice, this list of conditions and the following disclaimer.
066: *
067: * 2. Redistributions in binary form must reproduce the above copyright
068: * notice, this list of conditions and the following disclaimer in
069: * the documentation and/or other materials provided with the
070: * distribution.
071: *
072: * 3. The end-user documentation included with the redistribution,
073: * if any, must include the following acknowledgment:
074: * "This product includes software developed by
075: * CoolServlets.com (http://www.coolservlets.com)."
076: * Alternately, this acknowledgment may appear in the software itself,
077: * if and wherever such third-party acknowledgments normally appear.
078: *
079: * 4. The names "Jive" and "CoolServlets.com" must not be used to
080: * endorse or promote products derived from this software without
081: * prior written permission. For written permission, please
082: * contact webmaster@coolservlets.com.
083: *
084: * 5. Products derived from this software may not be called "Jive",
085: * nor may "Jive" appear in their name, without prior written
086: * permission of CoolServlets.com.
087: *
088: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
089: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
090: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
091: * DISCLAIMED. IN NO EVENT SHALL COOLSERVLETS.COM OR
092: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
093: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
094: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
095: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
096: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
097: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
098: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
099: * 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: */package com.Yasna.forum;
106:
107: import com.Yasna.forum.Exceptions.RapidPostingException;
108: import com.Yasna.forum.Exceptions.UserBlackListedException;
109: import com.Yasna.forum.util.ClientIP;
110:
111: import java.util.Date;
112: import java.util.Iterator;
113: import java.util.Enumeration;
114:
115: /**
116: * A top level container for discussions. It contains a list of threads, each
117: * of which contains a tree of messages.
118: */
119: public interface Forum {
120:
121: //used for sorting the threads
122: public static final int SORT_BY_CREATE_DATE = 0;
123: public static final int SORT_BY_MODIFIED_DATE = 1;
124:
125: /**
126: * Returns the unique id of the forum.
127: *
128: * @return the unique id of the forum.
129: */
130: public int getID();
131:
132: /**
133: * Returns the name of the forum. Every forum name in the system must be
134: * unique. However, this restriction allows one to lookup a forum by name
135: * as well as by ID.
136: *
137: * @return the name of the forum.
138: * @see ForumFactory#getForum(String)
139: */
140: public String getName();
141:
142: /**
143: * Sets the name of a the forum. Every forum name in the system must be
144: * unique. However, this restriction allows one to lookup a forum by name
145: * as well as by ID.<p>
146: *
147: * An exception will be thrown if a forum with the same name as the new
148: * name already exists.
149: *
150: * @param name the name of the forum.
151: * @throws UnauthorizedException if does not have ADMIN permissions.
152: * @throws ForumAlreadyExistsException if a forum with the specified name
153: * already exists.
154: */
155: public void setName(String name) throws UnauthorizedException,
156: ForumAlreadyExistsException;
157:
158: /**
159: * Returns the description of the forum.
160: *
161: * @return the description of the forum.
162: */
163: public String getDescription();
164:
165: /**
166: * Sets the description of the forum.
167: *
168: * @param description the description of the forum.
169: * @throws UnauthorizedException if does not have ADMIN permissions.
170: */
171: public void setDescription(String description)
172: throws UnauthorizedException;
173:
174: /**
175: * Returns the Date that the forum was created.
176: *
177: * @return the Date the forum was created.
178: */
179: public Date getCreationDate();
180:
181: /**
182: * Sets the creation date of the forum. In most cases, the creation date
183: * will default to when the forum was entered into the system. However,
184: * the creation date needs to be set manually when importing data.
185: * In other words, skin authors should ignore this method since it only
186: * intended for system maintenance.
187: *
188: * @param creationDate the date the forum was created.
189: * @throws UnauthorizedException if does not have ADMIN permissions.
190: */
191: public void setCreationDate(Date creationDate)
192: 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)
213: throws UnauthorizedException;
214:
215: /**
216: * Returns an extended property of the forum. Each forum can have an
217: * arbitrary number of extended properties. This allows for enhanced
218: * functionality that is not part of the base interface.
219: *
220: * @param name the name of the property to get.
221: */
222: public String getProperty(String name);
223:
224: /**
225: * Sets an extended property of the forum. Each forum can have an
226: * arbitrary number of extended properties. This allows for enhanced
227: * functionality that is not part of the base interface.
228: *
229: * @param name the name of the property to set.
230: * @param value the new value for the property.
231: */
232: public void setProperty(String name, String value)
233: throws UnauthorizedException;
234:
235: /**
236: * Returns an Enumeration of all the names of the forum properties.
237: *
238: * @return an Enumeration of all the names of the forum properties.
239: */
240: public Enumeration propertyNames();
241:
242: /**
243: * Returns true if this forum is moderated. When a forum is moderated,
244: * posted messages and threads must first be approved by a user with
245: * moderator permissions.<p>
246: *
247: * @return true if the forum is moderated.
248: */
249: public boolean isModerated();
250:
251: /**
252: * Sets whether the forum is moderated. When a forum is moderated,
253: * posted messages and threads must first be approved by a user with
254: * moderator permissions.<p>
255: *
256: *
257: * @param moderated when true forum is moderated
258: * @throws UnauthorizedException if does not have ADMIN permissions.
259: */
260: public void setModerated(boolean moderated)
261: throws UnauthorizedException;
262:
263: /**
264: * Factory method to create a Thread.
265: *
266: * @param rootMessage the root message of the thread.
267: *
268: * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
269: */
270: public abstract ForumThread createThread(ForumMessage rootMessage,
271: ThreadType type) throws UnauthorizedException;
272:
273: /**
274: * Factory method to create a Message.
275: *
276: * @param user the user for the message.
277: * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
278: */
279: public abstract ForumMessage createMessage(User user,
280: ClientIP clientIP) throws UnauthorizedException,
281: RapidPostingException, UserBlackListedException;
282:
283: /**
284: * Factory method to create a Dummy Message. This is used to display how
285: * a message looks after it is filtered.
286: *
287: * @param user the user for the message.
288: * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
289: */
290: public abstract ForumMessage createDummyMessage(User user)
291: throws UnauthorizedException;
292:
293: /**
294: * Adds a thread to the forum.
295: *
296: * @param thread the thread to add to the forum.
297: * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
298: */
299: public void addThread(ForumThread thread)
300: throws UnauthorizedException;
301:
302: /**
303: * Deletes a thread. Once a thread is deleted, the thread object should
304: * no longer be used.
305: *
306: * @param thread the thread to delete.
307: * @throws UnauthorizedException if does not have ADMIN permissions.
308: */
309: public void deleteThread(ForumThread thread)
310: throws UnauthorizedException;
311:
312: /**
313: * Moves a thread from one forum to another. For this to work, the thread
314: * must exist in the forum that this method is invoked on, and the user
315: * calling this method must have ADMIN permissions for the forum this method
316: * is invoked on and <code>newForum</code>.<p>
317: *
318: * The main purpose of this method is to allow admins to move non-topical
319: * threads into a more appropriate forum.
320: *
321: * @param thread the thread to move to another forum.
322: * @param newForum the forum to move the thread to.
323: * @throws UnauthorizedException if does not have ADMIN permissions for the
324: * this forum and <code>newForum</code>.
325: * @throws IllegalArgumentException if <code>thread</code> does not belong
326: * to the forum that this method was invoked on.
327: */
328: public void moveThread(ForumThread thread, Forum newForum)
329: throws UnauthorizedException, IllegalArgumentException;
330:
331: /**
332: * Returns the thread specified by id. The method will return null
333: * if the thread is not in the forum.
334: */
335: public ForumThread getThread(int threadID)
336: throws ForumThreadNotFoundException;
337:
338: /**
339: * Returns a Iterator for the forum to move through the threads.
340: */
341: public Iterator threads();
342:
343: /**
344: * Returns a ListIterator for the forum to move through the threads.
345: *
346: * @param startIndex the index you'd like to start the iterator at.
347: * @param sortBy used to sort messages - create/modified date.
348: */
349: public Iterator threads(int startIndex, int numResults, int sortBy);
350:
351: /**
352: * Returns the number of threads in the forum.
353: */
354: public int getThreadCount();
355:
356: /**
357: * Returns the number of messages in the forum.
358: */
359: public int getMessageCount();
360:
361: /**
362: * Creates a query object to search the forum. This method is considered
363: * a first stab at searching in Yazd, and will almost certainly be
364: * modified in the near future.
365: */
366: public Query createQuery();
367:
368: /**
369: * Grants a user a particular permission for the forum. Valid permission
370: * types for a forum are <code>ForumPermissions.ADMIN</code>
371: *
372: * @param user the User to grant a permission to.
373: * @param permissionType the type of permission to grant the user.
374: * @throws UnauthorizedException if does not have ADMIN permissions.
375: */
376: public void addUserPermission(User user, int permissionType)
377: throws UnauthorizedException;
378:
379: /**
380: * Revokes a particular permission from a user for the forum.
381: *
382: * @param user the User to revoke a permission from.
383: * @param permissionType the type of permission to revoke from the user.
384: * @throws UnauthorizedException if does not have ADMIN permissions.
385: * @see ForumPermissions
386: */
387: public void removeUserPermission(User user, int permissionType)
388: throws UnauthorizedException;
389:
390: /**
391: * Returns all the userID's of users with a particular permission.
392: *
393: * @param permissionType the type of permission to check.
394: * @throws UnauthorizedException if does not have ADMIN permissions.
395: * @see ForumPermissions
396: */
397: public int[] usersWithPermission(int permissionType)
398: throws UnauthorizedException;
399:
400: /**
401: * Grants a group a particular permission for the forum.
402: *
403: * @throws UnauthorizedException if does not have ADMIN permissions.
404: * @see ForumPermissions
405: */
406: public void addGroupPermission(Group group, int permissionType)
407: throws UnauthorizedException;
408:
409: /**
410: * Revokes a particular permission from a group for the forum.
411: *
412: * @throws UnauthorizedException if does not have ADMIN permissions.
413: */
414: public void removeGroupPermission(Group group, int permissionType)
415: throws UnauthorizedException;
416:
417: /**
418: * Returns all the groupID's of groups with a particular permission.
419: *
420: * @throws UnauthorizedException if does not have ADMIN permissions.
421: */
422: public int[] groupsWithPermission(int permissionType)
423: throws UnauthorizedException;
424:
425: /**
426: * Applies all of the currently active filters to a message.
427: *
428: * @param message the ForumMessage to apply filters to.
429: */
430: public ForumMessage applyFilters(ForumMessage message);
431:
432: /**
433: * Returns an array of the currently active ForumMessageFilters.
434: *
435: * @throws UnauthorizedException if does not have ADMIN permissions.
436: */
437: public ForumMessageFilter[] getForumMessageFilters()
438: throws UnauthorizedException;
439:
440: /**
441: * Adds a new ForumMessageFilter to the end of the filter list.
442: *
443: * @param filter ForumMessageFilter to add to the filter list.
444: *
445: * @throws UnauthorizedException if does not have ADMIN permissions.
446: */
447: public void addForumMessageFilter(ForumMessageFilter filter)
448: throws UnauthorizedException;
449:
450: /**
451: * Inserts a new ForumMessageFilter at specified index in the filter list.
452: *
453: * @param filter ForumMessageFilter to add to the filter list.
454: * @param index position in filter list to insert new filter.
455: *
456: * @throws UnauthorizedException if does not have ADMIN permissions.
457: */
458: public void addForumMessageFilter(ForumMessageFilter filter,
459: int index) throws UnauthorizedException;
460:
461: /**
462: * Removes a ForumMessageFilter at the specified index in the filter list.
463: *
464: * @param index position in filter list to remove filter from.
465: *
466: * @throws UnauthorizedException if does not have ADMIN permissions.
467: */
468: public void removeForumMessageFilter(int index)
469: throws UnauthorizedException;
470:
471: /**
472: * Returns the permissions for the forum that correspond to the
473: * passed-in Authorization.
474: *
475: * @param authorization the auth token to lookup permissions for.
476: */
477: public abstract ForumPermissions getPermissions(
478: Authorization authorization);
479:
480: /**
481: * Returns true if the handle on the object has the permission specified.
482: * A list of possible permissions can be found in the ForumPermissions
483: * class. Certain methods of this class are restricted to certain
484: * permissions as specified in the method comments.
485: *
486: * @see ForumPermissions
487: */
488: public boolean hasPermission(int type);
489:
490: /**
491: * This method returns true if this forum is used for discussions around an article page.
492: * @return true if this forum is for articles
493: */
494: public boolean isArticleForum();
495:
496: public void addArticleMap(String pageKey, ForumThread thread)
497: throws UnauthorizedException;
498:
499: public int forumOrder();
500:
501: public void setForumOrder(int param) throws UnauthorizedException;
502:
503: }
|