Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface ForumCategory

All Superinterfaces:
ContentRetrieval, JiveObject
All Known Implementing Classes:
DbForumCategory, ForumCategoryProxy

public interface ForumCategory
extends JiveObject, ContentRetrieval

A container for forums and a hierarchy of other forum categories. In other words, the category structure is a tree, with lists of forums for every category node. There is always a "root" forum category (ID of 1), of which all other categories are children. Category names are not unique, therefore it is not possible to load a category by name.

See Also:
ForumFactory.getRootForumCategory(), ForumFactory.getForumCategory(long)

Field Summary
 
Fields inherited from interface com.jivesoftware.forum.ContentRetrieval
ALL_TYPES, THREAD
 
Method Summary
 ForumCategory createCategory(java.lang.String name, java.lang.String description)
          Creates a new ForumCategory as a sub-category of this category using the name and description.
 void deleteCategory(ForumCategory subCategory)
          Deletes a sub-category.
 void deleteForum(Forum forum)
          Deletes a forum and all of its content.
 void deleteProperty(java.lang.String name)
          Deletes an extended property.
 java.util.Iterator getCategories()
          Returns an Iterator for the child categories of this category.
 java.util.Iterator getCategories(int startIndex, int numResults)
          Returns an Iterator for the child categories of this category using a start index and the number of results to return.
 int getCategoryCount()
          Returns the number of sub-categories of this category.
 int getCategoryDepth()
          Returns the depth of a this category relative to the root.
 java.util.Date getCreationDate()
          Returns the Date that the category was created.
 java.lang.String getDescription()
          Returns the description of the forum category.
 java.util.Locale getFinalLocale()
          Returns the locale for this category.
 int getForumCount()
          Returns the number of forums in the category.
 int getForumCount(ResultFilter resultFilter)
          Returns the number of forums in the category based on the specified ResultFilter.
 java.util.Iterator getForums()
          Returns an Iterator for all the forums in the category.
 java.util.Iterator getForums(ResultFilter resultFilter)
          Returns a Iterator for all the forums in the category that match the criteria specified by the ResultFilter.
 long getID()
          Returns the ID of the category.
 InterceptorManager getInterceptorManager()
          Returns a message interceptor manager that can be used to manage interceptors for this category.
 ForumMessage getLatestMessage()
          Returns the most recently created or edited message in this category (including all sub-categories).
 java.util.Iterator getLatestMessages()
          Returns an Iterator for the most recently created or edited messages in this category (including all sub-categories).
 java.util.Locale getLocale()
          Returns the locale for this category.
 int getMessageCount()
          Returns the number of messages in the category.
 int getMessageCount(ResultFilter resultFilter)
          Returns the number of messages in the category based on the specified ResultFilter.
 java.util.Iterator getMessages()
          Returns an Iterator for all the messages in the category.
 java.util.Iterator getMessages(ResultFilter resultFilter)
          Returns a Iterator for all the messages in the category that match the criteria specified by the ResultFilter.
 java.util.Date getModificationDate()
          Returns the Date this category was last modified.
 java.lang.String getName()
          Returns the name of the category.
 ForumCategory getParentCategory()
          Returns the parent category of this category.
 Permissions getPermissions(AuthToken authToken)
          Returns the permissions for the category that correspond to the passed-in AuthToken.
 PermissionsManager getPermissionsManager()
          Returns a permissions manager that can be used to set permissions for this category.
 java.util.Iterator getPopularThreads()
          Returns an Iterator for the most popular threads in the category.
 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 category.
 java.util.Iterator getPropertyNames()
          Returns an Iterator for the names of the forum category properties.
 java.util.Iterator getRecursiveCategories()
          Returns an Iterator for all sub-categories of this category, including sub-categories of sub-categories, etc.
 int getRecursiveCategoryCount()
          Returns the total count of all sub-categories of this category, including sub-categories of sub-categories, etc.
 int getRecursiveForumCount()
          Returns the number of forums in the category and all sub-categories.
 int getRecursiveForumCount(ResultFilter resultFilter)
          Returns the number of forums in the category and all sub-categories based on the specified ResultFilter.
 java.util.Iterator getRecursiveForums()
          Returns an Iterator for all the forums in the category and all sub-categories.
 java.util.Iterator getRecursiveForums(ResultFilter resultFilter)
          Returns a Iterator for all the forums in the category and sub-categories that match the criteria specified by the ResultFilter.
 ForumRenderManager getRenderManager()
          Returns a render manager that can be used to manage render filters and macros for this category.
 java.util.Map getTags()
          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 community.
 java.util.Map getTags(TagResultFilter resultFilter)
          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 community filtered by the TagResultFilter.
 int getThreadCount()
          Returns the number of threads in the category.
 int getThreadCount(ResultFilter resultFilter)
          Returns the number of threads in the category based on the specified ResultFilter.
 java.util.Iterator getThreads()
          Returns a Iterator for all the threads in the category.
 java.util.Iterator getThreads(ResultFilter resultFilter)
          Returns a Iterator for all the threads in the category 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 moveCategory(ForumCategory subCategory, ForumCategory destinationCategory)
          Moves a sub-category to another category.
 void moveForum(Forum forum, ForumCategory destinationCategory)
          Moves a forum from this category to another.
 void setCategoryIndex(ForumCategory subCategory, int newIndex)
          Sets the display order of a sub-category.
 void setCreationDate(java.util.Date creationDate)
          Sets the creation date of the category.
 void setDescription(java.lang.String description)
          Sets the description of the forum category.
 void setForumIndex(Forum forum, int newIndex)
          Sets the index of the forum in the category.
 void setLocale(java.util.Locale locale)
          Sets the locale for this category.
 void setModificationDate(java.util.Date modificationDate)
          Sets the date the category was last modified.
 void setName(java.lang.String name)
          Sets the name of the forum category.
 void setProperty(java.lang.String name, java.lang.String value)
          Sets an extended property of the category.
 
Methods inherited from interface com.jivesoftware.base.JiveObject
getObjectType
 
Methods inherited from interface com.jivesoftware.forum.ContentRetrieval
getCombinedContent, getCombinedContent, getCombinedContentCount, getCombinedContentCount
 

Method Detail

getID

long getID()
Returns the ID of the category.

Specified by:
getID in interface JiveObject
Returns:
the ID of the category.

getName

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

Returns:
the name of the category.

setName

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

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

getDescription

java.lang.String getDescription()
Returns the description of the forum category.

Returns:
the description of the forum category.

setDescription

void setDescription(java.lang.String description)
                    throws UnauthorizedException
Sets the description of the forum category.

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

getCreationDate

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

Returns:
the Date the forum category was created.

setCreationDate

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

getModificationDate

java.util.Date getModificationDate()
Returns the Date this category was last modified. In other words, the date of the most recent forum update in this category.

By default, this feature is

Returns:
the Date the forum was last modified.

setModificationDate

void setModificationDate(java.util.Date modificationDate)
                         throws UnauthorizedException
Sets the date the category was last modified. In most cases, last modifed will default to when the category 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.

getLocale

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

Returns:
the locale for this category.

setLocale

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

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

getFinalLocale

java.util.Locale getFinalLocale()
Returns the locale for this category. A locale specifies language and country codes, and is used for internationalization. If a locale has not been specified for this category, this method will return an inherited locale. A category 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 category, you should call getLocale().

Returns:
the final locale for this category.

getProperty

java.lang.String getProperty(java.lang.String name)
Returns an extended property of the category. Each category 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 category. Each category 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 category properties.

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

getForumCount

int getForumCount()
Returns the number of forums in the category. This number might not agree with the number of forums returned by getForums() since that method only returns forums that a user has read permission for.

Returns:
the number of forums in the category.

getForumCount

int getForumCount(ResultFilter resultFilter)
Returns the number of forums in the category based on the specified ResultFilter. This is useful for determining such things as the number of forums in a date range, etc. This number might not agree with the number of forums returned by getForums() since that method only returns forums that a user has read permission for.

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

getRecursiveForumCount

int getRecursiveForumCount()
Returns the number of forums in the category and all sub-categories. This number might not agree with the number of forums returned by getRecursiveForums() since that method only returns forums that a user has read permission for.

Returns:
the number of forums in the category and sub-categories.

getRecursiveForumCount

int getRecursiveForumCount(ResultFilter resultFilter)
Returns the number of forums in the category and all sub-categories based on the specified ResultFilter. This is useful for determining such things as the number of forums in a date range, etc. This number might not agree with the number of forums returned by getRecursiveForums() since that method only returns forums that a user has read permission for.

Parameters:
resultFilter - a resultFilter to limit the query on.
Returns:
the number of forums in the category and sub-categories based on the filter.

getForums

java.util.Iterator getForums()
Returns an Iterator for all the forums in the category. Forums will be sorted based on their category index.

