ForumMessage


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  package com.Yasna.forum;
56  
57  import java.util.*;
58  
59  /**
60   * A ForumMessage encapsulates message data. Each message belongs to a thread,
61   * and relates to other messages in a thread in a tree relationship. This system
62   * allows messages to represent threaded conversations. For example:
63   *
64   * <pre>
65   *   [thread]
66   *        |- [message]
67   *        |- [message]
68   *                 |- [message]
69   *                 |- [message]
70   *                          |- [message]
71   *        |- [message]
72   * </pre><p>
73   *
74   * Each message has a subject and body. Messages are authored by a user
75   * in the system or can be anonymous. An ID is given to each message so that
76   * it can be tracked uniquely. Because is possible that one might want to store
77   * considerable more information with each message besides a subject and body,
78   * each message can have an arbitrary number of properties. For example, a
79   * property "IP" could be stored with each message that records the IP address
80   * of the person posting the message for security reasons.<p>
81   *
82   * The creation date, and the date the message was last modified are maintained
83   * for each message.<p>
84   *
85   * For added functionality, any number of filters can be applied to a message.
86   * Filters dynamically format the subject and body of a message. Methods are
87   * also provided to bypass filters.
88   *
89   * @see ForumMessageFilter
90   */
91  public interface ForumMessage {
92  
93      /**
94       * Returns the id of the message.
95       *
96       * @return the unique id of the message.
97       */
98      public int getID();
99  
100     /**
101      * Returns the date the message was created.
102      *
103      * @return the date the message was created.
104      */
105     public Date getCreationDate();
106 
107     /**
108      * Sets the creation date of the message. In most cases, the creation date
109      * will default to when the message was entered into the system. However,
110      * the creation date needs to be set manually when importing messages.
111      * In other words, skin authors should ignore this method since it only
112      * intended for system maintenance.
113      *
114      * @param creationDate the date the message was created.
115      *
116      * @throws UnauthorizedException if does not have ADMIN permissions.
117      */
118     public void setCreationDate(Date creationDate) throws UnauthorizedException;
119 
120     /**
121      * Returns the date the message was last modified. When a message is first
122      * created, the date returned by this method is identical to the creation
123      * date. The modified date is updated every time a message property is
124      * updated, such as the message body.
125      *
126      * @return the date the message was last modified.
127      */
128     public Date getModifiedDate();
129 
130     /**
131      * Sets the date the message was last modified. In most cases, last modifed
132      * will default to when the message data was last changed. However,
133      * the last modified date needs to be set manually when importing messages.
134      * In other words, skin authors should ignore this method since it only
135      * intended for system maintenance.
136      *
137      * @param modifiedDate the date the message was modified.
138      * @throws UnauthorizedException if does not have ADMIN permissions.
139      */
140     public void setModifiedDate(Date modifiedDate) throws UnauthorizedException;
141 
142     /**
143      * Returns the message subject. If message filters are active, the
144      * subject returned will be a filtered one. Because filters often provide
145      * security functionality, this method is the preferred way to get the
146      * subject of a message.
147      *
148      * @return the subject of the message.
149      */
150     public String   getSubject();
151 
152     /**
153      * Returns the message subject, bypassing any active filters. Because
154      * filters often provide security, this method should be used with caution.
155      * In particular, you should avoid showing unfiltered data in an environment
156      * where embedded HTML might be interpreted.<p>
157      *
158      * Unfiltered content is necessary for a few reasons. One is when saving
159      * Yazd content to another persistence mechanism such as an XML format.
160      * Another is when you need to skip filter formatting, such as when a user
161      * is responding to another user's message.
162      *
163      * @return the subject of the message.
164      */
165     public String   getUnfilteredSubject();
166 
167     /**
168      * Sets the subject of the message.
169      *
170      * @param subject the subject of the message.
171      * @throws UnauthorizedException if does not have ADMIN permissions.
172      */
173     public void setSubject(String   subject) throws UnauthorizedException;
174 
175     /**
176      * Used only for private messages. Sets the userId of the parent message.
177      *
178      * @param replyPrivateUserId the userId of the parent message.
179      * @throws UnauthorizedException if does not have ADMIN permissions.
180      */
181     public void setReplyPrivateUserId(int replyPrivateUserId) throws UnauthorizedException;
182 
183     /**
184      * Used by moderators to approved a message in moderated forum.
185      *
186      * @param approved when true this message will be visible for all.
187      * @throws UnauthorizedException if does not have ADMIN permissions.
188      */
189     public void setApprovment(boolean approved) throws UnauthorizedException;
190 
191 
192     /**
193      * Returns the message body. If message filters are active, the body
194      * returned will be a filtered one. Because filters often provide security
195      * functionality, this method is the preferred way to get the body of a
196      * message.
197      *
198      * @return the body of the message.
199      */
200     public String   getBody();
201 
202     /**
203      * Returns the message body, bypassing any active filters. Because filters
204      * often provide security, this method should be used with caution. In
205      * particular, you should avoid showing unfiltered data in an environment
206      * where embedded HTML might be interpreted.<p>
207      *
208      * Unfiltered content is necessary for a few reasons. One is when saving
209      * Yazd content to another persistence mechanism such as an XML format.
210      * Another is when you need to skip filter formatting, such as when a user
211      * is responding to another user's message.
212      *
213      * @return the body of the message.
214      */
215     public String   getUnfilteredBody();
216 
217     /**
218      * Sets the body of the message.
219      *
220      * @param body the body of the message.
221      * @throws UnauthorizedException if does not have ADMIN permissions.
222      */
223     public void setBody(String   body) throws UnauthorizedException;
224 
225     /**
226      * Returns the id of the User to which the private message is posted
227      * i.e. userId of the parent message or 0 if the message is not private
228      *
229      * @return user id of the of the parent message or 0 if the message is not private.
230      */
231     public int getReplyPrivateUserId();
232 
233     /**
234      * Indicates if message is private or not.
235      *
236      * @return <i>true</i> if message is private, <i>false</i> otherwise.
237      */
238     public boolean isPrivate();
239 
240     /**
241      * Returns the User that authored the message. If the message was created
242      * anonymously, the Anonymous User object will be returned.
243      *
244      * @return the author of the message.
245      */
246     public User getUser();
247 
248     /**
249      * Returns an extended property of the message. Each message can have an
250      * arbitrary number of extended properties. This lets particular skins
251      * or filters provide enhanced functionality that is not part of the base
252      * interface.<p>
253      *
254      * For security reasons, all property values are run through an HTML filter
255      * before being returned.
256      *
257      * @param name the name of the property to get.
258      * @return the value of the property.
259      */
260     public String   getProperty(String   name);
261 
262     /**
263      * Returns an extended property of the message, bypassing the HTML filter.
264      * Each message can have an arbitrary number of extended properties. This
265      * lets particular skins or filters provide enhanced functionality that is
266      * not part of the base interface.<p>
267      *
268      * Because properties are not filtered before being returned, this method
269      * should be used with caution. In particular, you should avoid showing
270      * unfiltered data in an environment where embedded HTML might be
271      * interpreted.
272      *
273      * @param name the name of the property to get.
274      * @return the value of the property.
275      */
276     public String   getUnfilteredProperty(String   name);
277 
278     /**
279      * Sets an extended property of the message. Each message can have an
280      * arbitrary number of extended properties. This lets particular skins
281      * or filters provide enhanced functionality that is not part of the base
282      * interface.
283      *
284      * @param name the name of the property to set.
285      * @param value the new value for the property.
286      */
287     public void setProperty(String   name, String   value);
288 
289     /**
290      * Returns an Iterator for all the names of the message properties.
291      *
292      * @return an Iterator for the names of all message properties.
293      */
294     public Iterator propertyNames();
295 
296     /**
297      * Returns whether the message was posted anonymously. This is a convenience
298      * method and is equivalent to getUser().isAnonymous();
299      *
300      * @return true if the message was posted anonymously.
301      */
302     public boolean isAnonymous();
303 
304     /**
305      * Returns whether the message was approved. When forum is not modereted
306      * this method always will return true;
307      *
308      * @return true if the message was approved.
309      */
310     public boolean isApproved();
311 
312     /**
313      * Returns the thread the message belongs to.
314      *
315      * @return the thread the message belongs to.
316      */
317     public ForumThread getForumThread();
318 
319     /**
320      * Returns true if the handle on the object has the permission specified.
321      * A list of possible permissions can be found in the ForumPermissions
322      * class. Certain methods of this class are restricted to certain
323      * permissions as specified in the method comments.
324      *
325      * @param type a permission type.
326      * @return true if the specified permission is valid.
327      * @see ForumPermissions
328      */
329     public boolean hasPermission(int type);
330     /**
331      * this method returns the ranking of the message.
332      * If this is the root message then there is no ranking. It is defaulted to neutral ranking for the message.
333      * @return
334      */
335     public MessageRanking getRanking();
336     /**
337      * this method sets the ranking of the message.
338      * Note that the ranking of the message can only be set by the user who created the thread or asked the original question.
339      * Also the user can't rank his own posts.
340      * @param para
341      * @throws UnauthorizedException
342      */
343     public void setRanking(int para) throws UnauthorizedException;
344 }
345 
346
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags