|
Jive Forums API (5.5.20.2-oracle) Developer Javadocs | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jivesoftware.forum.nntp.Session
public class Session
Represents a client-server NNTP session.
Every NNTP connection maintains a session tracking the connection's session state and other information regarding the session.
Constructor Summary | |
---|---|
Session(SessionManager sessionManager,
Connection conn)
Create a session that owns the given connection. |
Method Summary | |
---|---|
ArticlePointer |
getArticlePointer()
Obtain the article pointer associated with the session. |
CommandMonitor |
getCommandMonitor()
Obtain the command monitor that watches the NNTP command-responses for this session. |
java.util.Iterator |
getList(NewsGroupFilter filter)
Retrieves a list of valid newsgroups and associated information. |
java.util.Iterator |
getNewNews(NewsGroupFilter filter)
Retrieve a list of new articles according to several selection criteria. |
NNTPParser |
getParser()
Obtain the parser associated with the session. |
boolean |
isAuthenticated()
Flag indicated if this session has been authenticated. |
boolean |
isPostingOK()
Flag indicating if posting is ok or not. |
void |
postArticle(java.util.Iterator article)
Post the given article to the server. |
void |
quit()
Quits the client-server session. |
boolean |
setPassword(java.lang.String password)
Tests the username-password pair for validity against the forums auth factory. |
void |
setUser(java.lang.String name)
Sets the user name for authentication but does not test the validity of the user name assertion. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Session(SessionManager sessionManager, Connection conn)
conn
- the connection for this session.Method Detail |
---|
public NNTPParser getParser()
public ArticlePointer getArticlePointer()
Obtain the article pointer associated with the session.
An article pointer exists with every NNTP session. However, the article pointer is not valid until a group is selected and an article pointed to.
public void quit() throws java.io.IOException
Quits the client-server session.
QUIT
The server processes the QUIT command and then closes the connection to the client. This is the preferred method for a client to indicate that it has finished all its transactions with the NNTP server.
If a client simply disconnects (or the connection times out, or some other fault occurs), the server should gracefully cease its attempts to service the client.
java.io.IOException
- If there was trouble closing the connectionpublic boolean isPostingOK()
Flag indicating if posting is ok or not.
The posting status may change between initial connection and after authentication.
public boolean isAuthenticated()
Flag indicated if this session has been authenticated.
public void setUser(java.lang.String name)
name
- the name of the userpublic boolean setPassword(java.lang.String password)
password
- the password of the user
public java.util.Iterator getNewNews(NewsGroupFilter filter) throws NoGroupSelectedException, NoPermissionException, ArticleNotFoundException
Retrieve a list of new articles according to several selection criteria.
NEWNEWS newsgroups date time [GMT] []
A list of message-ids of articles posted or received to the specified newsgroup since "date" will be listed. The format of the listing will be one message-id per line, as though text were being sent. A single line consisting solely of one period followed by CR-LF will terminate the list.
Date and time are in the same format as the NEWGROUPS command.
A newsgroup name containing a "*" (an asterisk) may be specified to broaden the article search to some or all newsgroups. The asterisk will be extended to match any part of a newsgroup name (e.g., net.micro* will match net.micro.wombat, net.micro.apple, etc). Thus if only an asterisk is given as the newsgroup name, all newsgroups will be searched for new news.
(Please note that the asterisk "*" expansion is a general replacement; in particular, the specification of e.g., net.*.unix should be correctly expanded to embrace names such as net.wombat.unix and net.whocares.unix.)
Conversely, if no asterisk appears in a given newsgroup name, only the specified newsgroup will be searched for new articles. Newsgroup names must be chosen from those returned in the listing of available groups. Multiple newsgroup names (including a "*") may be specified in this command, separated by a comma. No comma shall appear after the last newsgroup in the list. [Implementors are cautioned to keep the 512 character command length limit in mind.]
The exclamation point ("!") may be used to negate a match. This can be used to selectively omit certain newsgroups from an otherwise larger list. For example, a newsgroups specification of "net.*,mod.*,!mod.map.*" would specify that all net.<anything> and all mod.<anything> EXCEPT mod.map.<anything> newsgroup names would be matched. If used, the exclamation point must appear as the first character of the given newsgroup name or pattern.
The optional parameter "distributions" is a list of distribution groups, enclosed in angle brackets. If specified, the distribution portion of an article's newsgroup (e.g, 'net' in 'net.wombat') will be examined for a match with the distribution categories listed, and only those articles which have at least one newsgroup belonging to the list of distributions will be listed. If more than one distribution group is to be supplied, they must be separated by commas within the angle brackets.
The use of the IHAVE, NEWNEWS, and NEWGROUPS commands to distribute news is discussed in an earlier part of this document.
Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there is currently no new news.
filter
- A filter to further restrict the list of qualifying items
NoGroupSelectedException
NoPermissionException
ArticleNotFoundException
public java.util.Iterator getList(NewsGroupFilter filter) throws NoPermissionException, NewsGroupNotFoundException
Retrieves a list of valid newsgroups and associated information.
Each newsgroup is sent as a line of text in the following format:
group last first p
where <group> is the name of the newsgroup, <last> is the number of the last known article currently in that newsgroup, <first> is the number of the first article currently in the newsgroup, and <p> is either 'y' or 'n' indicating whether posting to this newsgroup is allowed ('y') or prohibited ('n').
The <first> and <last> fields will always be numeric. They may have leading zeros. If the <last> field evaluates to less than the <first> field, there are no articles currently on file in the newsgroup.
Note that posting may still be prohibited to a client even though the LIST command indicates that posting is permitted to a particular newsgroup. See the POST command for an explanation of client prohibitions. The posting flag exists for each newsgroup because some newsgroups are moderated or are digests, and therefore cannot be posted to; that is, articles posted to them must be mailed to a moderator who will post them for the submitter. This is independent of the posting permission granted to a client by the NNTP server.
Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there are currently no valid newsgroups.
This method supports both RFC-977 as well as RFC-2980 extended list commands. These include:
Retrieves a list of newsgroups created since a given date and time will be listed in the same format as the LIST command.
NEWGROUPS date time [GMT] [
] The date is sent as 6 digits in the format YYMMDD, where YY is the last two digits of the year, MM is the two digits of the month (with leading zero, if appropriate), and DD is the day of the month (with leading zero, if appropriate). The closest century is assumed as part of the year (i.e., 86 specifies 1986, 30 specifies 2030, 99 is 1999, 00 is 2000).
Time must also be specified. It must be as 6 digits HHMMSS with HH being hours on the 24-hour clock, MM minutes 00-59, and SS seconds 00-59. The time is assumed to be in the server's timezone unless the token "GMT" appears, in which case both time and date are evaluated at the 0 meridian.
The optional parameter "distributions" is a list of distribution groups, enclosed in angle brackets. If specified, the distribution portion of a new newsgroup (e.g, 'net' in 'net.wombat') will be examined for a match with the distribution categories listed, and only those new newsgroups which match will be listed. If more than one distribution group is to be listed, they must be separated by commas within the angle brackets.
Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there are currently no new newsgroups.
filter
- True if the newsgroup descriptions should be included
NoPermissionException
NewsGroupNotFoundException
public CommandMonitor getCommandMonitor()
public void postArticle(java.util.Iterator article) throws PostFailedException, PostRejectedException, PostNotAllowedException
Post the given article to the server.
Called with the article text. The call parses the article, handles it, and returns witheither posting success or failure response.
Responses
article
- an iterator over the String lines in the article
PostFailedException
- if the article could not be posted due to a syntax/format problem.
PostRejectedException
- if the article was rejected.
PostNotAllowedException
- if the user doesn't have permission to post articles.
|
Jive Forums Project Page | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |