Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface ForumMessage

All Superinterfaces:
JiveContentObject, JiveObject, Taggable, Watchable
All Known Implementing Classes:
DbForumMessage, EmailWatchMessageWrapper, ForumMessageProxy

public interface ForumMessage
extends JiveContentObject

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:

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:
ForumFactory.getMessage(long), ForumThread.getMessage(long)

Field Summary
 
Fields inherited from interface com.jivesoftware.forum.JiveContentObject
PLAIN_STRATEGY
 
Method Summary
 Attachment createAttachment(java.lang.String name, java.lang.String contentType, java.io.InputStream data)
          Creates a new attachment for this message.
 void deleteAttachment(Attachment attachment)
          Deletes an attachment that belongs to this message.
 void deleteProperty(java.lang.String name)
          Deletes an extended property.
 int getAttachmentCount()
          Returns the number of attachments this message has.
 java.util.Iterator getAttachments()
          Returns an Iterator for all the attachments of this message.
 java.lang.String getBody()
          Returns the message body.
 java.util.Date getCreationDate()
          Returns the date this message was created.
 Forum getForum()
          Returns the forum this message belongs to.
 int getForumIndex()
          Returns the index of this message in the forum.
 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.lang.String getPlainBody()
          Returns the message body with no html markup applied.
 java.lang.String getPlainSubject()
          Returns the message subject with no html markup applied.
 java.util.Collection getProperties(java.lang.String parentName)
          Return all immediate children property values of a parent property as an unmodifiable Collection of String values.
 java.lang.String getProperty(java.lang.String name)
          Returns an extended property of this message.
 java.util.Iterator getPropertyNames()
          Returns an Iterator of String values for all the names of the message properties.
 java.lang.String getSubject()
          Returns the message subject.
 TagDelegator getTagDelegator()
          Retrieve a tag delegator to manage message tags.
 java.lang.String getUnfilteredBody()
          Returns the message body, bypassing any active filters.
 java.lang.String getUnfilteredProperty(java.lang.String name)
          Returns an extended property of this message, bypassing any filters.
 java.lang.String getUnfilteredSubject()
          Returns the message subject, bypassing any active 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.
 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 setProperty(java.lang.String name, java.lang.String value)
          Sets an extended property of this message.
 void setSubject(java.lang.String subject)
          Sets the subject of this message.
 
Methods inherited from interface com.jivesoftware.base.JiveObject
getObjectType
 

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.

getForumIndex

int getForumIndex()
Returns the index of this message in the forum. The forum index is a sequential, incrementing value assigned to a message when it is added to a forum. Therefore, ordering messages by forum 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 forum to another it will get the next available forum index so will be out of creation date order.

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

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

Returns:
the forumIndex 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.

getPlainSubject

java.lang.String getPlainSubject()
Returns the message subject with no html markup applied. If message filters are active, the subject returned will be a filtered one with no html markup applied.

Specified by:
getPlainSubject in interface JiveContentObject
Returns:
the subject of the message with no html markup applied

getUnfilteredSubject

java.lang.String getUnfilteredSubject()
Returns the message subject, bypassing any active filters. Because filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving Jive content to another persistence mechanism such as an XML format. Another is when you need to skip filter formatting, such as when a user is responding to another user's message.

Specified by:
getUnfilteredSubject in interface JiveContentObject
Returns:
the subject of this message.

setSubject

void setSubject(java.lang.String subject)
                throws UnauthorizedException,
                       MessageRejectedException
Sets the subject of this message.

Parameters:
subject - the subject of this message.
Throws:
UnauthorizedException - if not allowed to edit this message.
MessageRejectedException - if an interceptor rejected the 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.

getPlainBody

java.lang.String getPlainBody()
Returns the message body with no html markup applied. If message filters are active, the body returned will be a filtered one with no html markup applied.

Specified by:
getPlainBody in interface JiveContentObject
Returns:
the body of the message with no html markup applied

getUnfilteredBody

java.lang.String getUnfilteredBody()
Returns the message body, bypassing any active filters. Because filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving Jive content to another persistence mechanism such as an XML format. Another is when you need to skip filter formatting, such as when a user is responding to another user's message.

Specified by:
getUnfilteredBody in interface JiveContentObject
Returns:
the unfiltered body of this message.

setBody

void setBody(java.lang.String body)
             throws UnauthorizedException,
                    MessageRejectedException
Sets the body of this message.

