Jive Forums API (5.5.20.2-oracle) Core Javadocs

com.jivesoftware.forum
Class ForumFactory

java.lang.Object
  extended by com.jivesoftware.forum.ForumFactory

public abstract class ForumFactory
extends java.lang.Object

A ForumFactory provides access to and management of Forums. It is the point of entry for the entire Jive system.

A concrete instance of ForumFactory can be obtained by calling the getInstance() method with an AuthToken. The AuthToken determines the access rights the user will have on all other objects in the system.

Usually the first steps of any program interacting with the Jive system are:

It is also possible to access Jive content with anonymous permissions. See the AuthorizationFactory class for more information.

Finer grained pluggability for the user and group system is also available. See the UserManager and GroupManager classes for more information.

See Also:
AuthFactory, UserManager, GroupManager

Constructor Summary
ForumFactory()
           
 
Method Summary
abstract  Forum createForum(java.lang.String name, java.lang.String description)
          Creates a new forum.
abstract  Forum createForum(java.lang.String name, java.lang.String description, ForumCategory category)
          Creates a new forum in the specified category.
abstract  Query createQuery()
          Creates a query object to search through all forums.
abstract  Query createQuery(Forum[] forums)
          Creates a query object to search through the specified list of forums.
abstract  void deleteForum(Forum forum)
          Deprecated. the ForumCategory.deleteForum(Forum) method should now be used instead of this method.
abstract  com.jivesoftware.forum.abuse.AbuseManager getAbuseManager()
          Returns an abuse manager that can be used for managing abuse reports
abstract  AnnouncementManager getAnnouncementManager()
          Returns an announcement manager, which is used to create and retrieve announcements.
abstract  ArchiveManager getArchiveManager()
          Returns an archive manager that can be used to manage archiving for forums.
abstract  AttachmentManager getAttachmentManager()
          Returns an attachment manager that can be used to manage attachment rules.
abstract  AvatarManager getAvatarManager()
          Returns a AvatarManager that can be used to find, create, delete, and make avatars active
abstract  com.jivesoftware.base.ban.BanManager getBanManager()
          Returns a ban manager that can be used for banning users
abstract  com.jivesoftware.forum.DraftManager getDraftManager()
          Returns a DraftManager that can be used to manager message drafts.
abstract  EmailManager getEmailManager()
          Returns an EmailManager that can be used for sending out emails
abstract  Forum getForum(long forumID)
          Returns the forum with the specified forumID.
abstract  Forum getForum(java.lang.String nntpName)
          Returns the forum with the specified NNTP name.
abstract  ForumCategory getForumCategory(long categoryID)
          Returns the forum category with the specified categoryID.
abstract  int getForumCount()
          Returns the total number of forums in the system.
abstract  int getForumCount(ResultFilter resultFilter)
          Returns the total number of forums in the system matching the ResultFilter.
abstract  java.util.Iterator getForums()
          Returns all forums in the system that the user has read permission for.
abstract  java.util.Iterator getForums(ResultFilter resultFilter)
          Returns all forums in the system that the user has read permission for and that matche the specified ResultFilter.
abstract  ForumThread getForumThread(long threadID)
          Returns the thread with the specified threadID.
abstract  com.jivesoftware.forum.gateway.GatewayManager getGatewayManager()
          Returns a gateway manager that can be used for managing gateways
abstract  GroupManager getGroupManager()
          Returns a GroupManager that can be used to manage groups.
static ForumFactory getInstance(AuthToken authToken)
          Returns a concrete ForumFactory instance.
abstract  InterceptorManager getInterceptorManager()
          Returns a message interceptor manager that can be used to manage global interceptors.
abstract  ForumMessage getMessage(long messageID)
          Returns the forum message with the specified messageID.
abstract  long getMessageID(long forumID, int forumIndex)
          Returns the message ID with the specified forumID and forumIndex, or -1 if the forumIndex does not map to a message.
