com.jivesoftware.community
Interface ForumThread

All Superinterfaces:

JiveContentObject, JiveObject

public interface ForumThread
extends JiveContentObject

A ForumThread is a container for a hierarchy of ForumMessages.

Every thread has a root message, which all other messages in the thread are children of. The root message must be supplied when creating a thread.

To get a ForumThread, the ForumManager.getForumThread(long) method is called from the ForumManager. To create a thread, use the Community.createThread(ForumMessage) method. After creating a thread, you must add it to the community by calling Community.addThread(ForumThread). To delete a ForumThread, call the ForumManager.deleteThread(ForumThread) method.

There are two options for navigating through the messages in a thread.

• A TreeWalker -- provides a hierarchical view of the messages in in the thread.
• An Iterable -- provides a flat view of the messages in the thread. This view of thread is useful for skins that want to provide functionality such as listing all the messages in the order they were created, etc.

Because a root message must be passed in when creating a thread, you must first create that message before creating the thread. The following code snippet demonstrates:

 // Assume that a community object and user object are already defined.
 ForumMessage rootMessage = community.createMessage(user);
 rootMessage.setSubject("A subject");
 rootMessage.setBody("A body");
 ForumThread thread = community.createThread(rootMessage);
 community.addThread(thread);
 

Field Summary

Fields inherited from interface com.jivesoftware.community.JiveContentObject

BODY_FIELD, SUBJECT_FIELD

Method Summary

void	addMessage(ForumMessage parentMessage, ForumMessage newMessage) Adds a new message to this thread.
void	deleteMessage(ForumMessage message) Deletes a message in this thread.
void	deleteMessage(ForumMessage message, boolean deleteChildren) Deletes a message in this thread, optionally recusively deleting child messages.
long	getBranchedParentThreadID() Returns the ID of the thread this was branched from, if any, else null.
long	getBranchedThreadID() Returns the ID of a brached thread, or null if no thread is branched from this one.
Community	getCommunity() Returns the community this thread belongs to.
java.util.Date	getCreationDate() Returns the date that this thread was created.
long	getID() Returns the unique ID of this thread, or -1 if the thread hasn't been added to the database yet.
ForumMessage	getLatestMessage() Returns the most recently created messages in this thread.
ForumMessage	getMessage(long messageID) Returns a message from this thread based on its id.
int	getMessageCount() Returns the number of messages in the thread.
int	getMessageCount(ThreadResultFilter resultFilter) Returns the number of messages in this thread based on the specified result filter.
JiveIterator<ForumMessage>	getMessages() Return an Iterable for all the messages in this thread.
JiveIterator<ForumMessage>	getMessages(ThreadResultFilter resultFilter) Returns a Iterable for all the messages in the thread that match the criteria specified by the ResultFilter.
int	getModerationValue() Returns the number of moderation points this thread has.
java.util.Date	getModificationDate() Returns the date that this thread was last modified.
java.lang.String	getName() Returns the subject of the root message of this thread.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Retrieve a map of all the extended properties for the thread.
Question	getQuestion() Returns the question associated with a thread or null if the question does not exist.
com.jivesoftware.community.RatingDelegator	getRatingDelegator() Retrieve a rating delegator to manage thread ratings.
ForumMessage	getRootMessage() Returns the root message this thread.
com.jivesoftware.community.TagDelegator	getTagDelegator() Retrieve a tag delegator to manage thread tags.
TrackbackManager	getTrackbackManager() Retrieve a trackback manager to manage thread trackbacks.
TreeWalker	getTreeWalker() Returns the TreeWalker for this thread.
int	getViewCount() Returns the number of times this thread has been viewed.
boolean	hasQuestion() Returns true if this thread has been marked as a question.
boolean	isAuthorized(long permissionType) Returns true if the handle on the object has the permission specified.
boolean	isRead(User user) Returns true if this thread has been read by the user, false otherwise.
boolean	isUnread(User user) Returns true if this thread has not been read by the user, false otherwise.
boolean	isUpdated(User user) Returns true if this thread has been updated since read by the user, false otherwise.
void	setCreationDate(java.util.Date creationDate) Sets the creation date of this thread.
void	setModerationValue(int value, AuthToken authToken) Sets the number of moderation points this thread has.
void	setModificationDate(java.util.Date modificationDate) Sets the date this thread was last modified.

Methods inherited from interface com.jivesoftware.community.JiveContentObject

