com.jivesoftware.community
Interface ForumManager

All Superinterfaces:

JiveManager

public interface ForumManager
extends JiveManager

This manager provides methods to load forum threads, user messages and to retrieve popular forum threads.

See Also:

JiveContext

Method Summary

void	addMessage(ForumThread thread, ForumMessage parentMessage, ForumMessage newMessage) Adds a new message to a given thread.
void	addThread(JiveContainer container, ForumThread thread) Adds a new thread to the container.
ForumMessage	createMessage(JiveContainer container) Factory method to create a message with an anonymous author.
ForumMessage	createMessage(JiveContainer container, User user) Factory method to create a message as the specified user.
ForumThread	createThread(JiveContainer container, ForumMessage rootMessage) Factory method to create a new thread.
void	deleteMessage(ForumThread thread, ForumMessage message) Deletes a message from the given thread.
void	deleteMessage(ForumThread thread, ForumMessage message, boolean deleteChildren) Deletes a message and (optionally) all of its child messages from the given thread.
void	deleteThread(ForumThread thread) Deletes a thread and all of its messages.
void	deleteUserMessages(User user) Deletes all messages authored by a given user.
ForumThread	getForumThread(long threadID) Returns the thread with the specified threadID.
ForumMessage	getLatestMessage(JiveContainer container) Returns the most recently created or edited message in this container (including all sub-containers if applicable).
ForumMessage	getLatestMessage(TagSet tagSet) Returns the most recently created or edited message in this tag set .
ForumMessage	getMessage(long messageID) Returns the forum message with the specified messageID.
int	getMessageCount(JiveContainer container) Acquire the count of all messages for a specified container.
int	getMessageCount(JiveContainer container, ThreadResultFilter resultFilter) The account of messages for the JiveContainer with the ThreadResultFilter applied.
int	getMessageCount(TagSet tagSet) Acquire the count of all messages for a specified tag set.
int	getMessageCount(TagSet tagSet, ThreadResultFilter resultFilter) The account of messages for the TagSet with the ThreadResultFilter applied.
JiveIterator<ForumMessage>	getMessages(JiveContainer container) Returns an Iterable for all the messages in the container.
JiveIterator<ForumMessage>	getMessages(JiveContainer container, ThreadResultFilter resultFilter) Returns an Iterable for all the messages in the container that match the criteria specified by the ResultFilter.
JiveIterator<ForumMessage>	getMessages(TagSet tagSet) Returns an Iterable for all the messages in the tag set.
JiveIterator<ForumMessage>	getMessages(TagSet tagSet, ThreadResultFilter resultFilter) Returns an Iterable for all the messages in the tag set that match the criteria specified by the ResultFilter.
JiveIterator<ForumThread>	getPopularThreads() Returns an Iterable for the most threads in the system as ForumThread objects.
int	getThreadCount(JiveContainer container) Returns the number of threads in the container.
int	getThreadCount(JiveContainer container, ThreadResultFilter resultFilter) Returns the number of threads in the container based on the specified ResultFilter.
int	getThreadCount(TagSet tagSet) Returns the number of threads in the tag set.
int	getThreadCount(TagSet tagSet, ThreadResultFilter resultFilter) Returns the number of threads in the tag set based on the specified ResultFilter.
JiveIterator<ForumThread>	getThreads(JiveContainer container) Returns an Iterable for all the threads in the container.
JiveIterator<ForumThread>	getThreads(JiveContainer container, ThreadResultFilter resultFilter) Returns an Iterable for all the threads in the container that match the criteria specified by the ResultFilter.
JiveIterator<ForumThread>	getThreads(TagSet tagSet) Returns an Iterable for all the threads in the tag set.
JiveIterator<ForumThread>	getThreads(TagSet tagSet, ThreadResultFilter resultFilter) Returns an Iterable for all the threads in the tag set that match the criteria specified by the ResultFilter.
int	getUserMessageCount(User user) Returns the total number of messages a user has posted in all containers.
int	getUserMessageCount(User user, ThreadResultFilter resultFilter) Returns the total number of messages a user has posted in all containers that obey the parameters set by the specificed ResultFilter.
JiveIterator<ForumMessage>	getUserMessages(User user) Returns an iterable for all messages posted by a user.
JiveIterator<ForumMessage>	getUserMessages(User user, ThreadResultFilter resultFilter) Returns an iterable for all messages posted by a user that obey the parameters set by the specified ResultFilter.
boolean	isModerationEnabled() Returns true if moderation has been enabled by setting the Jive property "database.moderationEnabled" to true.
void	moveMessage(ForumMessage message, ForumThread newThread, long parentMessageID) Moves a message to another thread.
void	moveThread(ForumThread thread, JiveContainer newContainer) Moves a thread from one container to another.
void	update(ForumMessage message) Persists message changes, and broadcasts changes across the cluster.
void	update(ForumThread thread) Persists thread changes, and broadcasts changes across the cluster.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy

