com.jivesoftware.community
Interface ForumThread

All Superinterfaces:

com.jivesoftware.community.ContainerAware, 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 ForumManager.createThread(JiveContainer,ForumMessage) method. After creating a thread, you must add it to the community by calling ForumManager.addThread(JiveContainer,ForumThread). To delete a ForumThread, call the ForumManager.deleteThread(ForumThread)

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 = forumManager.createMessage(community, user);
 rootMessage.setSubject("A subject");
 rootMessage.setBody("A body");
 ForumThread thread = forummManager.createThread(community, rootMessage);
 forumManager.addThread(community, thread);
 

Nested Class Summary

Nested classes/interfaces inherited from interface com.jivesoftware.community.JiveContentObject

JiveContentObject.Field, JiveContentObject.Status

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.
long	getContainerID() Returns the id of the container object of the thread.
int	getContainerType() Returns the type of the container object of the thread.
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.
JiveContainer	getJiveContainer() Returns the container object of the thread.
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.
Date	getModificationDate() Returns the date that this thread was last modified.
String	getName() Returns the subject of the root message of this thread.
Map<String,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.
com.jivesoftware.community.TrackbackDelegator	getTrackbackDelegator() Retrieve a trackback delegator 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	refreshMessageCount() Forces a message count refresh from the database.
void	setCreationDate(Date creationDate) Sets the creation date of this thread.
void	setModerationValue(int value) Sets the number of moderation points this thread has.
void	setModificationDate(Date modificationDate) Sets the date this thread was last modified.
void	setStatus(JiveContentObject.Status status) Sets the status of this message

Methods inherited from interface com.jivesoftware.community.JiveContentObject

getBody, getIndexContent, getPlainBody, getPlainSubject, getStatus, getSubject, 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

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

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(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

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(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)
                        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.

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

Map<String,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.

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.

refreshMessageCount

void refreshMessageCount()

Forces a message count refresh from the database. Useful if the thread was recently branched.

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:

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:

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.

getTrackbackDelegator

com.jivesoftware.community.TrackbackDelegator getTrackbackDelegator()

Retrieve a trackback delegator to manage thread trackbacks. Attempting to retrieve a trackback delegator 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.

getContainerType

int getContainerType()

Returns the type of the container object of the thread.

Specified by:

getContainerType in interface com.jivesoftware.community.ContainerAware

Specified by:

getContainerType in interface JiveContentObject

Returns:

the type of the container object of the thread.

getContainerID

long getContainerID()

Returns the id of the container object of the thread.

Specified by:

getContainerID in interface com.jivesoftware.community.ContainerAware

Specified by:

getContainerID in interface JiveContentObject

Returns:

the id of the container object of the thread.

getJiveContainer

JiveContainer getJiveContainer()

Returns the container object of the thread.

Returns:

the container object of the thread.

setStatus

void setStatus(JiveContentObject.Status status)
               throws UnauthorizedException

Sets the status of this message

Parameters:

status - the status of the message.

Throws:

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