getBody, getIndexContent, getPlainBody, getPlainSubject, getSubject, getUnfilteredBody, getUnfilteredSubject, getUser

Methods inherited from interface com.jivesoftware.community.JiveObject

getObjectType

Method Detail

getID

long getID()

Returns the unique ID of this thread, or -1 if the thread hasn't been added to the database yet.

Specified by:

getID in interface JiveObject

Returns:

the unique ID of the thread.

getName

java.lang.String getName()

Returns the subject of the root message of this thread. This is a convenience method equivalent to getRootMessage().getSubject().

Returns:

the name of this thread, which is the subject of the root message.

getCreationDate

java.util.Date getCreationDate()

Returns the date that this thread was created.

Specified by:

getCreationDate in interface JiveContentObject

Returns:

the date this thread was created.

setCreationDate

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

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

Parameters:

creationDate - the date this thread was created.

Throws:

UnauthorizedException - if not an administrator.

getModificationDate

java.util.Date getModificationDate()

Returns the date that this thread was last modified. In other words, the date of the most recent message in the thread.

Specified by:

getModificationDate in interface JiveContentObject

Returns:

the date this thread was last modified.

setModificationDate

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

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

Parameters:

modificationDate - the date this thread was modified.

Throws:

UnauthorizedException - if not an administrator.

getModerationValue

int getModerationValue()

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

If the moderation value is less than JiveConstants.MESSAGE_MODERATION_VISIBLE then the thread will not be displayed by default. Because a thread and its root message are intrinsically bound together, their moderation values are linked and are always the same. This means that setting the moderation value on the thread or setting the moderation value of a root message will always affect both objects.

Returns:

the number of moderation points the thread has.

setModerationValue

void setModerationValue(int value,
                        AuthToken authToken)
                        throws UnauthorizedException

Sets the number of moderation points this thread has. If the moderation value is less than JiveConstants.MESSAGE_MODERATION_VISIBLE then the thread will not be displayed by default. Because a thread and its root message must always go together, their moderation values are linked and are always the same. This means that setting the moderation value on the thread or setting the moderation value of a root message will always affect both objects.

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

Parameters:

value - the number of moderation points for this thread.

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

Throws:

UnauthorizedException - if not a moderator or administrator.

hasQuestion

boolean hasQuestion()

Returns true if this thread has been marked as a question.

Returns:

true if this thread has been marked as a question.

getQuestion

Question getQuestion()

Returns the question associated with a thread or null if the question does not exist.

Returns:

the question associated with a thread.

getProperties

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

Retrieve a map of all the extended properties for the thread. Each thread 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 thread. Null keys and values are not allowed.

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

Returns:

a map of thread extended properties.

getCommunity

Community getCommunity()

Returns the community this thread belongs to.

Returns:

the community this thread belongs to.

getMessage

ForumMessage getMessage(long messageID)
                        throws ForumMessageNotFoundException

Returns a message from this thread based on its id.

Parameters:

messageID - the ID of the message to get from this thread.

Throws:

ForumMessageNotFoundException

getRootMessage

ForumMessage getRootMessage()

Returns the root message this thread. The root message is a special first message that is intimately tied to the thread for most communityViews. All other messages in the thread are children of the root message.

Returns:

the root message of this thread.

getLatestMessage

ForumMessage getLatestMessage()

Returns the most recently created messages in this thread. This information could also be determined using a ThreadResultFilter, but this method offers a simpler, more optimized way to access the data.

Returns:

the most recently created message in this thread.

getMessageCount

int getMessageCount()

Returns the number of messages in the thread. This includes the root message. So, to find the number of replies to the root message, subtract one from the answer of this method.

Returns:

the number of messages in this thread.

getMessageCount

int getMessageCount(ThreadResultFilter resultFilter)

Returns the number of messages in this thread based on the specified result filter. This includes the root message. So, to find the number of replies to the root message, subtract one from the answer of this method.

Parameters:

resultFilter - a filter to limit the message count query, such as date or moderation value range.

Returns:

the number of messages in this thread based on a ResultFilter.

addMessage

void addMessage(ForumMessage parentMessage,
                ForumMessage newMessage)
                throws RejectedException,
                       UnauthorizedException

Adds a new message to this thread. It is not legal to add a message to a thread before the thread has been added to a community.

When a message is being added, it is first run through all message interceptors that are installed. Each interceptor has the option to reject the message by throwing a RejectedException. For example, an interceptor might reject all messages coming from a certain IP.

Parameters:

parentMessage - some message in this thread that will be parent.