Method Detail

getForumThread

ForumThread getForumThread(long threadID)
                           throws ForumThreadNotFoundException,
                                  UnauthorizedException

Returns the thread with the specified threadID.

Parameters:

threadID - the id of the thread to return.

Returns:

the ForumThread specified by threadID.

Throws:

UnauthorizedException - if not allowed to read the thread.

ForumThreadNotFoundException - if the requested thread does not exist.

getMessage

ForumMessage getMessage(long messageID)
                        throws ForumMessageNotFoundException,
                               UnauthorizedException

Returns the forum message with the specified messageID.

Parameters:

messageID - the id of the message to return.

Returns:

the ForumMessage specified by messageID.

Throws:

UnauthorizedException - if not allowed to read the message.

ForumMessageNotFoundException - if the requested message does not exist.

getPopularThreads

JiveIterator<ForumThread> getPopularThreads()

Returns an Iterable for the most threads in the system as ForumThread objects. Popular threads are defined as those that have the most new messages over a period of time (e.g. the last 24 hours).

A number of configurable Jive properties control how the popular threads feature works:

• popularThreads.number -- The number of threads that will be returned in the list of popular threads. Default is 4.
• popularThreads.timeWindow -- The number of hours to consider new messages in a thread from. Default is 24 hours, which is suitable for sites with moderate to high amounts of traffic. Sites with less traffic may wish to set the window to a number of days.

Returns:

an Iterable of ForumThread objects for the most popular threads.

moveThread

void moveThread(ForumThread thread,
                JiveContainer newContainer)
                throws UnauthorizedException

Moves a thread from one container to another. For this to work, the user calling this method must have admin or moderator permissions for the container the thread currently belongs to and the newContainer.

The main purpose of this method is to allow admins to move non-topical threads into a more appropriate container.

Parameters:

thread - the thread to move to another container.

newContainer - the new container to move the thread to

Throws:

UnauthorizedException - if does not have admin or moderator permissions for the thread's current container and the newContainer.

deleteThread

void deleteThread(ForumThread thread)
                  throws UnauthorizedException

Deletes a thread and all of its messages. Once a thread is deleted, the thread object should no longer be used. The search index and other resources that referenced the thread and its messages will also be updated appropriately.

Parameters:

thread - the thread to delete.

Throws:

UnauthorizedException - if not an admin or moderator of the thread's container

getUserMessageCount

int getUserMessageCount(User user)

Returns the total number of messages a user has posted in all containers. Warning: containers that the current user doesn't have read access for will also be included in the total, so you should use caution if that information should be private.

In order to get a count of user messages in an individual containers, use the getMessageCount(JiveContainer ,ThreadResultFilter) method.

Parameters:

user - the user to tally results for.

Returns:

the number of messages the user has posted.

getUserMessageCount

int getUserMessageCount(User user,
                        ThreadResultFilter resultFilter)

Returns the total number of messages a user has posted in all containers that obey the parameters set by the specificed ResultFilter. Warning: containers that the current user doesn't have read access for will also be included in the total, so you should use caution if that information should be private.

In order to get a count of user messages in an individual container, use the getMessageCount(JiveContainer , ThreadResultFilter) method.

