IP*Works!

ipworks
Class Pop

java.lang.Object
  |
  +--ipworks.Pop

public class Pop
extends java.lang.Object

The POP class is used retrieve electronic mail from Internet Post Office servers (POP).

The POP class implements a standard internet post office (POP3) client as specified in RFC 1725.

The class is driven by a few key properties and the Action property. To connect to a MailServer first set the appropriate User and Password and then connect by setting Action to 'Connect'. Upon successful connection to the MailServer , the number of waiting messages is shown by the MessageCount property. A message is selected by setting the MessageNumber property to a number between 1 and MessageCount (inclusive). Then, message text and/or headers are received by setting Action to the appropriate value.

The message text is received through the Transfer event, whereas the message headers are received through the Header event. The body of the message is also saved in the file specified by the LocalFile property. StartTransfer and EndTransfer events are fired at the beginning and end of message transmission. The PITrail event provides a trace of the interaction between the client and server (excluding message transfers).


Field Summary
static int a_Connect
           
static int a_Delete
           
static int a_Disconnect
           
static int a_Idle
           
static int a_Reset
           
static int a_Retrieve
           
 
Constructor Summary
Pop()
           
 
Method Summary
 void addPopEventListener(PopEventListener l)
           
 void fireEndTransfer()
          Fired when the message completes transferring.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireHeader(java.lang.String field, java.lang.String value)
          Fired for every message header being retrieved.
 void firePITrail(int direction, java.lang.String message)
          Traces the commands sent to the mail server, and the respective replies.
 void fireStartTransfer()
          Fired when the message starts transferring.
 void fireTransfer(int bytesTransferred, byte[] text)
          Fired while the message gets transferred from MailServer .
 int getAction()
          An action code for the component.
 java.lang.String getLastReply()
          The last reply from the server.
 java.lang.String getLocalFile()
          The path to a local file for downloading the message body.
 java.lang.String getLocalHost()
          The name of the local host.
 int getMailPort()
          The server port for POP (default 110).
 java.lang.String getMailServer()
          The name or address of a mail server (internet post office server).
 int getMaxLineLength()
          The maximum expected length for message lines.
 int getMaxLines()
          The maximum number of message lines beside headers to retrieve.
 int getMessageCount()
          The number of messages waiting in the mailbox.
 int getMessageNumber()
          Current (selected) message.
 int getMessageSize()
          The size in bytes of the current message.
 java.lang.String getPassword()
          The password for the mailbox user.
 int getTotalSize()
          Cumulative size in bytes of messages in the mailbox (including headers).
 java.lang.String getUser()
          The user id for the mailbox.
 void removePopEventListener(PopEventListener l)
           
 void setAction(int action)
          An action code for the component.
 void setCommand(java.lang.String command)
          Can be used to send additional commands directly to the POP server.
 void setLocalFile(java.lang.String localFile)
          The path to a local file for downloading the message body.
 void setMailPort(int mailPort)
          The server port for POP (default 110).
 void setMailServer(java.lang.String mailServer)
          The name or address of a mail server (internet post office server).
 void setMaxLineLength(int maxLineLength)
          The maximum expected length for message lines.
 void setMaxLines(int maxLines)
          The maximum number of message lines beside headers to retrieve.
 void setMessageNumber(int messageNumber)
          Current (selected) message.
 void setPassword(java.lang.String password)
          The password for the mailbox user.
 void setUser(java.lang.String user)
          The user id for the mailbox.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

a_Idle

public static final int a_Idle

a_Connect

public static final int a_Connect

a_Disconnect

public static final int a_Disconnect

a_Retrieve

public static final int a_Retrieve

a_Delete

public static final int a_Delete

a_Reset

public static final int a_Reset
Constructor Detail

Pop

public Pop()
Method Detail

getAction

public int getAction()
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Connect
Connects to the mail server and attempts to login using the current User and Password . Then it retrieves initial statistics about the mailbox contents ( MessageCount and TotalSize ).
a_Disconnect
Makes the class disconnect from the MailServer by posting a QUIT command. If successful, all changes to the mailbox are committed by the server, otherwise, changes are rolled back to the initial state (before the connection).
a_Retrieve
Asks the MailServer to retrieve the message specified by MessageNumber . Please check also the MaxLines property.
a_Delete
Asks the MailServer to delete the message specified by MessageNumber .
a_Reset
Asks the MailServer to reset all changes and revert back to the state it was when connected.


setAction

public void setAction(int action)
               throws IPWorksException
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Connect
Connects to the mail server and attempts to login using the current User and Password . Then it retrieves initial statistics about the mailbox contents ( MessageCount and TotalSize ).
a_Disconnect
Makes the class disconnect from the MailServer by posting a QUIT command. If successful, all changes to the mailbox are committed by the server, otherwise, changes are rolled back to the initial state (before the connection).
a_Retrieve
Asks the MailServer to retrieve the message specified by MessageNumber . Please check also the MaxLines property.
a_Delete
Asks the MailServer to delete the message specified by MessageNumber .
a_Reset
Asks the MailServer to reset all changes and revert back to the state it was when connected.


setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException
Can be used to send additional commands directly to the POP server. Check the LastReply property and/or trap the PITrail events comming from the server to get the response.


getLastReply

public java.lang.String getLastReply()
The last reply from the server. This is the last reply received from the server. It can be used for information purposes. The same information and more can also be retrieved through the PITrail event.