abstract  com.jivesoftware.forum.moderation.ModerationManager getModerationManager()
          Returns a moderation manager that can be used for moderating messages
abstract  Permissions getPermissions(AuthToken authToken)
          Returns the permissions for the factory that correspond to the passed-in Authorization.
abstract  PermissionsManager getPermissionsManager()
          Returns a permissions manager that can be used to set system wide permissions.
abstract  com.jivesoftware.base.plugin.PluginManager getPluginManager()
          Returns an instance of PluginManager that can be used for acquiring plugin instances.
abstract  PollManager getPollManager()
          Returns a poll manager that can be used to retrieve and manager polls.
abstract  java.util.Iterator getPopularForums()
          Returns an Iterator for the most popular forums in the system as Forum objects.
abstract  java.util.Iterator getPopularThreads()
          Returns an Iterator for the most threads in the system as ForumThread objects.
abstract  PresenceManager getPresenceManager()
          Returns a presence manager that can be used to retrieve and manage presences.
abstract  PrivateMessageManager getPrivateMessageManager()
          Returns a private message manager, which controls private message settings.
abstract  QueryManager getQueryManager()
          Returns a query manager that can be used to retrieve and manage search queries.
abstract  com.jivesoftware.forum.QuestionManager getQuestionManager()
          Returns a QuestionManager, which can be used to manage Questions.
abstract  ReadTracker getReadTracker()
          Returns a read tracker that can be used to track which threads and messages a user has read.
abstract  com.jivesoftware.base.registration.RegistrationManager getRegistrationManager()
          Returns a validation manager that can be used for validating user accounts
abstract  RenderManager getRenderManager()
          Returns a render manager that can be used to manage system wide render filters and macros.
abstract  RewardManager getRewardManager()
          Returns a reward manager that can be used to manage reward points.
abstract  ForumCategory getRootForumCategory()
          Returns the "root" forum category, that all other categories are children of.
abstract  SearchManager getSearchManager()
          Returns the search manger which can be used to manage the index used by Jive to perform searches.
abstract  StatusLevelManager getStatusLevelManager()
          Returns a StatusLevelManager that can be used to check a user status level, find leaders system wide, or by forum/category.
abstract  TagManager getTagManager()
          Returns a tag manager that can be used for managing tags
abstract  UserManager getUserManager()
          Returns a UserManager that can be used to manage users.
abstract  int getUserMessageCount(User user)
          Returns the total number of messages a user has posted in all forums.
abstract  int getUserMessageCount(User user, ResultFilter resultFilter)
          Returns the total number of messages a user has posted in all forums that obey the parameters set by the specificed ResultFilter.
abstract  java.util.Iterator getUserMessages(User user)
          Returns an iterator for all messages posted by a user.
abstract  java.util.Iterator getUserMessages(User user, ResultFilter resultFilter)
          Returns an iterator for all messages posted by a user that obey the parameters set by the specified ResultFilter.
abstract  WatchManager getWatchManager()
          Returns a watch manager that can be used to manage watches.
abstract  com.jivesoftware.forum.watches.WatchSettingsManager getWatchSettingsManager()
          Returns a watch settings manager that can be used to manage watch settings.
abstract  boolean isAuthorized(long permissionType)
          Returns true if the handle on the object has the permission specified.
abstract  void mergeForums(Forum forum1, Forum forum2)
          Merges the content of two forums by copying the threads from forum2 to forum1.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ForumFactory

public ForumFactory()
Method Detail

getInstance

public static ForumFactory getInstance(AuthToken authToken)
Returns a concrete ForumFactory instance. Permissions corresponding to the Authorization will be used. If getting the factory fails, null will be returned.

Parameters:
authToken - the auth token for the user.
Returns:
a concrete ForumFactory instance.

createForum

public abstract Forum createForum(java.lang.String name,
                                  java.lang.String description)
                           throws UnauthorizedException
Creates a new forum.