Parameters:

user - the user to tally results for.

resultFilter - a resultFilter to limit the query on.

Returns:

the number of messages the user has posted.

getUserMessages

JiveIterator<ForumMessage> getUserMessages(User user)

Returns an iterable for all messages posted by a user. Only messages that the caller of this method has permission to read will be returned. Therefore, it's possible that the number of messages returned in this iterable will be less than the number returned by userMessageCount(user).

Parameters:

user - the user to get messages for.

Returns:

an iterable for all messages posted by a user

getUserMessages

JiveIterator<ForumMessage> getUserMessages(User user,
                                           ThreadResultFilter resultFilter)

Returns an iterable for all messages posted by a user that obey the parameters set by the specified ResultFilter. Only messages that the caller of this method has permission to read will be returned. Therefore, it's possible that the number of messages returned in this iterable will be less than the number returned by userMessageCount(user).

Parameters:

user - the user to get messages for.

resultFilter - a resultFilter to limit the query on.

Returns:

an Iterable for all messages posted by a user in the specified range.

isModerationEnabled

boolean isModerationEnabled()

Returns true if moderation has been enabled by setting the Jive property "database.moderationEnabled" to true. When true, moderation is enabled at the database query level. This is useful for sites that don't use message/thread approval moderation and that have extreme amounts of traffic such that the moderation check in database queries causes significant slowdowns. Unless your community have over 500K page views per day, you can probably ignore this setting.

Returns:

true if moderation should be enabled at the database query level.

getThreadCount

int getThreadCount(JiveContainer container)

Returns the number of threads in the container. Note: this method ignores permissions because it's not possible to do a database query for the count that obeys permissions counts. Therefore, the count returned by this method may not be the same as the number of threads returned by the getThreads(JiveContainer) method.

Parameters:

container - the container

Returns:

the number of threads in the container.

getThreadCount

int getThreadCount(TagSet tagSet)

Returns the number of threads in the tag set. Note: this method ignores permissions because it's not possible to do a database query for the count that obeys permissions counts. Therefore, the count returned by this method may not be the same as the number of threads returned by the getThreads(TagSet) method.

Parameters:

tagSet - the tag set

Returns:

the number of threads in the tag set.

getThreadCount

int getThreadCount(JiveContainer container,
                   ThreadResultFilter resultFilter)

Returns the number of threads in the container based on the specified ResultFilter. This is useful for determining such things as the number of threads in a date range, etc. Note: this method ignores permissions because it's not possible to do a database query for the count that obeys permissions counts. Therefore, the count returned by this method may not be the same as the number of threads returned by the getThreads(JiveContainer , com.jivesoftware.community.ThreadResultFilter) method.

Parameters:

container - the container

resultFilter - a resultFilter to limit the query on.

Returns:

the number of threads in the container based on the filter.

getThreadCount

int getThreadCount(TagSet tagSet,
                   ThreadResultFilter resultFilter)

Returns the number of threads in the tag set based on the specified ResultFilter. This is useful for determining such things as the number of threads in a date range, etc. Note: this method ignores permissions because it's not possible to do a database query for the count that obeys permissions counts. Therefore, the count returned by this method may not be the same as the number of threads returned by the getThreads(JiveContainer , com.jivesoftware.community.ThreadResultFilter) method.

Parameters:

tagSet - the tag set

resultFilter - a resultFilter to limit the query on.

Returns:

the number of threads in the tag set based on the filter.

getThreads

JiveIterator<ForumThread> getThreads(JiveContainer container)

Returns an Iterable for all the threads in the container. Threads will be sorted on their modified date.

Parameters:

container - the container

Returns:

an Iterable for the threads in the container.

getThreads

JiveIterator<ForumThread> getThreads(TagSet tagSet)

Returns an Iterable for all the threads in the tag set. Threads will be sorted on their modified date.

Parameters:

tagSet - the tag set

Returns:

an Iterable for the threads in the tag set.

getThreads

JiveIterator<ForumThread> getThreads(JiveContainer container,
                                     ThreadResultFilter resultFilter)

