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: */package com.Yasna.forum;
053:
054: import java.util.*;
055:
056: /**
057: * A ForumMessage encapsulates message data. Each message belongs to a thread,
058: * and relates to other messages in a thread in a tree relationship. This system
059: * allows messages to represent threaded conversations. For example:
060: *
061: * <pre>
062: * [thread]
063: * |- [message]
064: * |- [message]
065: * |- [message]
066: * |- [message]
067: * |- [message]
068: * |- [message]
069: * </pre><p>
070: *
071: * Each message has a subject and body. Messages are authored by a user
072: * in the system or can be anonymous. An ID is given to each message so that
073: * it can be tracked uniquely. Because is possible that one might want to store
074: * considerable more information with each message besides a subject and body,
075: * each message can have an arbitrary number of properties. For example, a
076: * property "IP" could be stored with each message that records the IP address
077: * of the person posting the message for security reasons.<p>
078: *
079: * The creation date, and the date the message was last modified are maintained
080: * for each message.<p>
081: *
082: * For added functionality, any number of filters can be applied to a message.
083: * Filters dynamically format the subject and body of a message. Methods are
084: * also provided to bypass filters.
085: *
086: * @see ForumMessageFilter
087: */
088: public interface ForumMessage {
089:
090: /**
091: * Returns the id of the message.
092: *
093: * @return the unique id of the message.
094: */
095: public int getID();
096:
097: /**
098: * Returns the date the message was created.
099: *
100: * @return the date the message was created.
101: */
102: public Date getCreationDate();
103:
104: /**
105: * Sets the creation date of the message. In most cases, the creation date
106: * will default to when the message was entered into the system. However,
107: * the creation date needs to be set manually when importing messages.
108: * In other words, skin authors should ignore this method since it only
109: * intended for system maintenance.
110: *
111: * @param creationDate the date the message was created.
112: *
113: * @throws UnauthorizedException if does not have ADMIN permissions.
114: */
115: public void setCreationDate(Date creationDate)
116: throws UnauthorizedException;
117:
118: /**
119: * Returns the date the message was last modified. When a message is first
120: * created, the date returned by this method is identical to the creation
121: * date. The modified date is updated every time a message property is
122: * updated, such as the message body.
123: *
124: * @return the date the message was last modified.
125: */
126: public Date getModifiedDate();
127:
128: /**
129: * Sets the date the message was last modified. In most cases, last modifed
130: * will default to when the message data was last changed. However,
131: * the last modified date needs to be set manually when importing messages.
132: * In other words, skin authors should ignore this method since it only
133: * intended for system maintenance.
134: *
135: * @param modifiedDate the date the message was modified.
136: * @throws UnauthorizedException if does not have ADMIN permissions.
137: */
138: public void setModifiedDate(Date modifiedDate)
139: throws UnauthorizedException;
140:
141: /**
142: * Returns the message subject. If message filters are active, the
143: * subject returned will be a filtered one. Because filters often provide
144: * security functionality, this method is the preferred way to get the
145: * subject of a message.
146: *
147: * @return the subject of the message.
148: */
149: public String getSubject();
150:
151: /**
152: * Returns the message subject, bypassing any active filters. Because
153: * filters often provide security, this method should be used with caution.
154: * In particular, you should avoid showing unfiltered data in an environment
155: * where embedded HTML might be interpreted.<p>
156: *
157: * Unfiltered content is necessary for a few reasons. One is when saving
158: * Yazd content to another persistence mechanism such as an XML format.
159: * Another is when you need to skip filter formatting, such as when a user
160: * is responding to another user's message.
161: *
162: * @return the subject of the message.
163: */
164: public String getUnfilteredSubject();
165:
166: /**
167: * Sets the subject of the message.
168: *
169: * @param subject the subject of the message.
170: * @throws UnauthorizedException if does not have ADMIN permissions.
171: */
172: public void setSubject(String subject) throws UnauthorizedException;
173:
174: /**
175: * Used only for private messages. Sets the userId of the parent message.
176: *
177: * @param replyPrivateUserId the userId of the parent message.
178: * @throws UnauthorizedException if does not have ADMIN permissions.
179: */
180: public void setReplyPrivateUserId(int replyPrivateUserId)
181: 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)
190: throws UnauthorizedException;
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: /**
332: * this method returns the ranking of the message.
333: * If this is the root message then there is no ranking. It is defaulted to neutral ranking for the message.
334: * @return
335: */
336: public MessageRanking getRanking();
337:
338: /**
339: * this method sets the ranking of the message.
340: * Note that the ranking of the message can only be set by the user who created the thread or asked the original question.
341: * Also the user can't rank his own posts.
342: * @param para
343: * @throws UnauthorizedException
344: */
345: public void setRanking(int para) throws UnauthorizedException;
346: }
|