Parameters:
name - the name of the forum.
description - the description of the forum.
Throws:
UnauthorizedException - if not allowed to create a Forum.

createForum

public abstract Forum createForum(java.lang.String name,
                                  java.lang.String description,
                                  ForumCategory category)
                           throws UnauthorizedException
Creates a new forum in the specified category.

Parameters:
name - the name of the forum.
description - the description of the forum.
Throws:
UnauthorizedException - if not allowed to create a Forum.

getForumCategory

public abstract ForumCategory getForumCategory(long categoryID)
                                        throws ForumCategoryNotFoundException
Returns the forum category with the specified categoryID.

Parameters:
categoryID - the id of the forum category to return.
Returns:
the ForumCategory specified by categoryID.
Throws:
ForumCategoryNotFoundException - if the requested category does not exist.

getRootForumCategory

public abstract ForumCategory getRootForumCategory()
Returns the "root" forum category, that all other categories are children of. The root category can never be deleted, so there isn't a possibility of it not being found.

Returns:
the root forum category.

getForum

public abstract Forum getForum(long forumID)
                        throws ForumNotFoundException,
                               UnauthorizedException
Returns the forum with the specified forumID.

Parameters:
forumID - the id of the forum to return.
Returns:
the forum specified by forumID.
Throws:
UnauthorizedException - if not allowed to read the forum.
ForumNotFoundException - if the requested forum does not exist.

getForum

public abstract Forum getForum(java.lang.String nntpName)
                        throws ForumNotFoundException,
                               UnauthorizedException
Returns the forum with the specified NNTP name.

Parameters:
nntpName - the NNTP Name of the forum to return.
Returns:
the forum.
Throws:
UnauthorizedException - if not allowed to read the forum.
ForumNotFoundException - if the requested forum does not exist.

getForumThread

public abstract 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

public abstract 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.

getMessageID

public abstract long getMessageID(long forumID,
                                  int forumIndex)
Returns the message ID with the specified forumID and forumIndex, or -1 if the forumIndex does not map to a message.

Parameters:
forumID - the forum ID of the message.
forumIndex - the forum index value of the message.
Returns:
the message ID, or -1 if the specified forumIndex is invalid.

getForumCount

public abstract int getForumCount()
Returns the total number of forums in the system. This number might not agree with the number of forums returned by ForumFactory.forums() since that method return an Iterator of forums that a user has read permission for.

Returns:
the total number of forums.

getForumCount

public abstract int getForumCount(ResultFilter resultFilter)
Returns the total number of forums in the system matching the ResultFilter. This number might not agree with the number of forums returned by ForumFactory.forums(ResultFilter) since that method return an Iterator of forums that a user has read permission for.

Parameters:
resultFilter - a ResultFilter used to filter the result.
Returns:
the total number of forums.

getForums

public abstract java.util.Iterator getForums()
Returns all forums in the system that the user has read permission for. Read access can be granted in the following ways:

Returns:
an Iterator of Forum objects for all forums in the system that the user has read permission for.
See Also:
ForumCategory.getRecursiveForums()

getForums

public abstract java.util.Iterator getForums(ResultFilter resultFilter)
Returns all forums in the system that the user has read permission for and that matche the specified ResultFilter.

Parameters:
resultFilter - a ResultFilter object to perform filtering and sorting with.
Returns:
an Iterator for the forums in the system that the user can read and that match the ResultFilter.
See Also:
ForumCategory.getRecursiveForums(ResultFilter)

createQuery

public abstract Query createQuery()
Creates a query object to search through all forums. Note: only forums that the user calling this method has read access for will be included in the search.

Returns:
a Query object that can be used to search all forums.

createQuery

public abstract Query createQuery(Forum[] forums)
Creates a query object to search through the specified list of forums.

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

getPopularForums

public abstract java.util.Iterator getPopularForums()
Returns an Iterator for the most popular forums in the system as Forum objects. Popular forums 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 forums feature works:

Returns:
an Iterator of Forum objects for the most popular forums.

