ForumThread


1   /*
2    * NEMESIS-FORUM.
3    * Copyright (C) 2002  David Laurent(lithium2@free.fr). All rights reserved.
4    * 
5    * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
6    * 
7    * Copyright (C) 2001 Yasna.com. All rights reserved.
8    * 
9    * Copyright (C) 2000 CoolServlets.com. All rights reserved.
10   * 
11   * NEMESIS-FORUM. is free software; you can redistribute it and/or
12   * modify it under the terms of the Apache Software License, Version 1.1,
13   * or (at your option) any later version.
14   * 
15   * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
16   * application are parts of NEMESIS-FORUM and are distributed under
17   * same terms of licence.
18   * 
19   * 
20   * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
21   * and software developed by CoolServlets.com (http://www.coolservlets.com).
22   * and software developed by Yasna.com (http://www.yasna.com).
23   * 
24   */
25  
26  
27  package org.nemesis.forum;
28  
29  import java.util.Date  ;
30  import java.util.Iterator  ;
31  
32  import org.nemesis.forum.exception.ForumMessageNotFoundException;
33  import org.nemesis.forum.exception.UnauthorizedException;
34  
35  /**
36   * A ForumThread is a container for a hierarchy of ForumMessages.<p>
37   *
38   * Intimately tied to the concept of a ForumThread is a root message. A
39   * root message must be supplied when creating a thread. Subsequently, all
40   * further messages posted to the thread are children of the root message.<p>
41   *
42   * To get a handle on a ForumThread object, the <code>getThread</code> method
43   * should be called from a Forum object. To create a thread, <code>createThread</code>
44   * from a Forum object should be used. After creating a thread, you must
45   * attach it to a Forum by calling <code>addThread</code> from a Forum object.
46   * To delete a ForumThread, call the <code>deleteThread</code> method from the
47   * Forum object that the thread is attached to.<p>
48   *
49   * There are two options for navigating through the messages of a thread.
50   * <ul>
51   *   <li>A TreeWalker -- this provides a hierarchical view of the messages in
52   *      in the thread. For most skins, this will be the most appropriate
53   *      navigation method.
54   *   <li>An Iterator -- this provides a flat view of the messages in the thread.
55   *      Since the message structure is not really flat, a field to sort by
56   *      must be provided. This view of thread is useful for skins that want
57   *      to provide functionality such as listing all the messages in the order
58   *      they were created, etc.
59   * </ul>
60   *
61   * Because a root message must be passed in when creating a thread, you must
62   * first create that message before creating the thread. The following code
63   * snippet demonstrates:
64   * <pre>
65   * //Assume that a forum object and user object are already defined.
66   * ForumMessage rootMessage = myForum.createMessage(myUser);
67   * rootMessage.setSubject("A subject");
68   * rootMessage.setBody("A body");
69   * ForumThread myThread = myForum.createThread(rootMessage);
70   * </pre>
71   */
72  public interface ForumThread {
73  
74      /**
75       * Returns the unique id of the thread.
76       */
77      public int getID();
78  
79      /**
80       * Returns the name of the thread (which is the subject of the root message).
81       * This is a convenience method that is equivalent to
82       * <code>getRootMessage().getSubject()</code>.
83       *
84       * @return the name of the thread, which is the subject of the root message.
85       */
86      public String   getName();
87  
88      /**
89       * Returns the Date that the thread was created.
90       */
91      public Date   getCreationDate();
92  
93      /**
94       * Sets the creation date of the thread. In most cases, the creation date
95       * will default to when the thread was entered into the system. However,
96       * the creation date needs to be set manually when importing data.
97       * In other words, skin authors should ignore this method since it only
98       * intended for system maintenance.
99       *
100      * @param creationDate the date the thread was created.
101      *
102      * @throws UnauthorizedException if does not have ADMIN permissions.
103      */
104     public void setCreationDate(Date   creationDate) 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) throws UnauthorizedException;
124 
125     /**
126      * Returns the parent Forum of the thread.
127      */
128     public Forum getForum();
129 
130     /**
131      * Returns a message from the thread based on its id.
132      *
133      * @param messageID the ID of the message to get from the thread.
134      */
135     public Message getMessage(int messageID)
136             throws ForumMessageNotFoundException;
137 
138     /**
139      * Returns the root message of a thread. The root message is a special
140      * first message that is intimately tied to the thread for most forumViews.
141      * All other messages in the thread are children of the root message.
142      */
143     public Message getRootMessage();
144 
145     /**
146      * Returns the number of messages in the thread. This includes the root
147      * message. So, to find the number of replies to the root message,
148      * subtract one from the answer of this method.
149      */
150     public int getMessageCount();
151 
152     /**
153      * @author dlaurent
154      * Returns the number of messages in the forum.
155      *  approved or not
156      */
157     public int getMessageCount(boolean approved);
158     
159 
160 
161     /**
162      * Adds a new message to the thread.
163      *
164      * @param parentMessage some message in the thread that will be parent
165      * @param newMessage message to add to the thread under the parent
166      */
167     public void addMessage(Message parentMessage, Message newMessage);
168 
169     /**
170      * Deletes a message from the thread. Throws an IllegalArgumentException
171      * if the message is not in the thread. If the message is deleted, it
172      * should be entirely erased from the Forum system. Therefore, the
173      * behavior is unspecified if a message object is first removed from a
174      * thread and then added to another (this action not recommended).
175      *
176      * @throws IllegalArgumentException if the message does not belong to the
177      *   thread.
178      * @throws UnauthorizedException if does not have ADMIN permissions.
179      */
180     public void deleteMessage(Message message)
181             throws UnauthorizedException;
182 
183     /**
184      * Moves a message from one thread to another. The message will become
185      * a child of <code>parentMessage</code> in <code>newThread</code>
186      *
187      * For this to work, <code>message</code> must exist in the thread that
188      * this method is invoked on, <code>parentMessage</code> must be in
189      * <code>newThread</code>, and the user calling this method must have
190      * ADMIN permissions for the forum this method is invoked on and the forum
191      * that <code>newThread</code> belongs to.<p>
192      *
193      * The main purpose of this method is to allow admins to move non-topical
194      * messages into a more appropriate thread.
195      *
196      * @param message the message to move to another thread.
197      * @param newThread the thread to move the message to.
198      * @param parentMessage the message under newThread that <code>message</code>
199      *      should become a child of.
200      * @throws UnauthorizedException if does not have ADMIN permissions for the
201      *      this forum and the forum that <code>newThread</code> belongs to.
202      * @throws IllegalArgumentException if <code>message</code> does not belong
203      *      to the thread that this method is invoked on, or <code>parentMessage
204      *      </code> does not belong to <code>newThread</code>.
205      */
206     public void moveMessage(Message message, ForumThread newThread,
207             Message parentMessage) throws UnauthorizedException,
208             IllegalArgumentException  ;
209 
210     /**
211      * Returns a TreeWalker for the entire thread. A TreeWalker is used
212      * to navigate through the tree of messages in a hierarchical manner.
213      */
214     public TreeWalker treeWalker();
215     
216     /**
217      * Returns a TreeWalker for the entire thread. A TreeWalker is used
218      * to navigate through the tree of approved or not messages in a hierarchical manner.
219      */
220     public TreeWalker treeWalker(boolean approved);  
221 
222     /**
223      * Return an Iterator for all the messages in a thread.
224      */
225     public Iterator   messages();
226 
227     /**
228      * Return an Iterator for all the messages in a thread. The startIndex
229      * and numResults restrict the number of results returned, which is useful
230      * for multi-page HTML navigation.
231      *
232      * @param startIndex the index you'd like to start the iterator at.
233      * @param numResuls the max number of results iterator will hold.
234      */
235     public Iterator   messages(int startIndex, int numResults);
236     
237     /**
238      * Return an Iterator for all the messages in a thread.
239      */
240     public Iterator   messages(boolean approved);
241 
242     /**
243      * Return an Iterator for all the messages in a thread. The startIndex
244      * and numResults restrict the number of results returned, which is useful
245      * for multi-page HTML navigation.
246      *
247      * @param startIndex the index you'd like to start the iterator at.
248      * @param numResuls the max number of results iterator will hold.
249      */
250     public Iterator   messages(boolean approved,int startIndex, 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) throws UnauthorizedException;
269 }
270
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags