Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface Forum

All Known Implementing Classes:
DbForum, ForumProxy

public interface Forum

A container for a list of threads. Each forum belongs to a single category. A forum offers the finest granularity of permissions in the system.

A forum corresponds to an NNTP newsgroup when the NNTP server feature is enabled. Therefore, each forum has a unique NNTP name.


Method Summary
 void addThread(ForumThread thread)
          Adds a new thread to the forum.
 ForumMessage createMessage()
          Factory method to create a message with an anonymous author.
 ForumMessage createMessage(User user)
          Factory method to create a message as the specified user.
 Query createQuery()
          Creates a query object to search the forum.
 ForumThread createThread(ForumMessage rootMessage)
          Factory method to create a new thread.
 void deleteProperty(java.lang.String name)
          Deletes an extended property.
 void deleteThread(ForumThread thread)
          Deletes a thread and all of its messages.
 java.util.Date getCreationDate()
          Returns the Date that the forum was created.
 java.lang.String getDescription()
          Returns the description of the forum.
 java.util.Locale getFinalLocale()
          Returns the locale for this forum.
 ForumCategory getForumCategory()
          Returns the forum category that this forum belongs to.
 long getID()
          Returns the unique id of the forum.
 InterceptorManager getInterceptorManager()
          Returns an interceptor manager that can be used to manage the interceptors for this forum.
 ForumMessage getLatestMessage()
          Returns the most recently created or edited message in this forum.
 java.util.Locale getLocale()
          Returns the locale for this forum.
 int getMaxForumIndex()
          Returns the largest forum index value for a message in the forum.
 int getMessageCount()
          Returns the number of messages in the forum.
 int getMessageCount(ResultFilter resultFilter)
          Returns the number of messages in the forum based on the specified ResultFilter.
 ForumMessageIterator getMessages()
          Returns an Iterator for all the messages in the forum.
 ForumMessageIterator getMessages(ResultFilter resultFilter)
          Returns a Iterator for all the messages in the forum that match the criteria specified by the ResultFilter.
 int getMinForumIndex()
          Returns the smallest forum index value for a message in the forum.
 int getModerationDefaultMessageValue()
          Returns the default number of moderation points for messages created in the forum.
 int getModerationDefaultThreadValue()
          Returns the default number of moderation points for threads created in the forum.
 java.util.Date getModificationDate()
          Returns the Date that the forum was last modified.
 java.lang.String getName()
          Returns the name of the forum.
 java.lang.String getNNTPName()
          Returns the NNTP name for the forum, which is the name of the forum used in the NNTP protocol (newsgroups).
 Permissions getPermissions(AuthToken authToken)
          Returns the permissions for the forum that correspond to the passed-in AuthToken.
 PermissionsManager getPermissionsManager()
          Returns a permissions manager that can be used to set permissions for this forum.
 java.util.Iterator getPopularThreads()
          Returns an Iterator for the most popular threads in the forum.
 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 the forum.
 java.util.Iterator getPropertyNames()
          Returns an Iterator for the names of the forum properties.
 ForumRenderManager getRenderManager()
          Returns a render manager that can be used to manage render filters and macros for this forum.
 java.util.Map getTags()
          Returns all tags for a given forum in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum.
 java.util.Map getTags(TagResultFilter resultFilter)
          Returns all tags for a given forum in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum filtered by the TagResultFilter.
 ForumThread getThread(long threadID)
          Returns the thread specified by id.
 int getThreadCount()
          Returns the number of threads in the forum.
 int getThreadCount(ResultFilter resultFilter)
          Returns the number of threads in the forum based on the specified ResultFilter.
 ForumThreadIterator getThreads()
          Returns a Iterator for all the threads in the forum.
 ForumThreadIterator getThreads(ResultFilter resultFilter)
          Returns a Iterator for all the threads in the forum that match the criteria specified by the ResultFilter.
 boolean isAuthorized(long permissionType)
          Returns true if the handle on the object has the permission specified.
 void moveThread(ForumThread thread, Forum newForum)
          Moves a thread from one forum to another.
 void setCreationDate(java.util.Date creationDate)
          Sets the creation date of the forum.
 void setDescription(java.lang.String description)
          Sets the description of the forum.
 void setLocale(java.util.Locale locale)
          Sets the locale for this forum.
 void setModerationDefaultMessageValue(int value)
          Sets the default number of moderation points for threads created in the forum.
 void setModerationDefaultThreadValue(int value)
          Sets the default number of moderation points for threads created in the forum.
 void setModificationDate(java.util.Date modificationDate)
          Sets the date the forum was last modified.
 void setName(java.lang.String name)
          Sets the name of a the forum.
 void setNNTPName(java.lang.String nntpName)
          Sets the NNTP name for the forum, which is the name of the forum used in the NNTP protocol (newsgroups).
 void setProperty(java.lang.String name, java.lang.String value)
          Sets an extended property of the forum.
 

