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