Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum.nntp.spi
Class ForumSession

java.lang.Object
  extended by com.jivesoftware.forum.nntp.spi.ForumSession

public final class ForumSession
extends java.lang.Object

Implements the primary Forum integration point for supporting a Jive NNTP server front end. A unique ForumSession object is created for every user session and generates forum and article views from the perspective of that user only.

A complete backend storage provider implements this class, FMessageArticleAdapter, and FForumNewsGroupAdapter. The news front end is assumed to be a cluster member of an active Forums Silver deployment.

It is assumed that the backend system will be creating and changing the news repository while the NNTP server is operating. This requires the news server NEVER to cache any information gained through this interface in order to present news clients with an up to date view of the server. The backend should cache group information and groups to avoid excessive accesses to underlying persistent storage.

See Also:
NewsGroup, Article

Constructor Summary
ForumSession(NNTPReadStatSession session)
          Protect the constructor from creation.
 
Method Summary
 boolean authenticate(java.lang.String username, java.lang.String password)
          Authenticates the user with the given password, updating the forum factory if the authentication was successful.
 Article getArticle(long messageID)
          Obtain an article by it's message-id.
 Article getArticle(long groupID, int articleNumber)
          Obtain an article by it's article number.
 java.util.Iterator getArticles(NewsGroupFilter groupFilter, ArticleFilter articleFilter)
          Obtain an iterator over all articles on the server.
 Forum getForum(java.lang.String groupName)
          Obtain a forum by it's name.
 ForumFactory getForumFactory()
           
 Article getLastArticle(long groupID, int articleNumber)
          Returns the previous article in the group that proceeds the given article.
 NewsGroup getNewsGroup(long groupID)
          Obtain a group based on it's id.
 NewsGroup getNewsGroup(java.lang.String groupName)
          Obtain a group based on it's name.
 java.util.Iterator getNewsGroups(NewsGroupFilter filter)
          Obtain an iterator over all groups on the server that comply with the given filter.
 Article getNextArticle(long groupID, int articleNumber)
          Returns the next article in the group that follows the given article.
 User getUser()
          Returns the current user that has been authenticated using this adapter.
 boolean isAuthenticated()
          Returns true if the user has authenticated.
 void post(java.util.Iterator article)
          Posts an article to the system.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ForumSession

public ForumSession(NNTPReadStatSession session)
Protect the constructor from creation.

Method Detail

isAuthenticated

public boolean isAuthenticated()
Returns true if the user has authenticated.

Returns:
true if the user has authenticated.

authenticate

public boolean authenticate(java.lang.String username,
                            java.lang.String password)
Authenticates the user with the given password, updating the forum factory if the authentication was successful.

Parameters:
username - the username.
password - the password.
Returns:
true if the authentication succeeded

getForumFactory

public ForumFactory getForumFactory()

getUser

public User getUser()
Returns the current user that has been authenticated using this adapter.

Returns:
The user authenticated on this adapter session or null for anonymous.

getNewsGroups

public java.util.Iterator getNewsGroups(NewsGroupFilter filter)
Obtain an iterator over all groups on the server that comply with the given filter. Currently there are only two group lists that are important, either there is a start date, in which case list the groups created after that date, or obtain all groups on the server. Current client needs seem to not require newsgroup listings since they provide those to the users, but any other customers will need to obtain group lists.

Parameters:
filter - the newsgroup filter to use in determining what groups to list.
Returns:
an Iterator over all NewsGroup objects on the server. The iterator may be empty but must not be null.

getNewsGroup

public NewsGroup getNewsGroup(java.lang.String groupName)
                       throws NewsGroupNotFoundException,
                              NoPermissionException

Obtain a group based on it's name.

Parameters:
groupName - the name of the group.
Returns:
the newsgroup associated with the name.
Throws:
NewsGroupNotFoundException - if no group matches that name.
NoPermissionException

getForum

public Forum getForum(java.lang.String groupName)
               throws NewsGroupNotFoundException,
                      NoPermissionException

Obtain a forum by it's name.

Parameters:
groupName - the name of the group.
Returns:
the forum associated with the name.
Throws:
NewsGroupNotFoundException - if no forum matches that name.
NoPermissionException

getNewsGroup

public NewsGroup getNewsGroup(long groupID)
                       throws NewsGroupNotFoundException,
                              NoPermissionException

Obtain a group based on it's id.

Parameters:
groupID - the id of the group
Returns:
The newsgroup associated with the name
Throws:
NewsGroupNotFoundException - If no group matches that name
NoPermissionException

getArticle

public Article getArticle(long messageID)
                   throws ArticleNotFoundException,
                          NoPermissionException

Obtain an article by it's message-id.

Currenly message IDs are the message long ID surrounded by angle brackets.

Parameters:
messageID - the message ID of the article surrounded by angle brackets.
Returns:
the article associated with the message-id.
Throws:
ArticleNotFoundException - if no article matches the message ID.
NoPermissionException

getArticle

public Article getArticle(long groupID,
                          int articleNumber)
                   throws ArticleNotFoundException

Obtain an article by it's article number.

Parameters:
groupID - the ID of the group the article number belongs to.
articleNumber - the article number of an article.
Returns:
the article associated with the message-id.
Throws:
ArticleNotFoundException - if no article matches the article number.

post

public void post(java.util.Iterator article)
          throws NoPermissionException,
                 PostRejectedException,
                 PostFailedException

Posts an article to the system.

The article is a list of the lines of text (as String objects) in the originally posted article. The article will not contain the trailing '.' body terminator and any NNTP escaped '.' will already be unescaped by the caller.

The article is posted to the groups on the Newsgroups: header line. Articles posted to a moderated group returns success (true) when the article is accepted for moderation (when it's entered into the system) and NOT when it is approved.

Parameters:
article - iterator over the String lines in the articrle
Throws:
NoPermissionException - if the caller did not have permission to post.
PostRejectedException
PostFailedException

getLastArticle

public Article getLastArticle(long groupID,
                              int articleNumber)
                       throws NoPermissionException,
                              ArticleNotFoundException
Returns the previous article in the group that proceeds the given article.

Parameters:
groupID - the newsgroup the article is in.
articleNumber - the current article number.
Returns:
the previous article.
Throws:
NoPermissionException
ArticleNotFoundException

getNextArticle

public final Article getNextArticle(long groupID,
                                    int articleNumber)
                             throws NoPermissionException,
                                    ArticleNotFoundException
Returns the next article in the group that follows the given article.

Parameters:
groupID - the newsgroup the article is in.
articleNumber - the current article number.
Returns:
the next article.
Throws:
NoPermissionException
ArticleNotFoundException

getArticles

public java.util.Iterator getArticles(NewsGroupFilter groupFilter,
                                      ArticleFilter articleFilter)
                               throws NoPermissionException,
                                      NoGroupSelectedException

Obtain an iterator over all articles on the server.

There are two primary usages of this method. The first is to obtain articles in a particular group according to article filter settings (e.g. by range, article ID, or message ID). The second is to obtain a list of new articles that may occur in several groups. The date and groups to search is defined by the newsgroup filter and the article filter is ALL_ARTICLE_FILTER and can be ignored.

Parameters:
groupFilter - a filter describing the valid newsgroups to search and the date-time new groups should have been added after.
articleFilter - a filter describing the valid articles to search.
Returns:
an Iterator over all new Article objects on the server. The iterator may be empty but must not be null.
Throws:
NoPermissionException
NoGroupSelectedException

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.