Returns:
an Iterator for all the forums in the category.

getForums

java.util.Iterator getForums(ResultFilter resultFilter)
Returns a Iterator for all the forums in the category that match the criteria specified by the ResultFilter.

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

getRecursiveForums

java.util.Iterator getRecursiveForums()
Returns an Iterator for all the forums in the category and all sub-categories. The ordering of forums in unspecified.

Returns:
an Iterator for all the forums in the category and sub-categories.

getRecursiveForums

java.util.Iterator getRecursiveForums(ResultFilter resultFilter)
Returns a Iterator for all the forums in the category and sub-categories that match the criteria specified by the ResultFilter. Note that attempting to sort the forums on their category index will have strange results.

Parameters:
resultFilter - a ResultFilter object to perform filtering and sorting with.
Returns:
an Iterator for the forums in the category and sub-categories that match the ResultFilter.

setForumIndex

void setForumIndex(Forum forum,
                   int newIndex)
                   throws UnauthorizedException
Sets the index of the forum in the category. The index value can be used to display the forums in a category in an arbitrary order. Index values are from 0 to getForumCount() - 1.

Parameters:
forum - the forum to adjust the index of.
newIndex - the new index value for the forum.
Throws:
UnauthorizedException - if not an admin for this category

moveForum

void moveForum(Forum forum,
               ForumCategory destinationCategory)
               throws UnauthorizedException
Moves a forum from this category to another.

Parameters:
forum - the forum to move.
destinationCategory - the category to move the forum to.
Throws:
UnauthorizedException - if not an admin for this category and the destination category.

getPopularThreads

java.util.Iterator getPopularThreads()
Returns an Iterator for the most popular threads in the category. 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 category.

getThreads

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

Specified by:
getThreads in interface ContentRetrieval
Returns:
an Iterator for the threads in the category.

getThreads

java.util.Iterator getThreads(ResultFilter resultFilter)
Returns a Iterator for all the threads in the category that match the criteria specified by the ResultFilter.

Specified by:
getThreads in interface ContentRetrieval
Parameters:
resultFilter - a ResultFilter object to perform filtering and sorting with.
Returns:
an Iterator for the threads in the category that match the ResultFilter.

getThreadCount

int getThreadCount()
Returns the number of threads in the category. 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() method.

Specified by:
getThreadCount in interface ContentRetrieval
Returns:
the number of threads in the category.

getThreadCount

int getThreadCount(ResultFilter resultFilter)
Returns the number of threads in the category 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(ResultFilter) method.

Specified by:
getThreadCount in interface ContentRetrieval
Parameters:
resultFilter - a resultFilter to limit the query on.
Returns:
the number of threads in the category based on the filter.

getMessageCount

int getMessageCount()
Returns the number of messages in the category. 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 messages returned by the getMessages() method.

Specified by:
getMessageCount in interface ContentRetrieval
Returns:
the number of messages in the category.

getMessageCount

int getMessageCount(ResultFilter resultFilter)
Returns the number of messages in the category based on the specified ResultFilter. This is useful for determining such things as the number of messages 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 messages returned by the getMessages(ResultFilter) method.

Specified by:
getMessageCount in interface ContentRetrieval
Parameters:
resultFilter - a resultFilter to limit the query on.
Returns:
the number of messages in the category based on the filter.

getMessages

java.util.Iterator getMessages()
Returns an Iterator for all the messages in the category.

Specified by:
getMessages in interface ContentRetrieval
Returns:
an Iterator for the messages in the category.

getMessages

java.util.Iterator getMessages(ResultFilter resultFilter)
Returns a Iterator for all the messages in the category that match the criteria specified by the ResultFilter.

Specified by:
getMessages in interface ContentRetrieval
Parameters:
resultFilter - a ResultFilter object to perform filtering and sorting with.
Returns:
an Iterator for the messages in the category that match the ResultFilter.

getLatestMessage

ForumMessage getLatestMessage()
Returns the most recently created or edited message in this category (including all sub-categories). If there are no messages in this category, 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 category.

getLatestMessages

java.util.Iterator getLatestMessages()
Returns an Iterator for the most recently created or edited messages in this category (including all sub-categories). If there are no messages in this category, this method will return null.

Returns:
the most recently created or edited messages in this category.

getParentCategory

ForumCategory getParentCategory()
Returns the parent category of this category. This method will return null if the current category is the root category.

Returns:
the parent category of this category.

getCategoryCount

int getCategoryCount()
Returns the number of sub-categories of this category.