getLocalFile

public java.lang.String getLocalFile()
The path to a local file for downloading the message body. If the file exists, it is overwritten. (optional) The LocalFile property is used when retrieving a message via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


setLocalFile

public void setLocalFile(java.lang.String localFile)
                  throws IPWorksException
The path to a local file for downloading the message body. If the file exists, it is overwritten. (optional) The LocalFile property is used when retrieving a message via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


getLocalHost

public java.lang.String getLocalHost()
The name of the local host. When connected, the IP address of the interface through which the connection was made. The LocalHost property contains the name of the local host as obtained by the gethostname() Winsock call.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).


getMailPort

public int getMailPort()
The server port for POP (default 110). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the MailPort property while connected will fail with an error.


setMailPort

public void setMailPort(int mailPort)
                 throws IPWorksException
The server port for POP (default 110). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the MailPort property while connected will fail with an error.


getMailServer

public java.lang.String getMailServer()
The name or address of a mail server (internet post office server). The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name of the mail server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.


setMailServer

public void setMailServer(java.lang.String mailServer)
                   throws IPWorksException
The name or address of a mail server (internet post office server). The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name of the mail server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.


getMaxLineLength

public int getMaxLineLength()
The maximum expected length for message lines. Normally, internet mail message lines are up to 80 characters long, however, different mail systems might use other values. Change the value of this property if you are expecting longer lines.


setMaxLineLength

public void setMaxLineLength(int maxLineLength)
                      throws IPWorksException
The maximum expected length for message lines. Normally, internet mail message lines are up to 80 characters long, however, different mail systems might use other values. Change the value of this property if you are expecting longer lines.


getMaxLines

public int getMaxLines()
The maximum number of message lines beside headers to retrieve. The MaxLines property is to limit the number of text lines besides headers retrieved for messages. It can be used to preview message headers and a portion of their contents, without incurring the overhead of downloading the entire message.

The value of the property is a positive integer. If 0, then the entire message will be retrieved, without interruptions.


setMaxLines

public void setMaxLines(int maxLines)
                 throws IPWorksException
The maximum number of message lines beside headers to retrieve. The MaxLines property is to limit the number of text lines besides headers retrieved for messages. It can be used to preview message headers and a portion of their contents, without incurring the overhead of downloading the entire message.

The value of the property is a positive integer. If 0, then the entire message will be retrieved, without interruptions.


getMessageCount

public int getMessageCount()
The number of messages waiting in the mailbox. When the class is not connected to the server, the value of the MessageCount property is 0. When connected, it contains the number of messages in the mail box as reported by the POP server.


getMessageNumber

public int getMessageNumber()
Current (selected) message. The MessageNumber property specifies a message number in between 1 and MessageCount . The various class actions related to single messages use this property as a message pointer (see the description of the Action property and the MessageSize property).


setMessageNumber

public void setMessageNumber(int messageNumber)
                      throws IPWorksException
Current (selected) message. The MessageNumber property specifies a message number in between 1 and MessageCount . The various class actions related to single messages use this property as a message pointer (see the description of the Action property and the MessageSize property).


getMessageSize

public int getMessageSize()
The size in bytes of the current message. If the class is not connected, or MessageNumber does not contain a valid message number, the value of this property is 0. Otherwise, it contains the size of the mail message (including headers) as reported by the server.

The MailServer is asked about the size of the message only if the MessageNumber property has changed. If MessageNumber has not changed, the class returns a cached value.


getPassword

public java.lang.String getPassword()
The password for the mailbox user. This property must be set before the class connects to the MailServer .


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
The password for the mailbox user. This property must be set before the class connects to the MailServer .


getTotalSize

public int getTotalSize()
Cumulative size in bytes of messages in the mailbox (including headers). When the class is not connected to the server, the value of the TotalSize property is 0. When connected, it contains the cumulative size of all the messages in the mail box as reported by the POP server.


getUser

public java.lang.String getUser()
The user id for the mailbox. This property must be set before the class connects to the MailServer .


setUser

public void setUser(java.lang.String user)
             throws IPWorksException
The user id for the mailbox. This property must be set before the class connects to the MailServer .


fireEndTransfer

public void fireEndTransfer()
Fired when the message completes transferring. (Called internally to dispatch the event.)
See Also:
PopEndTransferEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
PopErrorEvent

fireHeader

public void fireHeader(java.lang.String field,
                       java.lang.String value)
Fired for every message header being retrieved. (Called internally to dispatch the event.)
See Also:
PopHeaderEvent

firePITrail

public void firePITrail(int direction,
                        java.lang.String message)
Traces the commands sent to the mail server, and the respective replies. (Called internally to dispatch the event.)
See Also:
PopPITrailEvent

fireStartTransfer

public void fireStartTransfer()
Fired when the message starts transferring. (Called internally to dispatch the event.)
See Also:
PopStartTransferEvent

fireTransfer

public void fireTransfer(int bytesTransferred,
                         byte[] text)
Fired while the message gets transferred from MailServer . (Called internally to dispatch the event.)
See Also:
PopTransferEvent

addPopEventListener

public void addPopEventListener(PopEventListener l)
                         throws java.util.TooManyListenersException

removePopEventListener

public void removePopEventListener(PopEventListener l)

IP*Works!

Copyright (c) 1995-2000 by /n software inc. - All rights reserved.