Method Detail

getID

long getID()
Returns the unique id of the forum.

Returns:
the unique id of the forum.

getName

java.lang.String getName()
Returns the name of the forum.

Returns:
the name of the forum.

setName

void setName(java.lang.String name)
             throws UnauthorizedException
Sets the name of a the forum.

Parameters:
name - the name of the forum.
Throws:
UnauthorizedException - if does not have admin permissions.

getNNTPName

java.lang.String getNNTPName()
Returns the NNTP name for the forum, which is the name of the forum used in the NNTP protocol (newsgroups). NNTP names must be unique in the system and typically contain category information in the name. For example, consider the forum named "Support" in the category "Product X". The NNTP name for the forum might be "product_x.support". However, this naming scheme is merely by convention; the NNTP name for a forum can be anything as long as it is unique in the system and conforms to NNTP naming conventions.

NNTP names must follow certain rules. In particular:

Returns:
the NNTP name of the forum.

setNNTPName

void setNNTPName(java.lang.String nntpName)
                 throws UnauthorizedException,
                        NameAlreadyExistsException
Sets the NNTP name for the forum, which is the name of the forum used in the NNTP protocol (newsgroups). NNTP names must be unique in the system and typically contain category information in the name. For example, consider the forum named "Support" in the category "Product X". The NNTP name for the forum might be "product_x.support". However, this naming scheme is merely by convention; the NNTP name for a forum can be anything as long as it is unique in the system and conforms to NNTP naming conventions.

NNTP names must follow certain rules. Therefore, any name passed into this method will automatically converted based on the following rules:

Parameters:
nntpName - the NNTP name of the forum.
Throws:
UnauthorizedException - if does not have admin permissions.
NameAlreadyExistsException - if attempting to use an existing NNTP name.

getDescription

java.lang.String getDescription()
Returns the description of the forum. A description should normally be no longer than thirty words so that it can be easily displayed in a list of forums on a web page.

Returns:
the description of the forum.

setDescription

void setDescription(java.lang.String description)
                    throws UnauthorizedException
Sets the description of the forum. A description should normally be no longer than thirty words so that it can be easily displayed in a list of forums on a web page.

Parameters:
description - the description of the forum.
Throws:
UnauthorizedException - if does not have ADMIN permissions.

getCreationDate

java.util.Date getCreationDate()
Returns the Date that the forum was created.

Returns:
the Date the forum was created.

setCreationDate

void setCreationDate(java.util.Date creationDate)
                     throws UnauthorizedException
Sets the creation date of the forum. In most cases, the creation date will default to when the forum 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 the forum was created.
Throws:
UnauthorizedException - if does not have ADMIN permissions.

getModificationDate

java.util.Date getModificationDate()
Returns the Date that the forum was last modified. In other words, the date of the most recent message or thread in the forum.

Returns:
the Date the forum was last modified.

setModificationDate

void setModificationDate(java.util.Date modificationDate)
                         throws UnauthorizedException
Sets the date the forum was last modified. In most cases, last modifed will default to when the forum 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 the forum was modified.
Throws:
UnauthorizedException - if does not have ADMIN permissions.

getModerationDefaultThreadValue

int getModerationDefaultThreadValue()
Returns the default number of moderation points for threads created in the forum. This value is used to turn moderation on or off. A default value of 0 is used to turn moderation on, and a default value of 1 is used to turn it off.

Returns:
the default number of moderation points assigned to threads.

setModerationDefaultThreadValue

void setModerationDefaultThreadValue(int value)
                                     throws UnauthorizedException
Sets the default number of moderation points for threads created in the forum. This value is used to turn moderation on or off. A default value of 0 is used to turn moderation on, and a default value of 1 is used to turn it off.

Parameters:
value - default number of moderation points for threads.
Throws:
UnauthorizedException - if does not have permission.

getModerationDefaultMessageValue

int getModerationDefaultMessageValue()
Returns the default number of moderation points for messages created in the forum. This value is used to turn moderation on or off. A default value of 0 is used to turn moderation on, and a default value of 1 is used to turn it off.

Returns:
the default number of moderation points assigned to messages.

setModerationDefaultMessageValue

void setModerationDefaultMessageValue(int value)
                                      throws UnauthorizedException