newMessage - message to add to this thread under the parent.

Throws:

RejectedException - if one of the installed interceptors prevents the message from being posted.

UnauthorizedException - if does not have CREATE_MESSAGE permissions.

See Also:

JiveInterceptor

deleteMessage

void deleteMessage(ForumMessage message)
                   throws UnauthorizedException

Deletes a message in this thread. Deleting a message also deletes all of its children messages. The search index and other resources that referenced the message and its children will also be updated appropriately.

Parameters:

message - the message to delete.

Throws:

java.lang.IllegalArgumentException - if the message does not belong to the thread.

UnauthorizedException - if does not have permission to delete messages.

deleteMessage

void deleteMessage(ForumMessage message,
                   boolean deleteChildren)
                   throws UnauthorizedException

Deletes a message in this thread, optionally recusively deleting child messages. Passing in true to this method is equivalent to calling the deleteMessage(ForumMessage) method since it will recursively delete all child messages of the message. If deleteChildren is false, then child messages will not be deleted. Instead, they will be made children of the message's parent message. As an example, consider the following thread:

 A
 |-- B
     |-- C
     |-- D
         |-- E
 

If message B is deleted with deleteChildren set to true, then messages C, D, and E will also be deleted. If deleteChildren is set to false, then the new message structure will be:

 A
 |-- C
 |-- D
     |-- E
 

Note: because the root message has no parent messages, an IllegalArgumentException will thrown if message is the root message and deleteChildren is true.

Parameters:

message - the message to delete.

deleteChildren - true if child messages should be deleted, false if child messages should be moved to be children of the message's parent.

Throws:

java.lang.IllegalArgumentException - if the message does not belong to the thread or if the message is the root message.

UnauthorizedException - if does not have permission to delete messages.

getTreeWalker

TreeWalker getTreeWalker()

Returns the TreeWalker for this thread. A TreeWalker is used to navigate through the tree of messages in a hierarchical manner.

Returns:

the tree walker for this thread.

getMessages

JiveIterator<ForumMessage> getMessages()

Return an Iterable for all the messages in this thread.

Returns:

an Iterable for all messages in this thread.

getMessages

JiveIterator<ForumMessage> getMessages(ThreadResultFilter resultFilter)

Returns a Iterable for all the messages in the thread that match the criteria specified by the ResultFilter.

Parameters:

resultFilter - a ResultFilter object to perform filtering and sorting with.

Returns:

an Iterable for the messages in the thread that match the ResultFilter.

isAuthorized

boolean isAuthorized(long permissionType)

Returns true if the handle on the 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 - a permission type.

Returns:

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

See Also:

Permissions

isRead

boolean isRead(User user)

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

Parameters:

user - the user to check read stats for this thread

Returns:

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

isUnread

boolean isUnread(User user)

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

Parameters:

user - the user to check read stats for this thread

Returns:

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

isUpdated

boolean isUpdated(User user)

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

Parameters:

user - the user to check read stats for this thread

Returns:

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

getViewCount

int getViewCount()

Returns the number of times this thread has been viewed. A return value of -1 indicates the number of views is unknown or that the feature is disabled.

Returns:

the number of times this thread has been viewed or -1 if the value is not known.

getBranchedParentThreadID

long getBranchedParentThreadID()

Returns the ID of the thread this was branched from, if any, else null.

Returns:

the ID of the thread this was branched from, if any, else null.

getBranchedThreadID

long getBranchedThreadID()

Returns the ID of a brached thread, or null if no thread is branched from this one.

Returns:

the ID of a new thread, if a new thread was branched from this message, null otherwise.

getTagDelegator

com.jivesoftware.community.TagDelegator getTagDelegator()

Retrieve a tag delegator to manage thread tags. Attempting to retrieve a tag delegator prior to the thread being created will result in an IllegalStateArgument being thrown.

Returns:

a tag delegator to manage thread tags.

getTrackbackManager

TrackbackManager getTrackbackManager()

Retrieve a trackback manager to manage thread trackbacks. Attempting to retrieve a trackback manager prior to the thread being saved will result in an IllegalStateException being thrown.

Returns:

a trackback manager to manage thread trackbacks.

getRatingDelegator

com.jivesoftware.community.RatingDelegator getRatingDelegator()

Retrieve a rating delegator to manage thread ratings. Attempting to retrieve a rating delegator prior to the thread being saved will result in an IllegalStateArgument being thrown.

Returns:

a rating delegator to manage thread ratings.