getPopularThreads

public abstract java.util.Iterator getPopularThreads()
Returns an Iterator 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:

Returns:
an Iterator of ForumThread objects for the most popular forums.

deleteForum

public abstract void deleteForum(Forum forum)
                          throws UnauthorizedException
Deprecated. the ForumCategory.deleteForum(Forum) method should now be used instead of this method.

Deletes a forum and all of its content.

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.

mergeForums

public abstract void mergeForums(Forum forum1,
                                 Forum forum2)
                          throws UnauthorizedException
Merges the content of two forums by copying the threads from forum2 to forum1. forum2 will be deleted after all content is merged.

You may only execute this operation if you are a system administrator.

Parameters:
forum1 - the Forum to merge threads into.
forum2 - the Forum to move all threads from.
Throws:
UnauthorizedException

getUserMessageCount

public abstract int getUserMessageCount(User user)
Returns the total number of messages a user has posted in all forums. Warning: forums 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 forum, use the Forum.getMessageCount(ResultFilter) method.

Parameters:
user - the user to tally results for.
Returns:
the number of messages the user has posted.

getUserMessageCount

public abstract int getUserMessageCount(User user,
                                        ResultFilter resultFilter)
Returns the total number of messages a user has posted in all forums that obey the parameters set by the specificed ResultFilter. Warning: forums 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 forum, use the Forum.getMessageCount(ResultFilter) 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

public abstract java.util.Iterator getUserMessages(User user)
Returns an iterator 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 iterator will be less than the number returned by userMessageCount(user).

Parameters:
user - the user to get messages for.

getUserMessages

public abstract java.util.Iterator getUserMessages(User user,
                                                   ResultFilter resultFilter)
Returns an iterator 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 iterator 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 Iterator for all users in the specified range.

getAbuseManager

public abstract com.jivesoftware.forum.abuse.AbuseManager getAbuseManager()
Returns an abuse manager that can be used for managing abuse reports

Returns:
abuse manager instance

getTagManager

public abstract TagManager getTagManager()
Returns a tag manager that can be used for managing tags

Returns:
tag manager instance

getAnnouncementManager

public abstract AnnouncementManager getAnnouncementManager()
Returns an announcement manager, which is used to create and retrieve announcements.

Returns:
an AnnouncementManager instance.

getArchiveManager

public abstract ArchiveManager getArchiveManager()
Returns an archive manager that can be used to manage archiving for forums.

Returns:
an ArchiveManager instance.

getAttachmentManager

public abstract AttachmentManager getAttachmentManager()
Returns an attachment manager that can be used to manage attachment rules.

Returns:
a AttachmentManager to manage attachment rules.

getAvatarManager

public abstract AvatarManager getAvatarManager()
Returns a AvatarManager that can be used to find, create, delete, and make avatars active

Returns:
an instance of the avatar manager

getBanManager

public abstract com.jivesoftware.base.ban.BanManager getBanManager()
Returns a ban manager that can be used for banning users

Returns:
ban manager instance

getEmailManager

public abstract EmailManager getEmailManager()
Returns an EmailManager that can be used for sending out emails

Returns:
an EmailManager that can be used for sending out emails

getPluginManager

public abstract com.jivesoftware.base.plugin.PluginManager getPluginManager()
Returns an instance of PluginManager that can be used for acquiring plugin instances.

Returns:
an instance of PluginManager that can be used for acquiring plugin instances.

getGatewayManager

public abstract com.jivesoftware.forum.gateway.GatewayManager getGatewayManager()
Returns a gateway manager that can be used for managing gateways

Returns:
gateway manager instance

getGroupManager

public abstract GroupManager getGroupManager()
Returns a GroupManager that can be used to manage groups.

Returns:
a group manager.
See Also:
GroupManager

getInterceptorManager

public abstract InterceptorManager getInterceptorManager()
                                                  throws UnauthorizedException
Returns a message interceptor manager that can be used to manage global interceptors.

Returns:
a InterceptorManager to manage global interceptors.
Throws:
UnauthorizedException - if not a system administrator.

getDraftManager

public abstract com.jivesoftware.forum.DraftManager getDraftManager()
Returns a DraftManager that can be used to manager message drafts.

Returns:
a DraftManager to manage message drafts.

getModerationManager

public abstract com.jivesoftware.forum.moderation.ModerationManager getModerationManager()
Returns a moderation manager that can be used for moderating messages

Returns:
moderation manager instance

getPermissionsManager

public abstract PermissionsManager getPermissionsManager()
                                                  throws UnauthorizedException
Returns a permissions manager that can be used to set system wide permissions. Only system admins can perform this function.

Returns:
a PermissionsManager to manage the system permissions.
Throws:
UnauthorizedException - if not a system admin.

getPollManager

public abstract PollManager getPollManager()
Returns a poll manager that can be used to retrieve and manager polls.

Returns:
a PollManager instance.

getPresenceManager

public abstract PresenceManager getPresenceManager()
Returns a presence manager that can be used to retrieve and manage presences.

Returns:
a PresenceManager.
See Also:
PresenceManager

getPrivateMessageManager

public abstract PrivateMessageManager getPrivateMessageManager()
Returns a private message manager, which controls private message settings.

Returns:
a PrivateMessageManager instance.

getQueryManager

public abstract QueryManager getQueryManager()
Returns a query manager that can be used to retrieve and manage search queries.

Returns:
a QueryManager
See Also:
QueryManager

getQuestionManager

public abstract com.jivesoftware.forum.QuestionManager getQuestionManager()
Returns a QuestionManager, which can be used to manage Questions. This feature is only available in Gold Edition.

Returns:
a QuestionManager instance.

getReadTracker

public abstract ReadTracker getReadTracker()
Returns a read tracker that can be used to track which threads and messages a user has read.

Returns:
a ReadTracker instance.

getRegistrationManager

public abstract com.jivesoftware.base.registration.RegistrationManager getRegistrationManager()
Returns a validation manager that can be used for validating user accounts

Returns:
validation manager instance

getRenderManager

public abstract RenderManager getRenderManager()
Returns a render manager that can be used to manage system wide render filters and macros.

Returns:
a RenderManager to manage system wide filters.
See Also:
RenderManager

getRewardManager

public abstract RewardManager getRewardManager()
Returns a reward manager that can be used to manage reward points.

Returns:
a RewardManager to manage reward points.

getSearchManager

public abstract SearchManager getSearchManager()
                                        throws UnauthorizedException
Returns the search manger which can be used to manage the index used by Jive to perform searches.

Returns:
a search manager.
Throws:
UnauthorizedException - if not a system administator.

getStatusLevelManager

public abstract StatusLevelManager getStatusLevelManager()
Returns a StatusLevelManager that can be used to check a user status level, find leaders system wide, or by forum/category. System administrators will also be allowed to manage status levels.

Returns:
an instance of the status level manager

getUserManager

public abstract UserManager getUserManager()
Returns a UserManager that can be used to manage users.

Returns:
a user manager.
See Also:
UserManager

getWatchManager

public abstract WatchManager getWatchManager()
Returns a watch manager that can be used to manage watches.

Returns:
a WatchManager to manage watches.

getWatchSettingsManager

public abstract com.jivesoftware.forum.watches.WatchSettingsManager getWatchSettingsManager()
Returns a watch settings manager that can be used to manage watch settings.

Returns:
a WatchManager to manage watch settings.

getPermissions

public abstract Permissions getPermissions(AuthToken authToken)
Returns the permissions for the factory that correspond to the passed-in Authorization.

Parameters:
authToken - the auth token for the user.
Returns:
the permissions for this object.

isAuthorized

public abstract boolean isAuthorized(long permissionType)
Returns true if the handle on the object has the permission specified. 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.
See Also:
ForumPermissions

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.