Sets the default number of moderation points for threads created in the forum. This value is used to turn moderation on or off. A default value of 0 is used to turn moderation on, and a default value of 1 is used to turn it off.

Parameters:
value - default number of moderation points for messages.
Throws:
UnauthorizedException - if does not have permission.

getMinForumIndex

int getMinForumIndex()
Returns the smallest forum index value for a message in the forum. The forum index is used to track when messages enter the forum. Each forum index is assigned to a message once and then never re-used. So, there may be gaps in forum index values as messages are deleted, archived, or moved. Still, a rough estimate of the number of messages in the system is max(forumIndex) - min(forumIndex) + 1;

Returns:
the smallest forum index in the forum.

getMaxForumIndex

int getMaxForumIndex()
Returns the largest forum index value for a message in the forum. The forum index is used to track when messages enter the forum. Each forum index is assigned to a message once and then never re-used. So, there may be gaps in forum index values as messages are deleted, archived, or moved. Still, a rough estimate of the number of messages in the system is max(forumIndex) - min(forumIndex) + 1;

Returns:
the largest forum index in the forum.

getLocale

java.util.Locale getLocale()
Returns the locale for this forum. A locale specifies language and country codes, and is used for internationalization. If a locale has not been specified for this forum, this method will return null. If you want to get the inherited locale for this forum, you should call getFinalLocale().

Returns:
the locale for this forum.

setLocale

void setLocale(java.util.Locale locale)
               throws UnauthorizedException
Sets the locale for this forum. A locale specifies language and country codes, and is used for internationalization.

Parameters:
locale - the locale of this forum.
Throws:
UnauthorizedException - if does not have admin permissions.

getFinalLocale

java.util.Locale getFinalLocale()
Returns the locale for this forum. A locale specifies language and country codes, and is used for internationalization. If a locale has not been specified for this forum, this method will return an inherited locale. A forum will inherit the locale from it's chain of parent categories, if one exists. Otherwise it will inherit the default locale used by Jive. If you want to get the explicit locale for this forum, you should call getLocale().

Returns:
the final locale for this forum.

getProperty

java.lang.String getProperty(java.lang.String name)
Returns an extended property of the forum. Each forum 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 the forum. Each forum can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface.

If the property referenced by name already exists, its value will be updated.

Parameters:
name - the name of the property to set.
value - the new value for the property.
Throws:
UnauthorizedException - if does not have ADMIN permissions.

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 does not have ADMIN permissions.

getPropertyNames

java.util.Iterator getPropertyNames()
Returns an Iterator for the names of the forum properties.

Returns:
an Iterator for the names of the forum properties.

getForumCategory

ForumCategory getForumCategory()
Returns the forum category that this forum belongs to.

Returns:
the forum category that this forum belongs to.

getThread

ForumThread getThread(long threadID)
                      throws ForumThreadNotFoundException
Returns the thread specified by id. This method will return null if the thread is not in the forum.

Parameters:
threadID - the id of the thread to get.
Returns:
the ForumThread corresponding to threadID
Throws:
ForumThreadNotFoundException - if the specified thread cannot be loaded.

createThread

ForumThread createThread(ForumMessage rootMessage)
                         throws UnauthorizedException
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 forum: 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 forum with the addThread(ForumThread) method before it is saved to the database. It is illegal to create a thread in one forum and then add it to another forum.

Parameters:
rootMessage - the root message of the thread.
Returns:
a new ForumThread object.
Throws:
UnauthorizedException - if does not have CREATE_THREAD permissions.

createMessage

ForumMessage createMessage()
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 forum and then add it to a thread in another forum.

Returns:
a new ForumMessage object.

createMessage

ForumMessage createMessage(User user)
                           throws UnauthorizedException
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 forum and then add it to a thread in another forum.

Parameters:
user - the author of the message.
Returns:
the new ForumMessage
Throws:
UnauthorizedException - if does not have permission to post as the specified user.

addThread

void addThread(ForumThread thread)
               throws MessageRejectedException,
                      UnauthorizedException
Adds a new thread to the forum.

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

Parameters:
thread - the thread to add to the forum.
Throws:
MessageRejectedException - if one of the installed interceptors prevents the root message from being posted.
UnauthorizedException - if does not have CREATE_THREAD permissions.

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.

moveThread

void moveThread(ForumThread thread,
                Forum newForum)
                throws UnauthorizedException,
                       java.lang.IllegalArgumentException
Moves a thread from one forum to another. For this to work, the thread must exist in the forum that this method is invoked on, and the user calling this method must have admin or moderator permissions for the forum this method is invoked on and newForum.

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