Parameters:
body - the body of this message.
Throws:
UnauthorizedException - if does not allowed to edit this message.
MessageRejectedException - if an interceptor rejected the 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

createAttachment

Attachment createAttachment(java.lang.String name,
                            java.lang.String contentType,
                            java.io.InputStream data)
                            throws AttachmentException,
                                   UnauthorizedException
Creates a new attachment for this message. Each attachment has a name, content type and binary data. Rules about who can create attachments and what kind attachments are allowed are controlled via an AttachmentManager.

Parameters:
name - the name of the new attachment, usually the file name.
contentType - the content type of the attachment.
data - an InputStream that contains the binary data of the attachment. The stream will never be closed so you must close it manually after calling this method.
Returns:
an Attachment object representing the new attachment created.
Throws:
AttachmentException - if an error occured while creating the attachment. Errors can occur because the attachment is too large or because the message already has too many attachments.
UnauthorizedException - if not allowed to create attachments.
See Also:
Attachment, AttachmentManager

getAttachmentCount

int getAttachmentCount()
Returns the number of attachments this message has.

Returns:
the number of attachments this message has.

deleteAttachment

void deleteAttachment(Attachment attachment)
                      throws AttachmentException,
                             UnauthorizedException
Deletes an attachment that belongs to this message. Only administrators or the creator of this message are allowed to call this method.

Parameters:
attachment - the attachment to delete.
Throws:
java.lang.IllegalArgumentException - if the attachment doesn't belong to the message.
UnauthorizedException - if not authorized to delete the attachment.
AttachmentException - if there was an error deleting the attachment.

getAttachments

java.util.Iterator getAttachments()
Returns an Iterator for all the attachments of this message.

Returns:
an Iterator for the message's attachments.
See Also:
Attachment

getModerationValue

int getModerationValue()
Returns the number of moderation points this message has. The default moderation value is determined by the forum this message belongs to: Forum.getModerationDefaultMessageValue()

If the moderation value is less than JiveConstants.FORUM_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.FORUM_MODERATION_VISIBLE, then a number of things will happen:

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 MODERATE_THREADS permissions.
See Also:
Gateway, WatchManager

getProperty

java.lang.String getProperty(java.lang.String name)
Returns an extended property of this message. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide enhanced functionality that is not part of the base interface.

For security reasons, you should enable an HTML filter in case properties contain malicious HTML code.

Parameters:
name - the name of the property to get.
Returns:
the value of the property.

getProperties

java.util.Collection getProperties(java.lang.String parentName)
Return all immediate children property values of a parent property as an unmodifiable Collection of String values. A parent/child relationship is denoted by the "." character. For example, given the properties X.Y.A, X.Y.B, X.Y.C and X.Y.C.D, then the immediate child properties of X.Y are X.Y.A, X.Y.B, and X.Y.C (the value of X.Y.C.D would not be returned using this method).

Parameters:
parentName - the name of the parent property to return the children for.
Returns:
all Collection of all child property values for the given parent.

getUnfilteredProperty

java.lang.String getUnfilteredProperty(java.lang.String name)
Returns an extended property of this message, bypassing any filters. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide 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.

setProperty

void setProperty(java.lang.String name,
                 java.lang.String value)
                 throws UnauthorizedException
Sets an extended property of this message. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide enhanced functionality that is not part of the base interface.

Parameters:
name - the name of the property to set.
value - the new value for the property.
Throws:
UnauthorizedException - if not allowed to edit the message.

deleteProperty

void deleteProperty(java.lang.String name)
                    throws UnauthorizedException
Deletes an extended property. If the property specified by name does not exist, this method will do nothing.

Parameters:
name - the name of the property to delete.
Throws:
UnauthorizedException - if not allowed to edit the message.

getPropertyNames

java.util.Iterator getPropertyNames()
Returns an Iterator of String values for all the names of the message properties.

Returns:
an Iterator for the names of all message properties.

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.

getForum

Forum getForum()
Returns the forum this message belongs to.

Returns:
the forum 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 forum administrator has a handle on this object, then calling isAuthorized(ForumPermissions.FORUM_ADMIN) would return true.

A list of possible permissions can be found in the ForumPermissions 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:
ForumPermissions

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

getTagDelegator

TagDelegator getTagDelegator()
Retrieve a tag delegator to manage message tags. Attempting to retrieve a tag delegator prior to the message being created will result in an IllegalStateArgument being thrown.

Returns:
a tag delegator to manage thread tags.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.