001: /*
002: * NEMESIS-FORUM.
003: * Copyright (C) 2002 David Laurent(lithium2@free.fr). All rights reserved.
004: *
005: * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
006: *
007: * Copyright (C) 2001 Yasna.com. All rights reserved.
008: *
009: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
010: *
011: * NEMESIS-FORUM. is free software; you can redistribute it and/or
012: * modify it under the terms of the Apache Software License, Version 1.1,
013: * or (at your option) any later version.
014: *
015: * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
016: * application are parts of NEMESIS-FORUM and are distributed under
017: * same terms of licence.
018: *
019: *
020: * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
021: * and software developed by CoolServlets.com (http://www.coolservlets.com).
022: * and software developed by Yasna.com (http://www.yasna.com).
023: *
024: */
025:
026: package org.nemesis.forum;
027:
028: import java.util.Date;
029: import java.util.Enumeration;
030: import java.util.Iterator;
031:
032: import org.nemesis.forum.exception.ForumAlreadyExistsException;
033: import org.nemesis.forum.exception.ForumMessageNotFoundException;
034: import org.nemesis.forum.exception.ForumThreadNotFoundException;
035: import org.nemesis.forum.exception.UnauthorizedException;
036:
037: /**
038: * A top level container for discussions. It contains a list of threads, each
039: * of which contains a tree of messages.
040: */
041: public interface Forum {
042:
043: /**
044: * Returns the unique id of the forum.
045: *
046: * @return the unique id of the forum.
047: */
048: public int getID();
049:
050: /**
051: * Returns the name of the forum. Every forum name in the system must be
052: * unique. However, this restriction allows one to lookup a forum by name
053: * as well as by ID.
054: *
055: * @return the name of the forum.
056: * @see ForumFactory#getForum(String)
057: */
058: public String getName();
059:
060: /**
061: * Sets the name of a the forum. Every forum name in the system must be
062: * unique. However, this restriction allows one to lookup a forum by name
063: * as well as by ID.<p>
064: *
065: * An exception will be thrown if a forum with the same name as the new
066: * name already exists.
067: *
068: * @param name the name of the forum.
069: * @throws UnauthorizedException if does not have ADMIN permissions.
070: * @throws ForumAlreadyExistsException if a forum with the specified name
071: * already exists.
072: */
073: public void setName(String name) throws UnauthorizedException,
074: ForumAlreadyExistsException;
075:
076: /**
077: * Returns the description of the forum.
078: *
079: * @return the description of the forum.
080: */
081: public String getDescription();
082:
083: /**
084: * Sets the description of the forum.
085: *
086: * @param description the description of the forum.
087: * @throws UnauthorizedException if does not have ADMIN permissions.
088: */
089: public void setDescription(String description)
090: throws UnauthorizedException;
091:
092: /**
093: * Returns the Date that the forum was created.
094: *
095: * @return the Date the forum was created.
096: */
097: public Date getCreationDate();
098:
099: /**
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 creationDate)
110: throws UnauthorizedException;
111:
112: /**
113: * Returns the Date that the forum was last modified. In other words, the
114: * date of the most recent message or thread in the forum.
115: *
116: * @return the Date the forum was last modified.
117: */
118: public Date getModifiedDate();
119:
120: /**
121: * Sets the date the forum was last modified. In most cases, last modifed
122: * will default to when the forum data was last changed. However,
123: * the last modified date needs to be set manually when importing data.
124: * In other words, skin authors should ignore this method since it only
125: * intended for system maintenance.
126: *
127: * @param modifiedDate the date the forum was modified.
128: * @throws UnauthorizedException if does not have ADMIN permissions.
129: */
130: public void setModifiedDate(Date modifiedDate)
131: throws UnauthorizedException;
132:
133: public Message getMessage(int messageID)
134: throws ForumMessageNotFoundException;
135:
136: /**
137: * Returns an extended property of the forum. Each forum can have an
138: * arbitrary number of extended properties. This allows for enhanced
139: * functionality that is not part of the base interface.
140: *
141: * @param name the name of the property to get.
142: * @param the value of the property specified by name.
143: */
144: public String getProperty(String name);
145:
146: /**
147: * Sets an extended property of the forum. Each forum can have an
148: * arbitrary number of extended properties. This allows for enhanced
149: * functionality that is not part of the base interface.
150: *
151: * @param name the name of the property to set.
152: * @param value the new value for the property.
153: */
154: public void setProperty(String name, String value)
155: throws UnauthorizedException;
156:
157: /**
158: * Returns an Enumeration of all the names of the forum properties.
159: *
160: * @return an Enumeration of all the names of the forum properties.
161: */
162: public Enumeration propertyNames();
163:
164: /**
165: * Returns true if this forum is moderated. When a forum is moderated,
166: * posted messages and threads must first be approved by a user with
167: * moderator permissions.<p>
168: *
169: * @return Constants.MODERATION_THREAD
170: * or Constants.MODERATION_MESSAGE or Constants.MODERATION_NONE
171: */
172: public int getModerationType();
173:
174: /**
175: * Sets whether the forum is moderated. When a forum is moderated,
176: * posted messages and threads must first be approved by a user with
177: * moderator permissions.<p>
178: *
179: * @param type should be either Constants.MODERATION_THREAD
180: * or Constants.MODERATION_MESSAGE
181: * or Constants.MODERATION_NONE
182: * @throws UnauthorizedException if does not have ADMIN permissions.
183: */
184: public void setModerationType(int type)
185: throws UnauthorizedException;
186:
187: /**
188: * Factory method to create a Thread.
189: *
190: * @param forum the forum to create the thread in.
191: * @param rootMessage the root message of the thread.
192: *
193: * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
194: */
195: public abstract ForumThread createThread(Message rootMessage)
196: throws UnauthorizedException;
197:
198: /**
199: * Factory method to create a Message.
200: *
201: * @param user the user for the message.
202: * @throws UnauthorizedException if does not have CREATE_MESSAGE permissions.
203: */
204: public abstract Message createMessage(User user)
205: throws UnauthorizedException;
206:
207: /**
208: * Adds a thread to the forum.
209: *
210: * @param thread the thread to add to the forum.
211: * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
212: */
213: public void addThread(ForumThread thread)
214: throws UnauthorizedException;
215:
216: /**
217: * Deletes a thread. Once a thread is deleted, the thread object should
218: * no longer be used.
219: *
220: * @param thread the thread to delete.
221: * @throws UnauthorizedException if does not have ADMIN permissions.
222: */
223: public void deleteThread(ForumThread thread)
224: throws UnauthorizedException;
225:
226: /**
227: * Moves a thread from one forum to another. For this to work, the thread
228: * must exist in the forum that this method is invoked on, and the user
229: * calling this method must have ADMIN permissions for the forum this method
230: * is invoked on and <code>newForum</code>.<p>
231: *
232: * The main purpose of this method is to allow admins to move non-topical
233: * threads into a more appropriate forum.
234: *
235: * @param thread the thread to move to another forum.
236: * @param newForum the forum to move the thread to.
237: * @throws UnauthorizedException if does not have ADMIN permissions for the
238: * this forum and <code>newForum</code>.
239: * @throws IllegalArgumentException if <code>thread</code> does not belong
240: * to the forum that this method was invoked on.
241: */
242: public void moveThread(ForumThread thread, Forum newForum)
243: throws UnauthorizedException, IllegalArgumentException;
244:
245: /**
246: * Returns the thread specified by id. The method will return null
247: * if the thread is not in the forum.
248: */
249: public ForumThread getThread(int threadID)
250: throws ForumThreadNotFoundException;
251:
252: /**
253: * Returns a Iterator for the forum to move through the threads.
254: */
255: public Iterator threads();
256:
257: /**
258: * Returns a Iterator for the forum to move through the threads.
259: */
260: public Iterator threads(boolean approved);
261:
262: /**
263: * Returns a ListIterator for the forum to move through the threads.
264: *
265: * @param startIndex the index you'd like to start the iterator at.
266: * @param numResuls the max number of results iterator will hold.
267: */
268: public Iterator threads(int startIndex, int numResults);
269:
270: /**
271: * Returns a ListIterator for the forum to move through the threads.
272: *
273: * @param startIndex the index you'd like to start the iterator at.
274: * @param numResuls the max number of results iterator will hold.
275: */
276: public Iterator threads(boolean approved, int startIndex,
277: int numResults);
278:
279: /**
280: * Returns the number of threads in the forum.
281: */
282: public int getThreadCount();
283:
284: /**
285: * Returns the number of messages in the forum.
286: */
287: public int getMessageCount();
288:
289: /**
290: * @author dlaurent
291: * Returns the number of messages in the forum.
292: * approved or not
293: */
294: public int getMessageCount(boolean approved);
295:
296: /**
297: * @author dlaurent
298: * Returns the number of messages in the forum.
299: * approved or not
300: */
301: public int getThreadCount(boolean approved);
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(
413: Authorization authorization);
414:
415: /**
416: * Returns true if the handle on the object has the permission specified.
417: * A list of possible permissions can be found in the ForumPermissions
418: * class. Certain methods of this class are restricted to certain
419: * permissions as specified in the method comments.
420: *
421: * @see ForumPermissions
422: */
423: public boolean hasPermission(int type);
424: }
|