Parameters:
thread - the thread to move to another forum.
newForum - the forum to move the thread to.
Throws:
UnauthorizedException - if does not have admin or moderator permissions for this forum and newForum.
java.lang.IllegalArgumentException - if thread does not belong to the forum that this method was invoked on.

getThreads

ForumThreadIterator getThreads()
Returns a Iterator for all the threads in the forum. Threads will be sorted on their modified date.

Returns:
an Iterator for the threads in the forum.

getThreads

ForumThreadIterator getThreads(ResultFilter resultFilter)
Returns a Iterator for all the threads in the forum that match the criteria specified by the ResultFilter.

Parameters:
resultFilter - a ResultFilter object to perform filtering and sorting with.
Returns:
an Iterator for the threads in the forum that match the ResultFilter.

getPopularThreads

java.util.Iterator getPopularThreads()
Returns an Iterator for the most popular threads in the forum. Popular threads are defined as those that have the most new messages over a period of time (e.g. the last 24 hours). When two threads have identical numbers of new messages, newer threads will be ordered first.

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

Returns:
an Iterator for the most popular threads in the forum.

getMessages

ForumMessageIterator getMessages()
Returns an Iterator for all the messages in the forum.

Returns:
an Iterator for the messages in the forum.

getMessages

ForumMessageIterator getMessages(ResultFilter resultFilter)
Returns a Iterator for all the messages in the forum 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 forum that match the ResultFilter.

getThreadCount

int getThreadCount()
Returns the number of threads in the forum.

Returns:
the number of threads in the forum.

getThreadCount

int getThreadCount(ResultFilter resultFilter)
Returns the number of threads in the forum based on the specified ResultFilter. This is useful for determining such things as the number of threads in a date range, etc.

Parameters:
resultFilter - a resultFilter to limit the query on.
Returns:
the number of threads in the forum based on the filter.

getMessageCount

int getMessageCount()
Returns the number of messages in the forum.

Returns:
the number of messages in the forum.

getMessageCount

int getMessageCount(ResultFilter resultFilter)
Returns the number of messages in the forum based on the specified ResultFilter. This is useful for determining such things as the number of messages in a date range, etc.

Parameters:
resultFilter - a resultFilter to limit the query on.
Returns:
the number of messages in the forum based on the filter.

getLatestMessage

ForumMessage getLatestMessage()
Returns the most recently created or edited message in this forum. If there are no messages in this forum, this method will return null. 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 or edited message in this forum.

createQuery

Query createQuery()
Creates a query object to search the forum.

Returns:
a Query object that can be used to search the forum.

getInterceptorManager

InterceptorManager getInterceptorManager()
                                         throws UnauthorizedException
Returns an interceptor manager that can be used to manage the interceptors for this forum.

Returns:
an InterceptorManager to manage interceptors for this forum.
Throws:
UnauthorizedException - if not an administrator.

getPermissionsManager

PermissionsManager getPermissionsManager()
                                         throws UnauthorizedException
Returns a permissions manager that can be used to set permissions for this forum. Only admins can perform this function.

Returns:
a PermissionsManager to manage the permissions on this forum.
Throws:
UnauthorizedException - is not an admin.

getRenderManager

ForumRenderManager getRenderManager()
Returns a render manager that can be used to manage render filters and macros for this forum. Render filter management is only for administrators, excluding the RenderManager.render(Object, com.jivesoftware.forum.renderer.RenderType, String) and RenderManager.render(Object, com.jivesoftware.forum.renderer.RenderType, com.jivesoftware.forum.renderer.RenderStrategy, String) methods, which may be useful to skin writers.

Returns:
a RenderManager to manage render filters and macros for this forum.
See Also:
RenderManager

getPermissions

Permissions getPermissions(AuthToken authToken)
Returns the permissions for the forum that correspond to the passed-in AuthToken. This method is not generally useful to skin writers. Instead, the isAuthorized(int) method should be used for permission checking.

Parameters:
authToken - the auth token to lookup permissions for.
Returns:
the permssions for the forum corresponding to the passed in AuthToken

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

getTags

java.util.Map getTags()
Returns all tags for a given forum in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum.

Returns:
all tags for a given forum in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum.

getTags

java.util.Map getTags(TagResultFilter resultFilter)
Returns all tags for a given forum in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum filtered by the TagResultFilter.

Parameters:
resultFilter - the filter to use to restrict tag results
Returns:
all tags for a given community in a Map where the key is the name of tag and the value is the number of times the tag has been used in this forum filtered by the TagResultFilter.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.