com.jscape.inet.pop
Class Pop

java.lang.Object
  com.jscape.inet.pop.Pop

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PopSsh, PopSsl

public class Pop
extends java.lang.Object
implements java.io.Serializable

Implements the basic functionality of a POP3 client.

Example Usage:

 // new instance with hostname, username and password
 Pop pop = new Pop("pop3.myserver.com","jsmith","secret");
 try
 {
   // connect to POP3 server
   pop.connect();
    // get messages
   Enumeration e = pop.getMessages();
   while(e.hasMoreElements()) {
     EmailMessage em = (EmailMessage)e.nextElement();
   }
    // disconnect
   pop.disconnect();
 }
 catch(Exception e)
 {
   System.out.println(e);
 }
 

See Also:

Serialized Form

Field Summary

static int	AUTH_APOP APOP authentication.
static int	AUTH_LOGIN Standard username/password authentication.
static int	AUTH_PASS Deprecated. replaced by AUTH_LOGIN variable for consistency

Constructor Summary

Pop()
Constructs a new Pop instance.

Pop(java.lang.String hostname, java.lang.String username, java.lang.String password)
Constructs a new Pop instance.

Method Summary

void	addPopListener(PopListener listener) Adds Pop event listener.
void	clearProxySettings() Clears proxy server values.
void	connect() Connects to POP3 server and performs login.
void	deleteMessage(int msg) Deletes message from POP3 server.
void	disconnect() Disconnects from POP3 server.
int	getAuthMode() Gets the authentication mode used when logging into POP3 server.
int	getConnectTimeout() Gets the timeout used when opening a POP3 server connection.
java.io.PrintStream	getDebugStream() Gets PrintStream used in reporting debug statements.
java.lang.String	getHostname() Gets the hostname of the POP3 server.
EmailMessage	getMessage(int msg) Gets message from POP3 server.
int	getMessageCount() Gets number of messages currently in POP3 mailbox.
PopMessageReader	getMessageReader(int msg) Gets a reader that may be used to read message.
java.util.Enumeration	getMessages() Gets all available messages in mailbox from POP3 server.
int	getMessageSize(int msg) Gets size of message in bytes from POP3 server.
int	getPort() Gets the port of the POP3 server.
int	getReadTimeout() Gets the timeout used when reading responses from POP server.
int	getTimeout() Deprecated. Replaced by getConnectTimeout and getReadTimeout
java.lang.String	getTop(int msg, int lines) Gets summary of message from POP3 server.
java.lang.String	getUid(int msg) Gets unique message id for a message on POP3 server.
java.lang.String	getUsername() Gets the username to be used in authentication to POP3 server.
boolean	isConnected() Checks if client is connected to POP3 server.
boolean	isDebug() Gets debug level of POP3 session.
boolean	isDelete() Checks whether to delete messages automatically after retrieval.
java.lang.String	issueCommand(java.lang.String command) Issues a command to POP3 server and reads response.
java.lang.String	issueCommand(java.lang.String command, boolean readResponse) Issues a command to POP3 server and optionally reads response.
java.lang.String	issueCommandMultiLine(java.lang.String command) Issues a command to POP3 server and reads a multi-line response.
void	removePopListener(PopListener listener) Removes specified Pop event listener.
void	setAuthMode(int mode) Sets the authentication mode used when logging into POP3 server.
void	setConnectTimeout(int timeout) Sets the timeout for opening a POP3 server connection.
void	setDebug(boolean debug) Sets debugging state.
void	setDebugStream(java.io.PrintStream debugStream) Sets PrintStream used in reporting debug statements.
void	setDelete(boolean delete) Defines whether to delete messages automatically after retrieval.
void	setHostname(java.lang.String hostname) Sets the hostname of the POP3 server.
void	setPassword(java.lang.String password) Sets the password to be used in authentication to POP3 server.
void	setPort(int port) Sets the port of the POP3 server.
void	setProxyAuthentication(java.lang.String proxyUsername, java.lang.String proxyPassword) Sets the username and password to use when for authentication with proxy server.
void	setProxyHost(java.lang.String proxyHostname, int proxyPort) Sets the proxy hostname and port for this connection.
void	setProxyType(java.lang.String proxyType) Sets the proxy type will be used for this connection.
void	setReadTimeout(int timeout) Sets the timeout for reading responses from POP server.
void	setTimeout(int timeout) Deprecated. Replaced by setConnectTimeout and setReadTimeout
void	setUsername(java.lang.String username) Sets the username to be used in authentication to POP3 server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTH_PASS

public static final int AUTH_PASS

Deprecated. replaced by AUTH_LOGIN variable for consistency

Standard username/password authentication. Use with setAuthMode method.

See Also:

Constant Field Values

AUTH_LOGIN

public static final int AUTH_LOGIN

Standard username/password authentication. Use with setAuthMode method.

See Also:

Constant Field Values

AUTH_APOP

public static final int AUTH_APOP

APOP authentication. Use with setAuthMode method.

See Also:

Constant Field Values

Constructor Detail

Pop

public Pop()

Constructs a new Pop instance.

Pop

public Pop(java.lang.String hostname,
           java.lang.String username,
           java.lang.String password)

Constructs a new Pop instance. Sets hostname, username and password for POP3 connection.

Parameters:

hostname - the hostname of POP3 server

username - the username of POP3 user

password - the password of POP3 user

Method Detail

setAuthMode

public void setAuthMode(int mode)

Sets the authentication mode used when logging into POP3 server. Possible values are Pop.AUTH_LOGIN for username/password authentication or Pop.AUTH_APOP for APOP authentication.

Parameters:

mode - authentication mode

getAuthMode

public int getAuthMode()

Gets the authentication mode used when logging into POP3 server. Possible values are Pop.AUTH_LOGIN for username/password authentication or Pop.AUTH_APOP for APOP authentication.

Returns:

authentication mode

setConnectTimeout

public void setConnectTimeout(int timeout)

Sets the timeout for opening a POP3 server connection. Default is 30 seconds.

Parameters:

timeout - the timeout in milliseconds

getConnectTimeout

public int getConnectTimeout()

Gets the timeout used when opening a POP3 server connection. Default is 30 seconds.

Returns:

timeout server connection.

isConnected

public boolean isConnected()

Checks if client is connected to POP3 server.

Returns:

connection status

setDebug

public void setDebug(boolean debug)

Sets debugging state. All debug statements are reported to debug stream. Default debug stream is System.out

Parameters:

debug - true to turn debugging on

See Also:

setDebugStream(java.io.PrintStream)

isDebug

public boolean isDebug()

Gets debug level of POP3 session. Debug messages are sent to debug stream. Defaul debug stream is System.out

Returns:

true if debugging is on

See Also:

setDebugStream(java.io.PrintStream)

setDebugStream

public void setDebugStream(java.io.PrintStream debugStream)

Sets PrintStream used in reporting debug statements. Default PrintStream is System.out

Parameters:

debugStream - the PrintStream to send debug statements to

See Also:

PrintStream

getDebugStream

public java.io.PrintStream getDebugStream()

Gets PrintStream used in reporting debug statements. Default PrintStream is System.out

Returns:

the PrintStream used for debugging

See Also:

PrintStream

setDelete

public void setDelete(boolean delete)

Defines whether to delete messages automatically after retrieval. Default is false.

Parameters:

delete - true to delete automatically

isDelete

public boolean isDelete()

Checks whether to delete messages automatically after retrieval. Default is false.

Returns:

true if should delete automatically

setHostname

public void setHostname(java.lang.String hostname)

Sets the hostname of the POP3 server.

Parameters:

hostname - the hostname of POP3 server

getHostname

public java.lang.String getHostname()

Gets the hostname of the POP3 server.

Returns:

hostname

getMessage

public EmailMessage getMessage(int msg)
                        throws PopException

Gets message from POP3 server. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.

Parameters:

msg - message id of message

Returns:

the email message with supplied message id

Throws:

PopException - if I/O or POP3 related error occurs

See Also:

EmailMessage

getMessageCount

public int getMessageCount()
                    throws PopException

Gets number of messages currently in POP3 mailbox.

Returns:

the total number of messages in POP3 account mailbox

Throws:

PopException - if I/O or POP3 related error occurs

getMessageReader

public PopMessageReader getMessageReader(int msg)
                                  throws PopException

Gets a reader that may be used to read message. Once this method is invoked you MAY NOT invoke any other methods until you have fully read the message. Failure to comply will result in a corrupt POP session. PopMessageProgressEvent and PopMessageEvent events will not be fired when using this method.

Parameters:

msg - the message id of message

Returns:

a PopMessageReader

Throws:

PopException - if an I/O or POP3 related error occurs.

See Also:

PopMessageReader

getMessageSize

public int getMessageSize(int msg)
                   throws PopException

Gets size of message in bytes from POP3 server. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.

Parameters:

msg - message id of message

Returns:

the size of email message in bytes

Throws:

PopException - if I/O or POP3 related error occurs

getMessages

public java.util.Enumeration getMessages()
                                  throws PopException

Gets all available messages in mailbox from POP3 server.

Returns:

an Enumeration of EmailMessage

Throws:

PopException - if I/O or POP3 related error occurs

See Also:

EmailMessage

setPassword

public void setPassword(java.lang.String password)

Sets the password to be used in authentication to POP3 server.

Parameters:

password - the password of POP3 user

setPort

public void setPort(int port)

Sets the port of the POP3 server. Default value is 110.

Parameters:

port - the port of POP3 server

getPort

public int getPort()

Gets the port of the POP3 server. Default value is 110.

Returns:

port

setReadTimeout

public void setReadTimeout(int timeout)

Sets the timeout for reading responses from POP server. Default is 30 seconds.

Parameters:

timeout - the timeout in milliseconds

getReadTimeout

public int getReadTimeout()

Gets the timeout used when reading responses from POP server. Default is 30 seconds.

Returns:

reading from server timeout.

setTimeout

public void setTimeout(int timeout)

Deprecated. Replaced by setConnectTimeout and setReadTimeout

Sets the timeout for opening a POP3 server connection and reading responses from POP server. Default is 30 seconds.

Parameters:

timeout - the timeout in milliseconds

See Also:

setConnectTimeout(int), setReadTimeout(int)

getTimeout

public int getTimeout()

Deprecated. Replaced by getConnectTimeout and getReadTimeout

Gets the timeout used when opening a POP3 server connection and reading responses from POP server. Default is 30 seconds.

Returns:

timeout

See Also:

getConnectTimeout(), getReadTimeout()

getTop

public java.lang.String getTop(int msg,
                               int lines)
                        throws PopException

Gets summary of message from POP3 server. Used primary to peek at a message without downloading entire contents. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.

Parameters:

msg - message id

lines - number of lines to retrieve

Returns:

portion of message

Throws:

PopException - if I/O or POP3 related error occurs

getUid

public java.lang.String getUid(int msg)
                        throws PopException

Gets unique message id for a message on POP3 server.

Parameters:

msg - the message number to get the unique message id for. Message number is always (1) based, first message number is 1, second is 2 and so on.

Returns:

a unique message id

Throws:

PopException - if an I/O or POP3 related error occurs

setUsername

public void setUsername(java.lang.String username)

Sets the username to be used in authentication to POP3 server.

Parameters:

username - the username of POP3 user

getUsername

public java.lang.String getUsername()

Gets the username to be used in authentication to POP3 server.

Returns:

username

setProxyAuthentication

public void setProxyAuthentication(java.lang.String proxyUsername,
                                   java.lang.String proxyPassword)

Sets the username and password to use when for authentication with proxy server. To clear these settings invoke the #clearProxySettings method.

Parameters:

proxyUsername - the proxy username

proxyPassword - the proxy password

See Also:

clearProxySettings()

setProxyHost

public void setProxyHost(java.lang.String proxyHostname,
                         int proxyPort)

Sets the proxy hostname and port for this connection. To clear these settings invoke the #clearProxySettings method.

Parameters:

proxyHostname - the hostname or ip address of the proxy server

proxyPort - the port of the proxy server

See Also:

clearProxySettings()

setProxyType

public void setProxyType(java.lang.String proxyType)

Sets the proxy type will be used for this connection.

Parameters:

proxyType - The proxy type. Valid values: HTTP, SOCKS5

clearProxySettings

public void clearProxySettings()

Clears proxy server values.

addPopListener

public void addPopListener(PopListener listener)

Adds Pop event listener.

Parameters:

listener - a PopListener

See Also:

PopListener

connect

public void connect()
             throws PopException

Connects to POP3 server and performs login.

Throws:

PopException - if I/O or POP3 related error occurs

deleteMessage

public void deleteMessage(int msg)
                   throws PopException

Deletes message from POP3 server.

Parameters:

msg - message id of message

Throws:

PopException - if I/O or POP3 related error occurs

disconnect

public void disconnect()
                throws PopException

Disconnects from POP3 server. Issues QUIT command to POP3 server.

Throws:

PopException - if I/O or POP3 related error occurs

issueCommand

public java.lang.String issueCommand(java.lang.String command)
                              throws PopException

Issues a command to POP3 server and reads response.

Parameters:

command - a POP3 command

Returns:

POP3 server response

Throws:

PopException - if I/O or POP3 related error occurs

issueCommand

public java.lang.String issueCommand(java.lang.String command,
                                     boolean readResponse)
                              throws PopException

Issues a command to POP3 server and optionally reads response.

Parameters:

command - a POP3 command

readResponse - true if should read response false otherwise

Returns:

POP3 server response

Throws:

PopException - if I/O or POP3 related error occurs

issueCommandMultiLine

public java.lang.String issueCommandMultiLine(java.lang.String command)
                                       throws PopException

Issues a command to POP3 server and reads a multi-line response. This command should only be used for known POP3 commands that issue a known multi-line response such as LIST and TOP.

Parameters:

command - a POP3 command

Returns:

POP3 server response

Throws:

PopException - if I/O or POP3 related error occurs

removePopListener

public void removePopListener(PopListener listener)

Removes specified Pop event listener.

Parameters:

listener - the PopListener to remove

See Also:

PopListener