Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum.nntp
Interface ArticlePointer

All Known Implementing Classes:
ArticlePointerImpl

public interface ArticlePointer

Maintains a pointer to the current article.


Method Summary
 Article getArticle(int number)
          Obtain an article by it's article number.
 Article getArticle(java.lang.String messageID)
          Obtain an article based on it's Message-ID.
 java.util.Iterator getArticles(ArticleFilter filter)
          Obtain all articles in the current group that match the article filter criteria.
 Article getCurrentArticle()
          Obtain the Article this pointer is currently pointing to.
 int getCurrentArticleNumber()
          Obtain the number of the article currently being pointed to.
 NewsGroup getGroup()
          Obtain the group currently assigned to the pointer on null if none has been set.
 Article last()
          Moves the article pointer to the previous article in the current group.
 Article next()
          Moves the article pointer to the next article in the current group.
 NewsGroup setGroup(java.lang.String group)
          Sets the article pointer to use the given group.
 

Method Detail

getArticle

Article getArticle(int number)
                   throws NoGroupSelectedException,
                          ArticleNotFoundException,
                          NoPermissionException
Obtain an article by it's article number. Successful retrieval sets the 'current article' pointer to the retrieved article.

Parameters:
number - the article number to use in selecting the article.
Returns:
the article found.
Throws:
NoGroupSelectedException - if no group was selected before making this call.
ArticleNotFoundException - if no acticle for that number could be found.
NoPermissionException - if the caller didn't have permission to retrieve the article.

getArticle

Article getArticle(java.lang.String messageID)
                   throws ArticleNotFoundException,
                          NoPermissionException
Obtain an article based on it's Message-ID. Successful matches does not affect the pointer.

Parameters:
messageID - The Message-ID of the article to match.
Returns:
The article with given Message-ID.
Throws:
ArticleNotFoundException - If no article was found that has a matching message ID.
NoPermissionException - If the caller does not have permission to retrieve the article.

getCurrentArticle

Article getCurrentArticle()
                          throws ArticleNotFoundException,
                                 NoPermissionException,
                                 ArticleNotSelectedException,
                                 NoGroupSelectedException
Obtain the Article this pointer is currently pointing to.

Returns:
the article being pointed to.
Throws:
ArticleNotFoundException - if the current article has been deleted.
NoPermissionException - if the caller does not have permission to retrieve the article.
ArticleNotSelectedException - if no current article has been set.
NoGroupSelectedException - if no group has been selected.

getCurrentArticleNumber

int getCurrentArticleNumber()
                            throws ArticleNotSelectedException
Obtain the number of the article currently being pointed to.

Returns:
the number of the article being pointed to.
Throws:
ArticleNotSelectedException - if no article has been selected.

getArticles

java.util.Iterator getArticles(ArticleFilter filter)
                               throws NoGroupSelectedException,
                                      ArticleNotSelectedException,
                                      NoPermissionException,
                                      ArticleNotFoundException
Obtain all articles in the current group that match the article filter criteria.

Parameters:
filter - The article filter to restrict the match results
Returns:
An iterator of Article objects that matched the filter
Throws:
NoGroupSelectedException - If no group is curently selected
ArticleNotSelectedException - If the filter is for the current article and none has been selected
NoPermissionException - If the caller does not have permission to get the list
ArticleNotFoundException - If the filter is for a specific article that could not be found

getGroup

NewsGroup getGroup()
                   throws NoGroupSelectedException,
                          NoPermissionException

Obtain the group currently assigned to the pointer on null if none has been set.

Returns:
The group the pointer is currently using, or null for none
Throws:
NoGroupSelectedException - If no group has been selected
NoPermissionException - If the caller does not have permission to get the group

setGroup

NewsGroup setGroup(java.lang.String group)
                   throws NoPermissionException,
                          NewsGroupNotFoundException

Sets the article pointer to use the given group.

The successful selection response will return 220 GROUP_SELECTED otherwise 411 ENO_SUCH_GROUP is returned. Successful responses are accompanied by the article numbers of the first and last articles in the group, and an estimate of the number of articles on file in the group. It is not necessary that the estimate be correct, although that is helpful; it must only be equal to or larger than the actual number of articles on file. (Some implementations will actually count the number of articles on file. Others will just subtract first article number from last to get an estimate.)

When a valid group is selected by means of this command, the internally maintained "current article pointer" is set to the first article in the group. If an invalid group is specified, the previously selected group and article remain selected. If an empty newsgroup is selected, the "current article pointer" is in an indeterminate state and should not be used.

Note that the name of the newsgroup is not case-dependent. It must otherwise match a newsgroup obtained from the LIST command or an error will result.

Parameters:
group - The name of the group to select
Returns:
The group that has been set
Throws:
NoPermissionException - If the caller does not have permission to get the list
NewsGroupNotFoundException - If no group matches the given name

last

Article last()
             throws NoGroupSelectedException,
                    ArticleNotFoundException,
                    ArticleNotSelectedException,
                    NoPermissionException

Moves the article pointer to the previous article in the current group.

The internally maintained "current article pointer" is set to the previous article in the current newsgroup. If already positioned at the first article of the newsgroup, an error message is returned and the current article remains selected:

The internally-maintained "current article pointer" is set by this command.

On successful repositioning of the current article pointer a 223 STAT response indicating the current article number, and a message-id string will be returned. No text is sent in response to this command.

Returns:
the response generated from this command.
Throws:
NoGroupSelectedException - if no group is curently selected.
ArticleNotSelectedException - if no current article has been selected.
NoPermissionException - if the caller does not have permission to get the list.
ArticleNotFoundException - if there is no previous article.

next

Article next()
             throws NoGroupSelectedException,
                    ArticleNotFoundException,
                    ArticleNotSelectedException,
                    NoPermissionException

Moves the article pointer to the next article in the current group.

The internally maintained "current article pointer" is set to the next article in the current newsgroup. If already positioned at the last article of the newsgroup, an error message is returned and the current article remains selected:

The internally-maintained "current article pointer" is set by this command.

On successful repositioning of the current article pointer a 223 STAT response indicating the current article number, and a message-id string will be returned. No text is sent in response to this command.

Returns:
the response generated from this command.
Throws:
NoGroupSelectedException - if no group is curently selected.
ArticleNotSelectedException - if no current article has been selected.
NoPermissionException - if the caller does not have permission to get the list.
ArticleNotFoundException - if there is no next article.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.