Returns an Iterable for all the threads in the container that match the criteria specified by the ResultFilter.

Parameters:

container - the container

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

Returns:

an Iterable for the threads in the container that match the ResultFilter.

getThreads

JiveIterator<ForumThread> getThreads(TagSet tagSet,
                                     ThreadResultFilter resultFilter)

Returns an Iterable for all the threads in the tag set that match the criteria specified by the ResultFilter.

Parameters:

tagSet - the tag set

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

Returns:

an Iterable for the threads in the tag set that match the ResultFilter.

createThread

ForumThread createThread(JiveContainer container,
                         ForumMessage rootMessage)

Factory method to create a new thread. A root message must be supplied when creating the thread. The root message can either be a new message (normal case), or an existing message in a thread. When a new message is being used, the following pattern should be applied to add a new thread to a container:

• Create a new message, and set each of its fields such as the subject and body.
• Create a new thread using the root message just created.
• Set any properties on the new thread.
• Add the thread to the container by calling the addThread method.

When an existing message is passed to this method, the effect will be to create a new thread with the existing message and all of its children (the messages will be removed from the old thread). This is useful if an off-topic conversation begins in a thread which should be branched into a new thread.

Note: creating the ForumThread object is only one step of the process. You must also add the thread to the container with the addThread method before it is saved to the database. It is illegal to create a thread in one container and then add it to another container.

Parameters:

container - The container to create a thread in.

rootMessage - the root message of the thread.

Returns:

a new ForumThread object.

Throws:

UnauthorizedException - if does not have CREATE_THREAD permissions.

addThread

void addThread(JiveContainer container,
               ForumThread thread)
               throws RejectedException

Adds a new thread to the container.

Adding an existing thread to a container is illegal. Instead, the moveForum method should be used.

Parameters:

container - The container to add a thread too.

thread - the thread to add to the container.

Throws:

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

UnauthorizedException - if does not have CREATE_THREAD permissions.

getMessageCount

int getMessageCount(JiveContainer container)

Acquire the count of all messages for a specified container.

Parameters:

container - The container to acquire the count for.

Returns:

The count of messages.

getMessageCount

int getMessageCount(TagSet tagSet)

Acquire the count of all messages for a specified tag set.

Parameters:

tagSet - the tag set

Returns:

The count of messages.

getMessageCount

int getMessageCount(JiveContainer container,
                    ThreadResultFilter resultFilter)

The account of messages for the JiveContainer with the ThreadResultFilter applied.

Parameters:

container - The container to acquire the count for.

resultFilter - The filter to apply to the resutls

Returns:

The message count.

getMessageCount

int getMessageCount(TagSet tagSet,
                    ThreadResultFilter resultFilter)

The account of messages for the TagSet with the ThreadResultFilter applied.

Parameters:

tagSet - the tag set

resultFilter - The filter to apply to the resutls

Returns:

The message count.

getMessages

JiveIterator<ForumMessage> getMessages(JiveContainer container)

Returns an Iterable for all the messages in the container. Threads will be sorted on their modified date.

Parameters:

container - The container

Returns:

an Iterable for the threads in the container.

getMessages

JiveIterator<ForumMessage> getMessages(TagSet tagSet)

Returns an Iterable for all the messages in the tag set. Threads will be sorted on their modified date.

Parameters:

tagSet - the tag set

Returns:

an Iterable for the threads in the tag set.

getMessages

JiveIterator<ForumMessage> getMessages(JiveContainer container,
                                       ThreadResultFilter resultFilter)

Returns an Iterable for all the messages in the container that match the criteria specified by the ResultFilter.

Parameters:

container - the container

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

Returns:

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

getMessages

JiveIterator<ForumMessage> getMessages(TagSet tagSet,
                                       ThreadResultFilter resultFilter)

Returns an Iterable for all the messages in the tag set that match the criteria specified by the ResultFilter.

Parameters:

tagSet - the tag set

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

Returns:

an Iterable for the messages in the tag set that match the ResultFilter.

getLatestMessage

ForumMessage getLatestMessage(JiveContainer container)

