ForumThread


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 java.util.Date  ;
110 import java.util.Iterator  ;
111 
112 /**
113  * A ForumThread is a container for a hierarchy of ForumMessages.<p>
114  *
115  * Intimately tied to the concept of a ForumThread is a root message. A
116  * root message must be supplied when creating a thread. Subsequently, all
117  * further messages posted to the thread are children of the root message.<p>
118  *
119  * To get a handle on a ForumThread object, the <code>getThread</code> method
120  * should be called from a Forum object. To create a thread, <code>createThread</code>
121  * from a Forum object should be used. After creating a thread, you must
122  * attach it to a Forum by calling <code>addThread</code> from a Forum object.
123  * To delete a ForumThread, call the <code>deleteThread</code> method from the
124  * Forum object that the thread is attached to.<p>
125  *
126  * There are two options for navigating through the messages of a thread.
127  * <ul>
128  *   <li>A TreeWalker -- this provides a hierarchical view of the messages in
129  *      in the thread. For most skins, this will be the most appropriate
130  *      navigation method.
131  *   <li>An Iterator -- this provides a flat view of the messages in the thread.
132  *      Since the message structure is not really flat, a field to sort by
133  *      must be provided. This view of thread is useful for skins that want
134  *      to provide functionality such as listing all the messages in the order
135  *      they were created, etc.
136  * </ul>
137  *
138  * Because a root message must be passed in when creating a thread, you must
139  * first create that message before creating the thread. The following code
140  * snippet demonstrates:
141  * <pre>
142  * //Assume that a forum object and user object are already defined.
143  * ForumMessage rootMessage = myForum.createMessage(myUser);
144  * rootMessage.setSubject("A subject");
145  * rootMessage.setBody("A body");
146  * ForumThread myThread = myForum.createThread(rootMessage);
147  * </pre>
148  */
149 public interface ForumThread {
150 
151     /**
152      * Returns the unique id of the thread.
153      */
154     public int getID();
155 
156     /**
157      * Returns the name of the thread (which is the subject of the root message).
158      * This is a convenience method that is equivalent to
159      * <code>getRootMessage().getSubject()</code>.
160      *
161      * @return the name of the thread, which is the subject of the root message.
162      */
163     public String   getName();
164 
165     /**
166      * Returns the Date that the thread was created.
167      */
168     public Date   getCreationDate();
169 
170     /**
171      * Sets the creation date of the thread. In most cases, the creation date
172      * will default to when the thread was entered into the system. However,
173      * the creation date needs to be set manually when importing data.
174      * In other words, skin authors should ignore this method since it only
175      * intended for system maintenance.
176      *
177      * @param creationDate the date the thread was created.
178      *
179      * @throws UnauthorizedException if does not have ADMIN permissions.
180      */
181     public void setCreationDate(Date   creationDate) throws UnauthorizedException;
182 
183     /**
184      * Returns the Date that the thread was last modified. In other words, the
185      * date of the most recent message in the thread.
186      */
187     public Date   getModifiedDate();
188 
189     /**
190      * Sets the date the thread was last modified. In most cases, last modifed
191      * will default to when the thread data was last changed. However,
192      * the last modified date needs to be set manually when importing data.
193      * In other words, skin authors should ignore this method since it only
194      * intended for system maintenance.
195      *
196      * @param modifiedDate the date the thread was modified.
197      *
198      * @throws UnauthorizedException if does not have ADMIN permissions.
199      */
200     public void setModifiedDate(Date   modifiedDate) throws UnauthorizedException;
201 
202     /**
203      * Returns whether the thread was approved. When forum is not modereted
204      * this method always will return true;
205      *
206      * @return true if the thread was approved.
207      */
208     public boolean isApproved();
209 
210     /**
211      * Used by moderators to approved a thread in moderated forum.
212      *
213      * @param approved when true this thread will be visible for all.
214      * @throws UnauthorizedException if does not have ADMIN permissions.
215      */
216     public void setApprovment(boolean approved) throws UnauthorizedException;
217 
218     /**
219      * Returns the parent Forum of the thread.
220      */
221     public Forum getForum();
222 
223     /**
224      * Returns a message from the thread based on its id.
225      *
226      * @param messageID the ID of the message to get from the thread.
227      */
228     public ForumMessage getMessage(int messageID)
229             throws ForumMessageNotFoundException;
230 
231     /**
232      * Returns the root message of a thread. The root message is a special
233      * first message that is intimately tied to the thread for most forumViews.
234      * All other messages in the thread are children of the root message.
235      */
236     public ForumMessage getRootMessage();
237 
238     /**
239      * Returns the number of messages in the thread. This includes the root
240      * message. So, to find the number of replies to the root message,
241      * subtract one from the answer of this method.
242      */
243     public int getMessageCount();
244     /**
245      * Returns the number of times this thread has been read.
246      * We also manually add the count each time the message is read from the cache,
247      * so we have an accurate count of the times the thread has been read.
248      *
249      * @return
250      */
251     public int getReadCount();
252 
253     /**
254      * This method adds one to the read count.
255      * This should have been implemented at the database level, but due to caching it couldn't.
256      * Also it couldn't be added at the getThread level, since the ForumIterator uses the factory to get the thread
257      * for the list of the threads. Therefore it would create an inacurate count.
258      * You manually have to add the count in the skin to return an accurate count.
259      */
260     public void addReadCount();
261 
262 
263     /**
264      * Adds a new message to the thread.
265      *
266      * @param parentMessage some message in the thread that will be parent
267      * @param newMessage message to add to the thread under the parent
268      */
269     public void addMessage(ForumMessage parentMessage, ForumMessage newMessage) throws UnauthorizedException;
270 
271     /**
272      * Deletes a message from the thread. Throws an IllegalArgumentException
273      * if the message is not in the thread. If the message is deleted, it
274      * should be entirely erased from the Forum system. Therefore, the
275      * behavior is unspecified if a message object is first removed from a
276      * thread and then added to another (this action not recommended).
277      *
278      * @throws IllegalArgumentException if the message does not belong to the
279      *   thread.
280      * @throws UnauthorizedException if does not have ADMIN permissions.
281      */
282     public void deleteMessage(ForumMessage message)
283             throws UnauthorizedException;
284 
285     /**
286      * Moves a message from one thread to another. The message will become
287      * a child of <code>parentMessage</code> in <code>newThread</code>
288      *
289      * For this to work, <code>message</code> must exist in the thread that
290      * this method is invoked on, <code>parentMessage</code> must be in
291      * <code>newThread</code>, and the user calling this method must have
292      * ADMIN permissions for the forum this method is invoked on and the forum
293      * that <code>newThread</code> belongs to.<p>
294      *
295      * The main purpose of this method is to allow admins to move non-topical
296      * messages into a more appropriate thread.
297      *
298      * @param message the message to move to another thread.
299      * @param newThread the thread to move the message to.
300      * @param parentMessage the message under newThread that <code>message</code>
301      *      should become a child of.
302      * @throws UnauthorizedException if does not have ADMIN permissions for the
303      *      this forum and the forum that <code>newThread</code> belongs to.
304      * @throws IllegalArgumentException if <code>message</code> does not belong
305      *      to the thread that this method is invoked on, or <code>parentMessage
306      *      </code> does not belong to <code>newThread</code>.
307      */
308     public void moveMessage(ForumMessage message, ForumThread newThread,
309             ForumMessage parentMessage) throws UnauthorizedException,
310             IllegalArgumentException  ;
311 
312     /**
313      * Returns a TreeWalker for the entire thread. A TreeWalker is used
314      * to navigate through the tree of messages in a hierarchical manner.
315      */
316     public TreeWalker treeWalker();
317 
318     /**
319      * Return an Iterator for all the messages in a thread.
320      */
321     public Iterator   messages();
322 
323     /**
324      * Return an Iterator for all the messages in a thread. The startIndex
325      * and numResults restrict the number of results returned, which is useful
326      * for multi-page HTML navigation.
327      *
328      * @param startIndex the index you'd like to start the iterator at.
329      * @param numResuls the max number of results iterator will hold.
330      */
331     public Iterator   messages(int startIndex, int numResults);
332 
333     /**
334      * Returns true if the handle on the object has the permission specified.
335      * A list of possible permissions can be found in the ForumPermissions
336      * class. Certain methods of this class are restricted to certain
337      * permissions as specified in the method comments.
338      *
339      * @see ForumPermissions
340      */
341     public boolean hasPermission(int type);
342     public ThreadType getThreadType();
343     public boolean isSticky();
344     public void setSticky(boolean param) throws UnauthorizedException;
345     public boolean isClosed();
346     public void setClosed(boolean param) throws UnauthorizedException;
347 }
348
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags