001: /*
002: * NEMESIS-FORUM.
003: * Copyright (C) 2002 David Laurent(lithium2@free.fr). All rights reserved.
004: *
005: * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
006: *
007: * Copyright (C) 2001 Yasna.com. All rights reserved.
008: *
009: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
010: *
011: * NEMESIS-FORUM. is free software; you can redistribute it and/or
012: * modify it under the terms of the Apache Software License, Version 1.1,
013: * or (at your option) any later version.
014: *
015: * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
016: * application are parts of NEMESIS-FORUM and are distributed under
017: * same terms of licence.
018: *
019: *
020: * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
021: * and software developed by CoolServlets.com (http://www.coolservlets.com).
022: * and software developed by Yasna.com (http://www.yasna.com).
023: *
024: */
025:
026: package org.nemesis.forum;
027:
028: import java.util.Date;
029: import java.util.Iterator;
030:
031: import org.nemesis.forum.exception.UnauthorizedException;
032:
033: /**
034: * A ForumMessage encapsulates message data. Each message belongs to a thread,
035: * and relates to other messages in a thread in a tree relationship. This system
036: * allows messages to represent threaded conversations. For example:
037: *
038: * <pre>
039: * [thread]
040: * |- [message]
041: * |- [message]
042: * |- [message]
043: * |- [message]
044: * |- [message]
045: * |- [message]
046: * </pre><p>
047: *
048: * Each message has a subject and body. Messages are authored by a user
049: * in the system or can be anonymous. An ID is given to each message so that
050: * it can be tracked uniquely. Because is possible that one might want to store
051: * considerable more information with each message besides a subject and body,
052: * each message can have an arbitrary number of properties. For example, a
053: * property "IP" could be stored with each message that records the IP address
054: * of the person posting the message for security reasons.<p>
055: *
056: * The creation date, and the date the message was last modified are maintained
057: * for each message.<p>
058: *
059: * For added functionality, any number of filters can be applied to a message.
060: * Filters dynamically format the subject and body of a message. Methods are
061: * also provided to bypass filters.
062: *
063: * @see ForumMessageFilter
064: */
065: public interface Message {
066:
067: //-------********************** isapproved???????, setapproved.....
068:
069: /**
070: * Returns the id of the message.
071: *
072: * @return the unique id of the message.
073: */
074: public int getID();
075:
076: /**
077: * Returns the date the message was created.
078: *
079: * @return the date the message was created.
080: */
081: public Date getCreationDate();
082:
083: /**
084: * Sets the creation date of the message. In most cases, the creation date
085: * will default to when the message was entered into the system. However,
086: * the creation date needs to be set manually when importing messages.
087: * In other words, skin authors should ignore this method since it only
088: * intended for system maintenance.
089: *
090: * @param creationDate the date the message was created.
091: *
092: * @throws UnauthorizedException if does not have ADMIN permissions.
093: */
094: public void setCreationDate(Date creationDate)
095: throws UnauthorizedException;
096:
097: /**
098: * Returns the date the message was last modified. When a message is first
099: * created, the date returned by this method is identical to the creation
100: * date. The modified date is updated every time a message property is
101: * updated, such as the message body.
102: *
103: * @return the date the message was last modified.
104: */
105: public Date getModifiedDate();
106:
107: /**
108: * Sets the date the message was last modified. In most cases, last modifed
109: * will default to when the message data was last changed. However,
110: * the last modified 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 modifiedDate the date the message was modified.
115: * @throws UnauthorizedException if does not have ADMIN permissions.
116: */
117: public void setModifiedDate(Date modifiedDate)
118: throws UnauthorizedException;
119:
120: /**
121: * Returns the message subject. If message filters are active, the
122: * subject returned will be a filtered one. Because filters often provide
123: * security functionality, this method is the preferred way to get the
124: * subject of a message.
125: *
126: * @return the subject of the message.
127: */
128: public String getSubject();
129:
130: /**
131: * Returns the message subject, bypassing any active filters. Because
132: * filters often provide security, this method should be used with caution.
133: * In particular, you should avoid showing unfiltered data in an environment
134: * where embedded HTML might be interpreted.<p>
135: *
136: * Unfiltered content is necessary for a few reasons. One is when saving
137: * content to another persistence mechanism such as an XML format.
138: * Another is when you need to skip filter formatting, such as when a user
139: * is responding to another user's message.
140: *
141: * @return the subject of the message.
142: */
143: public String getUnfilteredSubject();
144:
145: /**
146: * Sets the subject of the message.
147: *
148: * @param subject the subject of the message.
149: * @throws UnauthorizedException if does not have ADMIN permissions.
150: */
151: public void setSubject(String subject) throws UnauthorizedException;
152:
153: /**
154: * Returns the message body. If message filters are active, the body
155: * returned will be a filtered one. Because filters often provide security
156: * functionality, this method is the preferred way to get the body of a
157: * message.
158: *
159: * @return the body of the message.
160: */
161: public String getBody();
162:
163: /**
164: * Returns the message body, bypassing any active filters. Because filters
165: * often provide security, this method should be used with caution. In
166: * particular, you should avoid showing unfiltered data in an environment
167: * where embedded HTML might be interpreted.<p>
168: *
169: * Unfiltered content is necessary for a few reasons. One is when saving
170: * content to another persistence mechanism such as an XML format.
171: * Another is when you need to skip filter formatting, such as when a user
172: * is responding to another user's message.
173: *
174: * @return the body of the message.
175: */
176: public String getUnfilteredBody();
177:
178: /**
179: * Sets the body of the message.
180: *
181: * @param body the body of the message.
182: * @throws UnauthorizedException if does not have ADMIN permissions.
183: */
184: public void setBody(String body) throws UnauthorizedException;
185:
186: /**
187: * Returns the User that authored the message. If the message was created
188: * anonymously, the Anonymous User object will be returned.
189: *
190: * @return the author of the message.
191: */
192: public User getUser();
193:
194: /**
195: * Returns an extended property of the message. Each message can have an
196: * arbitrary number of extended properties. This lets particular skins
197: * or filters provide enhanced functionality that is not part of the base
198: * interface.<p>
199: *
200: * For security reasons, all property values are run through an HTML filter
201: * before being returned.
202: *
203: * @param name the name of the property to get.
204: * @return the value of the property.
205: */
206: public String getProperty(String name);
207:
208: /**
209: * Returns an extended property of the message, bypassing the HTML filter.
210: * Each message can have an arbitrary number of extended properties. This
211: * lets particular skins or filters provide enhanced functionality that is
212: * not part of the base interface.<p>
213: *
214: * Because properties are not filtered before being returned, this method
215: * should be used with caution. In particular, you should avoid showing
216: * unfiltered data in an environment where embedded HTML might be
217: * interpreted.
218: *
219: * @param name the name of the property to get.
220: * @return the value of the property.
221: */
222: public String getUnfilteredProperty(String name);
223:
224: /**
225: * Sets an extended property of the message. Each message can have an
226: * arbitrary number of extended properties. This lets particular skins
227: * or filters provide enhanced functionality that is not part of the base
228: * interface.
229: *
230: * @param name the name of the property to set.
231: * @param value the new value for the property.
232: */
233: public void setProperty(String name, String value);
234:
235: /**
236: * Returns an Iterator for all the names of the message properties.
237: *
238: * @return an Iterator for the names of all message properties.
239: */
240: public Iterator propertyNames();
241:
242: /**
243: * Returns whether the message was posted anonymously. This is a convenience
244: * method and is equivalent to getUser().isAnonymous();
245: *
246: * @return true if the message was posted anonymously.
247: */
248: public boolean isAnonymous();
249:
250: /**
251: * Returns the thread the message belongs to.
252: *
253: * @return the thread the message belongs to.
254: */
255: public ForumThread getForumThread();
256:
257: /**
258: * Returns true if the handle on the object has the permission specified.
259: * A list of possible permissions can be found in the ForumPermissions
260: * class. Certain methods of this class are restricted to certain
261: * permissions as specified in the method comments.
262: *
263: * @param type a permission type.
264: * @return true if the specified permission is valid.
265: * @see ForumPermissions
266: */
267: public boolean hasPermission(int type);
268:
269: // AJOUT
270: /**
271: * return true if the message is approved
272: */
273: public boolean isApproved();
274:
275: public void setApproved(boolean approved)
276: throws UnauthorizedException;
277: }
|