Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS FRAMES  | NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

Class injektilo.net.Pop3Connection

java.lang.Object
  |
  +--injektilo.net.Pop3Connection

public class Pop3Connection
extends java.lang.Object
This class implements the Post Office Protocol Version 3 as specified by RFC-1939.

Copyright (c) 1998 Jason Diamond

sendangels@usa.net
http://www.geocities.com/ResearchTriangle/Thinktank/8343/


Field Summary
static int APOP
          Constant passed to setAuthentication.
static int AUTO
          Constant passed to setAuthentication.
static int DEFAULT_PORT
           
static int USER
          Constant passed to setAuthentication.
 
Constructor Summary
Pop3Connection()
           
 
Method Summary
boolean authenticate(java.lang.String user, java.lang.String pass)
          Obtain authorization to access a mailbox.
void close()
          Closes the connection.
boolean delete(int message)
          Mark the specified message for deletion.
int getAuthentication()
          Gets the authentication mechanism being used for this connection.
Pop3InputStream getInputStream()
          Get a Pop3InputStream that can be used to retrieve a message from the server.
int getOctets()
          This method needs docs.
java.util.Vector getOctetsVector()
          This method needs docs.
int getTotalMessages()
          Get the total number of messages available for retrieval.
int getTotalOctets()
          Get the total size in octets of all the available messages.
java.lang.String getUid()
          This method needs docs.
java.util.Vector getUidVector()
          This method needs docs.
boolean list()
          Return a Vector containing the size of each available message in octets.
boolean list(int m)
          Get the size in octets of the specified message.
boolean noOp()
          Send the NOOP command to the server.
boolean open(java.lang.String host, int port)
          Open a connection to the specified host and port.
boolean open(java.lang.String host)
          Open a connection to the specified host using the default port.
boolean quit()
          Send the QUIT command to the server.
java.lang.String readLine()
          Get a line of text from the server.
void readTo(java.io.OutputStream os)
          Read a previously specified message by the retrieve method and write its contents to the specified output stream.
boolean reset()
          Restore any messages marked for deletion to their original state.
boolean retrieve(int message)
          Start the retrieval of the specified message number.
void setAuthentication(int auth)
          Sets the authentication mechanism to use for this connection.
void setDebugOut(java.io.OutputStream os)
          Set the output stream that debug info should be printed to.
void setDebug(boolean on)
          Set whether debug info should be printed to the debug output stream.
boolean status()
          Check the status of a user's maildrop.
boolean top(int message, int lines, java.io.OutputStream os)
          Retrieve the headers and specified amount of lines from the specified message.
boolean top(int m, int n)
          Retrieve the headers and the specified amount of lines from the body of a message.
boolean uidl()
          Retrieve a vector of strings that can be used to uniquely identify each of the available messages.
boolean uidl(int m)
          Retrieve a String that can be used to uniquely identify the specified message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait
 

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT

AUTO

public static final int AUTO
Constant passed to setAuthentication. When authentication is set to AUTO, the authenticate method will first attempt to authenticate the user using the APOP command only if a timestamp was presented when the connection was opened. If not, or if the APOP fails for some reason, the USER/PASS commands are used.
See Also:
setAuthentication, authenticate

USER

public static final int USER
Constant passed to setAuthentication. This is the default value.
See Also:
setAuthentication, authenticate

APOP

public static final int APOP
Constant passed to setAuthentication. Set it to this value if you want to use the APOP command for authenticating the user's identity. Without sending their password in the clear. Note that most servers don't support this option.
See Also:
setAuthentication, authenticate
Constructor Detail

Pop3Connection

public Pop3Connection()
Method Detail

setAuthentication

public void setAuthentication(int auth)
Sets the authentication mechanism to use for this connection. Defaults to USER.
Parameters:
auth - the authentication mechanism to use
See Also:
USER, APOP, getAuthentication

getAuthentication

public int getAuthentication()
Gets the authentication mechanism being used for this connection.
Returns:
the currently selected authentication mechanism
See Also:
USER, APOP, setAuthentication

open

public boolean open(java.lang.String host,
                    int port)
            throws java.net.UnknownHostException,
                   java.io.IOException
Open a connection to the specified host and port.
Parameters:
host - the domain name of the POP3 server
port - the port to connect to on the host
Returns:
true if connection successful, false if failed
Throws:
java.net.UnknownHostException - if the host could not be found
java.io.IOException - if an input or output exception occurred
See Also:
open(String)

open

public boolean open(java.lang.String host)
            throws java.net.UnknownHostException,
                   java.io.IOException
Open a connection to the specified host using the default port.
Parameters:
host - the domain name of the POP3 server
Returns:
true if connection successful, false if failed
Throws:
java.net.UnknownHostException - if the host could not be found
java.io.IOException - if an input or output exception occurred
See Also:
open(String, int)

authenticate

public boolean authenticate(java.lang.String user,
                            java.lang.String pass)
                    throws java.io.IOException
Obtain authorization to access a mailbox. The connection must have already been opened using the open method. The authentication mechanism (USER/PASS or APOP) is set using the setAuthentication method.
Parameters:
user - the name of the account
pass - the account's password
Returns:
true if authorization was granted, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
open, setAuthentication

