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.Iterator;
030:
031: import org.nemesis.forum.exception.ForumMessageNotFoundException;
032: import org.nemesis.forum.exception.UnauthorizedException;
033:
034: /**
035: * A ForumThread is a container for a hierarchy of ForumMessages.<p>
036: *
037: * Intimately tied to the concept of a ForumThread is a root message. A
038: * root message must be supplied when creating a thread. Subsequently, all
039: * further messages posted to the thread are children of the root message.<p>
040: *
041: * To get a handle on a ForumThread object, the <code>getThread</code> method
042: * should be called from a Forum object. To create a thread, <code>createThread</code>
043: * from a Forum object should be used. After creating a thread, you must
044: * attach it to a Forum by calling <code>addThread</code> from a Forum object.
045: * To delete a ForumThread, call the <code>deleteThread</code> method from the
046: * Forum object that the thread is attached to.<p>
047: *
048: * There are two options for navigating through the messages of a thread.
049: * <ul>
050: * <li>A TreeWalker -- this provides a hierarchical view of the messages in
051: * in the thread. For most skins, this will be the most appropriate
052: * navigation method.
053: * <li>An Iterator -- this provides a flat view of the messages in the thread.
054: * Since the message structure is not really flat, a field to sort by
055: * must be provided. This view of thread is useful for skins that want
056: * to provide functionality such as listing all the messages in the order
057: * they were created, etc.
058: * </ul>
059: *
060: * Because a root message must be passed in when creating a thread, you must
061: * first create that message before creating the thread. The following code
062: * snippet demonstrates:
063: * <pre>
064: * //Assume that a forum object and user object are already defined.
065: * ForumMessage rootMessage = myForum.createMessage(myUser);
066: * rootMessage.setSubject("A subject");
067: * rootMessage.setBody("A body");
068: * ForumThread myThread = myForum.createThread(rootMessage);
069: * </pre>
070: */
071: public interface ForumThread {
072:
073: /**
074: * Returns the unique id of the thread.
075: */
076: public int getID();
077:
078: /**
079: * Returns the name of the thread (which is the subject of the root message).
080: * This is a convenience method that is equivalent to
081: * <code>getRootMessage().getSubject()</code>.
082: *
083: * @return the name of the thread, which is the subject of the root message.
084: */
085: public String getName();
086:
087: /**
088: * Returns the Date that the thread was created.
089: */
090: public Date getCreationDate();
091:
092: /**
093: * Sets the creation date of the thread. In most cases, the creation date
094: * will default to when the thread was entered into the system. However,
095: * the creation date needs to be set manually when importing data.
096: * In other words, skin authors should ignore this method since it only
097: * intended for system maintenance.
098: *
099: * @param creationDate the date the thread was created.
100: *
101: * @throws UnauthorizedException if does not have ADMIN permissions.
102: */
103: public void setCreationDate(Date creationDate)
104: throws UnauthorizedException;
105:
106: /**
107: * Returns the Date that the thread was last modified. In other words, the
108: * date of the most recent message in the thread.
109: */
110: public Date getModifiedDate();
111:
112: /**
113: * Sets the date the thread was last modified. In most cases, last modifed
114: * will default to when the thread data was last changed. However,
115: * the last modified date needs to be set manually when importing data.
116: * In other words, skin authors should ignore this method since it only
117: * intended for system maintenance.
118: *
119: * @param modifiedDate the date the thread was modified.
120: *
121: * @throws UnauthorizedException if does not have ADMIN permissions.
122: */
123: public void setModifiedDate(Date modifiedDate)
124: throws UnauthorizedException;
125:
126: /**
127: * Returns the parent Forum of the thread.
128: */
129: public Forum getForum();
130:
131: /**
132: * Returns a message from the thread based on its id.
133: *
134: * @param messageID the ID of the message to get from the thread.
135: */
136: public Message getMessage(int messageID)
137: throws ForumMessageNotFoundException;
138:
139: /**
140: * Returns the root message of a thread. The root message is a special
141: * first message that is intimately tied to the thread for most forumViews.
142: * All other messages in the thread are children of the root message.
143: */
144: public Message getRootMessage();
145:
146: /**
147: * Returns the number of messages in the thread. This includes the root
148: * message. So, to find the number of replies to the root message,
149: * subtract one from the answer of this method.
150: */
151: public int getMessageCount();
152:
153: /**
154: * @author dlaurent
155: * Returns the number of messages in the forum.
156: * approved or not
157: */
158: public int getMessageCount(boolean approved);
159:
160: /**
161: * Adds a new message to the thread.
162: *
163: * @param parentMessage some message in the thread that will be parent
164: * @param newMessage message to add to the thread under the parent
165: */
166: public void addMessage(Message parentMessage, Message newMessage);
167:
168: /**
169: * Deletes a message from the thread. Throws an IllegalArgumentException
170: * if the message is not in the thread. If the message is deleted, it
171: * should be entirely erased from the Forum system. Therefore, the
172: * behavior is unspecified if a message object is first removed from a
173: * thread and then added to another (this action not recommended).
174: *
175: * @throws IllegalArgumentException if the message does not belong to the
176: * thread.
177: * @throws UnauthorizedException if does not have ADMIN permissions.
178: */
179: public void deleteMessage(Message message)
180: throws UnauthorizedException;
181:
182: /**
183: * Moves a message from one thread to another. The message will become
184: * a child of <code>parentMessage</code> in <code>newThread</code>
185: *
186: * For this to work, <code>message</code> must exist in the thread that
187: * this method is invoked on, <code>parentMessage</code> must be in
188: * <code>newThread</code>, and the user calling this method must have
189: * ADMIN permissions for the forum this method is invoked on and the forum
190: * that <code>newThread</code> belongs to.<p>
191: *
192: * The main purpose of this method is to allow admins to move non-topical
193: * messages into a more appropriate thread.
194: *
195: * @param message the message to move to another thread.
196: * @param newThread the thread to move the message to.
197: * @param parentMessage the message under newThread that <code>message</code>
198: * should become a child of.
199: * @throws UnauthorizedException if does not have ADMIN permissions for the
200: * this forum and the forum that <code>newThread</code> belongs to.
201: * @throws IllegalArgumentException if <code>message</code> does not belong
202: * to the thread that this method is invoked on, or <code>parentMessage
203: * </code> does not belong to <code>newThread</code>.
204: */
205: public void moveMessage(Message message, ForumThread newThread,
206: Message parentMessage) throws UnauthorizedException,
207: IllegalArgumentException;
208:
209: /**
210: * Returns a TreeWalker for the entire thread. A TreeWalker is used
211: * to navigate through the tree of messages in a hierarchical manner.
212: */
213: public TreeWalker treeWalker();
214:
215: /**
216: * Returns a TreeWalker for the entire thread. A TreeWalker is used
217: * to navigate through the tree of approved or not messages in a hierarchical manner.
218: */
219: public TreeWalker treeWalker(boolean approved);
220:
221: /**
222: * Return an Iterator for all the messages in a thread.
223: */
224: public Iterator messages();
225:
226: /**
227: * Return an Iterator for all the messages in a thread. The startIndex
228: * and numResults restrict the number of results returned, which is useful
229: * for multi-page HTML navigation.
230: *
231: * @param startIndex the index you'd like to start the iterator at.
232: * @param numResuls the max number of results iterator will hold.
233: */
234: public Iterator messages(int startIndex, int numResults);
235:
236: /**
237: * Return an Iterator for all the messages in a thread.
238: */
239: public Iterator messages(boolean approved);
240:
241: /**
242: * Return an Iterator for all the messages in a thread. The startIndex
243: * and numResults restrict the number of results returned, which is useful
244: * for multi-page HTML navigation.
245: *
246: * @param startIndex the index you'd like to start the iterator at.
247: * @param numResuls the max number of results iterator will hold.
248: */
249: public Iterator messages(boolean approved, int startIndex,
250: int numResults);
251:
252: /**
253: * Returns true if the handle on the object has the permission specified.
254: * A list of possible permissions can be found in the ForumPermissions
255: * class. Certain methods of this class are restricted to certain
256: * permissions as specified in the method comments.
257: *
258: * @see ForumPermissions
259: */
260: public boolean hasPermission(int type);
261:
262: //AJOUT
263: /**
264: * return true if the message is approved
265: */
266: public boolean isApproved();
267:
268: public void setApproved(boolean approved)
269: throws UnauthorizedException;
270: }
|