Returns:
the number of sub-categories in this category.

getCategories

java.util.Iterator getCategories()
Returns an Iterator for the child categories of this category.

Returns:
the child categories of this category.

getCategories

java.util.Iterator getCategories(int startIndex,
                                 int numResults)
Returns an Iterator for the child categories of this category using a start index and the number of results to return. This method can be used to perform pagination of results. Note: the number of results returned may be less than numResults depending on the data that's actually available to return.

Parameters:
startIndex - the index of the first result to return.
numResults - the max number of results to return.
Returns:
an Iterator for the child categories of this category.

getRecursiveCategoryCount

int getRecursiveCategoryCount()
Returns the total count of all sub-categories of this category, including sub-categories of sub-categories, etc.

Returns:
the recursive sub-category count of this category.

getRecursiveCategories

java.util.Iterator getRecursiveCategories()
Returns an Iterator for all sub-categories of this category, including sub-categories of sub-categories, etc.

Returns:
an Iterator for the recursive sub-categories of this category.

getCategoryDepth

int getCategoryDepth()
Returns the depth of a this category relative to the root. For example, consider the following tree (where 1 is the root category):
   1
   |-- 3
   |-- |-- 4
   |-- |-- |-- 7
 
The depth of message 4 is 2, the depth of category 7 is 3, etc. This method is useful in combination with the getRecursiveCategories() Iterator to build a UI of hierarchical categories.

Returns:
the depth of the category in the category tree.

setCategoryIndex

void setCategoryIndex(ForumCategory subCategory,
                      int newIndex)
                      throws UnauthorizedException
Sets the display order of a sub-category. For example, if a sub-category has an index of 0, then it will returned first in the Iterator resulting from the categories method call.

Parameters:
subCategory - the sub category to set the index for
newIndex - the new index of the sub category
Throws:
UnauthorizedException

moveCategory

void moveCategory(ForumCategory subCategory,
                  ForumCategory destinationCategory)
                  throws UnauthorizedException
Moves a sub-category to another category. You cannot move a category into a child category. For example, take the following category tree:
   1
   |-- 3
   |-- |-- 4
   |-- |-- |-- 7
 
Moving 3 to be a child of 7 is not allowed, since that breaks the tree structure.

Parameters:
subCategory - the ForumCategory to move.
destinationCategory - the category to move the sub-category to.
Throws:
UnauthorizedException - if not an admin of this category and the destination category.

createCategory

ForumCategory createCategory(java.lang.String name,
                             java.lang.String description)
                             throws UnauthorizedException
Creates a new ForumCategory as a sub-category of this category using the name and description.

Parameters:
name - the name of the new category.
description - the description of the new category.
Returns:
a new ForumCategory.
Throws:
UnauthorizedException - if not an admin.

deleteCategory

void deleteCategory(ForumCategory subCategory)
                    throws UnauthorizedException
Deletes a sub-category. Only direct children of this category can be deleted using this method. Attempting to delete a category that is not a direct child will throw an IllegalArgumentException.

Parameters:
subCategory - the ForumCategory to delete.
Throws:
UnauthorizedException - if not an admin.

deleteForum

void deleteForum(Forum forum)
                 throws UnauthorizedException
Deletes a forum and all of its content. The forum must belong to this category or to a sub-category.

This method is not always guaranteed to be safe to call. For example, if multiple clients have handles on a forum, and that forum is subsequently deleted, the behavior of the forum objects that the clients have handles on is unspecified and may result in errors.

Parameters:
forum - the forum to delete.
Throws:
UnauthorizedException - if not allowed to delete a forum.

getPermissionsManager

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

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

getInterceptorManager

InterceptorManager getInterceptorManager()
                                         throws UnauthorizedException
Returns a message interceptor manager that can be used to manage interceptors for this category.

Returns:
a InterceptorManager to manage interceptors.
Throws:
UnauthorizedException - if not an admin

getRenderManager

ForumRenderManager getRenderManager()
Returns a render manager that can be used to manage render filters and macros for this category. 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 category.
See Also:
RenderManager

getPermissions

Permissions getPermissions(AuthToken authToken)
Returns the permissions for the category 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 permissions for the category that correspond 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 category administrator has a handle on this object, then calling isAuthorized(ForumPermissions.FORUM_CATEGORY_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 - 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 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 community.

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 community.

getTags

java.util.Map getTags(TagResultFilter resultFilter)
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 community 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 community filtered by the TagResultFilter.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.