status

public boolean status()
              throws java.io.IOException
Check the status of a user's maildrop. This sends the STAT command to the POP3 server. If the command succeeds, you can retrieve the number of messages available and the total size in octets with getTotalMessages and getTotalOctets.
Returns:
true if successful, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
getTotalMessages, getTotalOctets

getTotalMessages

public int getTotalMessages()
Get the total number of messages available for retrieval. The status method needs to be invoked before this method will return any useful value.
Returns:
the number of messages available for retrieval or -1 if the status method hasn't been called or an error occured when it was called
See Also:
status

getTotalOctets

public int getTotalOctets()
Get the total size in octets of all the available messages. The status method needs to be invoked before this method will return any useful value.
Returns:
the size in octets of all the available messages or -1 is the status method hasn't been called or an error occured when it was
See Also:
status

list

public boolean list()
            throws java.io.IOException
Return a Vector containing the size of each available message in octets. The Vector will contain as many elements as the highest numbered message on the server. Messages marked for deletion will be represented by an Integer object with a value of -1. For example, if a session started out with 3 messages availble and message 2 was deleted, the resulting vector would contain [message 1's size, -1, message 3's size].
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
getOctetsVector

getOctetsVector

public java.util.Vector getOctetsVector()
This method needs docs.

list

public boolean list(int m)
            throws java.io.IOException
Get the size in octets of the specified message.
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
getOctets

getOctets

public int getOctets()
This method needs docs.

readTo

public void readTo(java.io.OutputStream os)
           throws java.io.IOException
Read a previously specified message by the retrieve method and write its contents to the specified output stream. Any byte-stuffed characters will be removed.
Parameters:
os - the output stream to write to
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
retrieve

retrieve

public boolean retrieve(int message)
                throws java.io.IOException
Start the retrieval of the specified message number. This method sends the RETR command to the server. The client needs to repeatedly call readLine to get the message headers and text.
Parameters:
message - the message number to retrieve
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
readLine, readTo, getInputStream

getInputStream

public Pop3InputStream getInputStream()
                                            throws java.io.IOException
Get a Pop3InputStream that can be used to retrieve a message from the server. This should only be used after you've called retrieve(int). Do not use this in conjunction with the readLine method.
Returns:
a Pop3InputStream that you can read the message with
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
retrieve(int), readLine

readLine

public java.lang.String readLine()
                         throws java.io.IOException
Get a line of text from the server. This method is used after using the retrieve or top method. Any byte-stuffed octets are removed.
Returns:
a String containing one line of the message being retrieved, or null if it's the end of the message
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
retrieve, top

delete

public boolean delete(int message)
              throws java.io.IOException
Mark the specified message for deletion. This can be undone with the reset method.
Parameters:
message - the message number to mark for deletion
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
reset

noOp

public boolean noOp()
            throws java.io.IOException
Send the NOOP command to the server. This is used mainly to keep the server's inactivity timer from closing the connection.
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred

reset

public boolean reset()
             throws java.io.IOException
Restore any messages marked for deletion to their original state.
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
delete

quit

public boolean quit()
            throws java.io.IOException
Send the QUIT command to the server. Any messages marked for deletion will be expunged at this time. The server should then terminate the connection.
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
delete

top

public boolean top(int message,
                   int lines,
                   java.io.OutputStream os)
           throws java.io.IOException
Retrieve the headers and specified amount of lines from the specified message. The headers and text will be output to the specified output stream. All byte-stuffed characters are removed from the output. Not all servers implement this command.
Parameters:
message - the message number to retrieve
lines - the number of lines of text the should be retrieved from the body of the message
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred

top

public boolean top(int m,
                   int n)
           throws java.io.IOException
Retrieve the headers and the specified amount of lines from the body of a message. The readLine method needs to be called to get each line of the message after this method is called. Not all servers implement this command.
Parameters:
message - the message number to retrieve
lines - the number of lines from the body to retrieve
Returns:
a true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
readLine

uidl

public boolean uidl()
            throws java.io.IOException
Retrieve a vector of strings that can be used to uniquely identify each of the available messages. Messages that are marked for deletion will be represented by an empty string. Note: not all servers implement this command.
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
getUidVector

getUidVector

public java.util.Vector getUidVector()
This method needs docs.

uidl

public boolean uidl(int m)
            throws java.io.IOException
Retrieve a String that can be used to uniquely identify the specified message. Not all servers implement this command.
Parameters:
message - the message number to retrieve the uid for
Returns:
true if the command succeeded, false if not
Throws:
java.io.IOException - if an input or output exception occurred
See Also:
getUid

getUid

public java.lang.String getUid()
This method needs docs.

close

public void close()
          throws java.io.IOException
Closes the connection.
Throws:
java.io.IOException - if an input or output exception occurred

setDebug

public void setDebug(boolean on)
Set whether debug info should be printed to the debug output stream.
Parameters:
on - true if you want debugging on, false if not
See Also:
setDebugOut

setDebugOut

public void setDebugOut(java.io.OutputStream os)
Set the output stream that debug info should be printed to. The debug bug flag must be set to true if this setting is to be used.
Parameters:
os - the output stream to print debug info to.
See Also:
setDebug

Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS FRAMES  | NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD