Jive Forums API (5.5.20.2-oracle) Core Javadocs

com.jivesoftware.forum
Interface ForumThread

All Superinterfaces:
JiveContentObject, JiveObject, com.jivesoftware.forum.Taggable, Watchable

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 Forum.getThread(long) method is called from a Forum object. To create a thread, use the Forum.createThread(ForumMessage) method. After creating a thread, you must add it to the forum by calling Forum.addThread(ForumThread). To delete a ForumThread, call the Forum.deleteThread(ForumThread) method.

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

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 forum object and user object are already defined.
 ForumMessage rootMessage = forum.createMessage(user);
 rootMessage.setSubject("A subject");
 rootMessage.setBody("A body");
 ForumThread thread = forum.createThread(rootMessage);
 forum.addThread(thread);
 


Field Summary
 
Fields inherited from interface com.jivesoftware.forum.JiveContentObject
PLAIN_STRATEGY
 
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.
 void deleteProperty(java.lang.String name)
          Deletes an extended property.
 java.util.Date getCreationDate()
          Returns the date that this thread was created.
 Forum getForum()
          Returns the forum this thread belongs to.
 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(ResultFilter resultFilter)
          Returns the number of messages in this thread based on the specified result filter.
 java.util.Iterator getMessages()
          Return an Iterator for all the messages in this thread.
 java.util.Iterator getMessages(ResultFilter resultFilter)
          Returns a Iterator 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.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 thread.
 java.util.Iterator getPropertyNames()
          Returns an Iterator for the names of this thread's properties.
 ForumMessage getRootMessage()
          Returns the root message this thread.
 com.jivesoftware.forum.TagDelegator getTagDelegator()
          Retrieve a tag delegator to manage thread tags.
 TreeWalker getTreeWalker()
          Returns the TreeWalker for this thread.
 boolean isAuthorized(long permissionType)
          Returns true if the handle on the object has the permission specified.
 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.
 void setProperty(java.lang.String name, java.lang.String value)
          Sets an extended property of this thread.
 
Methods inherited from interface com.jivesoftware.forum.JiveContentObject
getBody, getPlainBody, getPlainSubject, getSubject, getUnfilteredBody, getUnfilteredSubject, getUser
 
Methods inherited from interface com.jivesoftware.base.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 forum this thread belongs to: Forum.getModerationDefaultThreadValue()

If the moderation value is less than JiveConstants.FORUM_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.FORUM_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.

getProperty

java.lang.String getProperty(java.lang.String name)
Returns an extended property of this thread. Each thread can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface.

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

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.

setProperty

void setProperty(java.lang.String name,
                 java.lang.String value)
                 throws UnauthorizedException
Sets an extended property of this 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 user that created the thread (author of rootMessage), or system or forum admins can always call this method. Additionally, anyone (including anonymous users) can call this method before the thread has been added to a Forum.

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

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.

The user that created the thread (author of rootMessage), or system or forum admins can always call this method. Additionally, anyone (including anonymous users) can call this method before the thread has been added to a Forum.

Parameters:
name - the name of the property to delete.
Throws:
UnauthorizedException - if not allowed to delete extended properties.

getPropertyNames

java.util.Iterator getPropertyNames()
Returns an Iterator for the names of this thread's properties.

Returns:
an Iterator for the names of this thread's properties.

getForum

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

Returns:
the forum 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 forumViews. 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 ResultFilter, 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(ResultFilter 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 MessageRejectedException,
                       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 forum.

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 MessageRejectedException. 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:
MessageRejectedException - if one of the installed interceptors prevents the message from being posted.
UnauthorizedException - if does not have CREATE_MESSAGE permissions.
See Also:
MessageInterceptor

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

java.util.Iterator getMessages()
Return an Iterator for all the messages in this thread.

Returns:
an Iterator for all messages in this thread.

getMessages

java.util.Iterator getMessages(ResultFilter resultFilter)
Returns a Iterator 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 Iterator 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 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 - a permission type.
Returns:
true if the handle on the object has the specified permission.
See Also:
ForumPermissions

getTagDelegator

com.jivesoftware.forum.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.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.