Returns the most recently created or edited message in this container (including all sub-containers if applicable). If there are no messages in this container, this method will return null. This information could also be determined using a ThreadResultFilter, but this method offers a simpler, more optimized way to access the data.

Parameters:

container - The container to acquire the last message from.

Returns:

the most recently created or edited message in this container.

getLatestMessage

ForumMessage getLatestMessage(TagSet tagSet)

Returns the most recently created or edited message in this tag set . If there are no messages in this tag set, this method will return null. This information could also be determined using a ThreadResultFilter, but this method offers a simpler, more optimized way to access the data.

Parameters:

tagSet - the tag set

Returns:

the most recently created or edited message in this tag set.

createMessage

ForumMessage createMessage(JiveContainer container)

Factory method to create a message with an anonymous author. After the message is created, all fields should be set, and then the message can be used to create a new thread or can be added to an existing thread.

Note: creating the ForumMessage object is only one step of the process. You must also add the message to a thread before it is saved to the database. It is illegal to create a message in one container and then add it to a thread in another container.

Parameters:

container - The container to create the message in

Returns:

a new ForumMessage object.

createMessage

ForumMessage createMessage(JiveContainer container,
                           User user)

Factory method to create a message as the specified user. After the message is created, all fields should be set, and then the message can be used to create a new thread or can be added to an existing thread.

Note: creating the ForumMessage object is only one step of the process. You must also add the message to a thread before it is saved to the database. It is illegal to create a message in one container and then add it to a thread in another container.

Parameters:

container - The container to create the message in

user - the author of the message.

Returns:

a new ForumMessage object.

Throws:

UnauthorizedException - if does not have permission to post as the specified user.

update

void update(ForumMessage message)

Persists message changes, and broadcasts changes across the cluster. When any field that bears the RequiresUpdate annotation change this method should be called to save the changes.

Parameters:

message - The message.

update

void update(ForumThread thread)

Persists thread changes, and broadcasts changes across the cluster. When any field that bears the RequiresUpdate annotation change this method should be called to save the changes.

Parameters:

thread - The thread.

addMessage

void addMessage(ForumThread thread,
                ForumMessage parentMessage,
                ForumMessage newMessage)
                throws RejectedException

Adds a new message to a given 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:

thread - the thread recieving the new message.

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.

deleteMessage

void deleteMessage(ForumThread thread,
                   ForumMessage message,
                   boolean deleteChildren)

Deletes a message and (optionally) all of its child messages from the given thread. Once a message is deleted, the message object should no longer be used. The search index and other resources that referenced the message and its child messages will also be updated appropriately.

Parameters:

thread - the thread having message(s) delete from it.

message - the message to delete.

deleteChildren - true to delete given message's child messages.

Throws:

UnauthorizedException - if not an admin or moderator of the message's container

deleteUserMessages

void deleteUserMessages(User user)
                        throws UnauthorizedException

Deletes all messages authored by a given user. The search index and other resources that referenced the message and its child messages will also be updated appropriately.

Parameters:

user - the author of the messages being deleted.

Throws:

UnauthorizedException - if not an admin or moderator of the message's container

deleteMessage

void deleteMessage(ForumThread thread,
                   ForumMessage message)

Deletes a message from the given thread. Once a message is deleted, the message object should no longer be used. The search index and other resources that referenced the message will also be updated appropriately.

Child message of the deleted message are not deleted.

Parameters:

thread - the thread having message(s) delete from it.

message - the message to delete.

Throws:

UnauthorizedException - if not an admin or moderator of the message's container

moveMessage

void moveMessage(ForumMessage message,
                 ForumThread newThread,
                 long parentMessageID)

Moves a message to another thread. For this to work, the user calling this method must have admin or moderator permissions for the container the thread currently belongs to.

The main purpose of this method is to allow admins to move non-topical messages into a more appropriate thread.

Parameters:

message - the message being moved

newThread - the thread recieving the message

parentMessageID - the messageID of the moving message's new parent message within the new thread

Throws:

UnauthorizedException - if does not have admin or moderator permissions for the thread's current container.