com.jivesoftware.community
Interface ForumMessage

All Superinterfaces:

AttachmentContentResource, ImageContentResource, JiveContentObject, JiveObject

public interface ForumMessage
extends JiveContentObject, AttachmentContentResource, ImageContentResource

A ForumMessage encapsulates message data. Each message belongs to a thread, and relates to other messages in a thread in a tree relationship. This system allows messages to represent threaded conversations. For example:

   [thread]
        |- [message]
        |- [message]
                 |- [message]
                 |- [message]
                          |- [message]
        |- [message]
 

Each message has a subject and body. Messages are authored by a user in the system or can be anonymous. An ID is given to each message so that it can be tracked uniquely. Because is possible that one might want to store more information with each message besides a subject and body, each message can have an arbitrary number of properties. For example, a property "IPAddress" could be stored with each message that records the IP address of the person posting the message for security reasons.

The creation date, and the date the message was last modified are maintained for each message. These values are normally maintained automatically by the system and do not need to be set explicitly except in special circumstances.

Message editing has a number of rules:

• System or community administrators can edit any message at any time.
• The message author can edit a message at any time.
• Anonymous messages can be edited by anonyone before being added to a thread. After being added to a thread, only system or community can edit them.

Of course, these message editing rules can be made more strict by a skin. For example, you may choose to never allow anyone to edit messages, or only messages to be edited for the first fifteen minutes after they are posted.

For added functionality, any number of filters can be applied to a message. Filters dynamically format the subject and body of a message. Methods are also provided to bypass filters.

See Also:

ForumManager.getMessage(long), ForumThread.getMessage(long)

Field Summary

Fields inherited from interface com.jivesoftware.community.JiveContentObject

BODY_FIELD, SUBJECT_FIELD

Method Summary

java.lang.String	getBody() Returns the message body.
Community	getCommunity() Returns the community this message belongs to.
int	getCommunityIndex() Returns the index of this message in the community.
java.util.Date	getCreationDate() Returns the date this message was created.
ForumThread	getForumThread() Returns the thread this message belongs to.
long	getID() Returns the id of this message, or -1 if this message hasn't been added to the database yet.
int	getModerationValue() Returns the number of moderation points this message has.
java.util.Date	getModificationDate() Returns the date this message was last modified.
ForumMessage	getParentMessage() Returns the parent message of this message or null if this message is the root message of a thread.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Retrieve a map of all the extended properties for the message.
java.lang.String	getSubject() Returns the message subject.
java.lang.String	getUnfilteredProperty(java.lang.String name) Returns an extended property of the message, bypassing any filters.
User	getUser() Returns the User that authored this message.
boolean	isAnonymous() Returns true if this message was posted anonymously.
boolean	isAuthorized(long permissionType) Returns true if the handle on this object has the permission specified.
boolean	isHtml() Returns true if this body of this message contains HTML.
boolean	isRead(User user) Returns true if this message has been read by the user, false otherwise.
boolean	isUnread(User user) Returns true if this message has not been read by the user, false otherwise.
boolean	isUpdated(User user) Returns true if this message has been updated since read by the user, false otherwise.
void	setBody(java.lang.String body) Sets the body of this message.
void	setCreationDate(java.util.Date creationDate) Sets the creation date of this message.
void	setModerationValue(int value, AuthToken authToken) Sets the number of moderation points this message has.
void	setModificationDate(java.util.Date modificationDate) Sets the date this message was last modified.
void	setSubject(java.lang.String subject) Sets the subject of this message.

Methods inherited from interface com.jivesoftware.community.JiveContentObject

getIndexContent, getPlainBody, getPlainSubject, getUnfilteredBody, getUnfilteredSubject

Methods inherited from interface com.jivesoftware.community.JiveObject

getObjectType

Methods inherited from interface com.jivesoftware.community.AttachmentContentResource

createAttachment, deleteAttachment, getAttachment, getAttachmentCount, getAttachments

Methods inherited from interface com.jivesoftware.community.ImageContentResource

addImage, createImage, deleteImage, getImage, getImageCount, getImages

Method Detail

getID

long getID()

Returns the id of this message, or -1 if this message hasn't been added to the database yet.

Specified by:

getID in interface JiveObject

Returns:

the unique id of this message.

getCommunityIndex

int getCommunityIndex()

Returns the index of this message in the community. The community index is a sequential, incrementing value assigned to a message when it is added to a community. Therefore, ordering messages by community index is generally equivalent to ordering by creation date. There are exceptions to this rule, however; for example, when a message is moved from one community to another it will get the next available community index so will be out of creation date order.

Once a community index is assigned to a message, that value is never re-used. Therefore, there will be gaps in the community index values as messages are deleted, archived, or moved.

Community index values are primarily provided to support an NNTP-centric view of communitys, since the NNTP protocol requires article numbers (community indexes) inside a newsgroup (community).

Returns:

the communityIndex of this message.

getCreationDate

java.util.Date getCreationDate()

Returns the date this message was created.

Specified by:

getCreationDate in interface JiveContentObject

Returns:

the date this message was created.

setCreationDate

void setCreationDate(java.util.Date creationDate)
                     throws UnauthorizedException

Sets the creation date of this message. In most cases, the creation date will default to when the message was entered into the system. However, the creation date needs to be set manually when importing messages. In other words, skin authors should ignore this method since it only intended for system maintenance.

Parameters:

creationDate - the date this message was created.

Throws:

UnauthorizedException - if does not have ADMIN permissions.

getModificationDate

java.util.Date getModificationDate()

Returns the date this message was last modified. When a message is first created, the date returned by this method is identical to the creation date. The modified date is updated every time a message property is updated, such as the message body.

Specified by:

getModificationDate in interface JiveContentObject

Returns:

the date this message was last modified.

setModificationDate

void setModificationDate(java.util.Date modificationDate)
                         throws UnauthorizedException

Sets the date this message was last modified. In most cases, last modifed will default to when the message data was last changed. However, the last modified date needs to be set manually when importing messages. In other words, skin authors should ignore this method since it only intended for system maintenance.

Parameters:

modificationDate - the date this message was modified.

Throws:

UnauthorizedException - if not allowed to edit the message.

getSubject

java.lang.String getSubject()

Returns the message subject. If message filters are active, the subject returned will be a filtered one. Because filters often provide security functionality, this method is the preferred way to get the subject of a message.

Specified by:

getSubject in interface JiveContentObject

Returns:

the subject of this message.

setSubject

void setSubject(java.lang.String subject)
                throws UnauthorizedException

Sets the subject of this message.

Parameters:

subject - the subject of this message.

Throws:

UnauthorizedException - if not allowed to edit this message.

getBody

java.lang.String getBody()

Returns the message body. If message filters are active, the body returned will be a filtered one. Because filters often provide security functionality such as stripping out HTML and Javascript, this method is the preferred way to get the body of a message.

Specified by:

getBody in interface JiveContentObject

Returns:

the body of this message.

setBody

void setBody(java.lang.String body)
             throws UnauthorizedException

Sets the body of this message.

Parameters:

body - the body of this message.

Throws:

UnauthorizedException - if does not allowed to edit this message.

getUser

User getUser()

Returns the User that authored this message. If the message was created anonymously, this method will return null.

Specified by:

getUser in interface JiveContentObject

Returns:

the author of the message.

getParentMessage

ForumMessage getParentMessage()

Returns the parent message of this message or null if this message is the root message of a thread. See TreeWalker for similiar functionality.

Returns:

the parent message of this message or null if this message is a root message

getModerationValue

int getModerationValue()

Returns the number of moderation points this message has. The default moderation value is determined by the community this message belongs to: Community.getModerationDefaultMessageValue()

If the moderation value is less than JiveConstants.MESSAGE_MODERATION_VISIBLE then the message will not be displayed by default.

Returns:

the number of moderation points the message has.

setModerationValue

void setModerationValue(int value,
                        AuthToken authToken)
                        throws UnauthorizedException

Sets the number of moderation points this message has. If the moderation value is less than than JiveConstants.MESSAGE_MODERATION_VISIBLE, then a number of things will happen:

• The message will not be visible in the thread by default.
• The thread and community of the message will not have their modified date's updated.
• The message will not be exported to installed gateways.
• Watch updates will not be triggered.

When calling this method results in a message to go from below the minimum visible threshold to above, then the actions listed above will all be executed. Any change of the moderation value also results in the modified date of the message being updated.

Only administrators and moderators can call this method.

The authToken token of the user must be passed into this method as a paramater for moderation auditing purposes.

Parameters:

value - the number of moderation points for the message.

authToken - the AuthToken token of the user that is making the moderation decision.

Throws:

UnauthorizedException - if does not have ADMIN, MODERATE_MESSAGES or MODERATOR permissions.

See Also:

Gateway, WatchManager

getProperties

java.util.Map<java.lang.String,java.lang.String> getProperties()

Retrieve a map of all the extended properties for the message. Each message can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface. The map is alterable if the user is authorized to modify the message. Null keys and values are not allowed.

If the user is not authorized to modify the message any method which modifies the map will fail with a UnsupportedOperationException;

Returns:

a map of message extended properties.

getUnfilteredProperty

java.lang.String getUnfilteredProperty(java.lang.String name)

Returns an extended property of the message, bypassing any filters. Each message can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface.

Because properties are not filtered before being returned, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Parameters:

name - the name of the property to get.

Returns:

the value of the property.

isAnonymous

boolean isAnonymous()

Returns true if this message was posted anonymously. This is a convenience method for: message.getUser() != null.

Returns:

true if this message was posted anonymously.

getForumThread

ForumThread getForumThread()

Returns the thread this message belongs to.

Returns:

the thread this message belongs to.

getCommunity

Community getCommunity()

Returns the community this message belongs to.

Returns:

the community this message belongs to.

isAuthorized

boolean isAuthorized(long permissionType)

Returns true if the handle on this object has the permission specified. For example, if a community administrator has a handle on this object, then calling isAuthorized(Permissions.COMMUNITY_ADMIN) would return true.

A list of possible permissions can be found in the Permissions class. Certain methods of this class are restricted to certain permissions as specified in the method comments.

Parameters:

permissionType - permissionType a permission type.

Returns:

true if the handle on the object has the specified permission.

See Also:

Permissions

isHtml

boolean isHtml()

Returns true if this body of this message contains HTML. This is determined by the DbForumMessage.PROP_CONTENT_TYPE extended property being set to DbForumMessage.TEXT_HTML.

Returns:

true if the content type is text/html

isRead

boolean isRead(User user)

Returns true if this message has been read by the user, false otherwise.

Parameters:

user - the user to check read stats for this message

Returns:

true if this message has been read by the user, false otherwise

isUnread

boolean isUnread(User user)

Returns true if this message has not been read by the user, false otherwise.

Parameters:

user - the user to check read stats for this message

Returns:

true if this message has not been read by the user, false otherwise

isUpdated

boolean isUpdated(User user)

Returns true if this message has been updated since read by the user, false otherwise.

Parameters:

user - the user to check read stats for this message

Returns:

true if this message has been updated since read by the user, false otherwise