POP3 Provider ============= Welcome to version 1.1.1 of the POP3 Provider. The POP3 Provider implements a JavaMail(TM) API interface to a POP3 service. The provider provides a Store object that contains a single Folder named "INBOX". Due to the limitations of the POP3 protocol, many of the JavaMail API capabilities like event notification, folder management, flag management etc are not allowed. The corresponding methods throw the MethodNotSupportedException exception. Note that this provider does *not* include a local store into which messages can be downloaded and stored. This provider has been tested against the Sun and Netscape POP3 servers. We welcome your feedback on how this provider works with the numerous other POP3 servers available currently. Contents --------- Included in this release are the following: README.txt this file LICENSE.txt Software license pop3.jar The POP3 provider. DO NOT UNARCHIVE THIS FILE. Requirements ------------ The JavaMail API package and the JavaBeans(TM) Activation Framework packages have to be installed. Download the JavaMail API package from http://java.sun.com/products/javamail. Download the Activation Framework package from http://java.sun.com/beans/glasgow/jaf.html. Installation ------------- 1. Install the JavaMail API and JavaBeans Activation Framework packages. Set your CLASSPATH to include the appropriate jar files. Refer to README.txt from the JavaMail API package for more details. 2. Unzip the pop31_1_1.zip archive. (you may have already done this) 3. Set your CLASSPATH to include the pop3.jar file obtained from the download. 4. To use the POP3 provider, use "pop3" as the protocol-name. For example, try the msgshow.java demo program from the JavaMail API package with "pop3" as the -T option. $ java msgshow -T pop3 -H -U -P -f INBOX That's it ! Note on using the POP3 provider along with another third-party provider ----------------------------------------------------------------------- If you are already using another provider or plan to use one, you need to create a file named javamail.providers (if it does not already exist) and add the following line into the file: protocol=pop3; type=store; class=com.sun.mail.pop3.POP3Store; Similar entries should be included for all the other third-party providers you want to use (if they are not already there). This file should be placed under your application's META-INF directory. Changes since POP3 1.1 release ------------------------------ The following bugs have been fixed: 4269009 POP3 message content includes message header after first getContent 4269054 POP3 connection failures are reported as authentication failures support mail.pop3.timeout property Programming ----------- The POP3 provider is accessed using the JavaMail APIs using the protocol name "pop3" or a URL of the form "pop3://user:password@host:port/INBOX". POP3 supports only a single folder named "INBOX". POP3 supports *no* permanent flags (see Folder.getPermanentFlags()). In particular, the Flags.Flag.RECENT flag will never be set for POP3 messages. It's up to the application to determine which messages in a POP3 mailbox are "new". There are several strategies to accomplish this, depending on the needs of the application and the environment: - A simple approach would be to keep track of the newest message seen by the application. - An alternative would be to keep track of the UIDs (see below) of all messages that have been seen. - Another approach is to download *all* messages into a local mailbox, so that all messages in the POP3 mailbox are, by definition, new. All approaches will require some permanent storage associated with the client. POP3 does not support the Folder.expunge() method. To delete and expunge messages, set the Flags.Flag.DELETED flag on the messages and close the folder using the Folder.close(true) method. You cannot expunge without closing the folder. POP3 does not provide a "received date", so getReceivedDate() will return null. It may be possible to examine other message headers (e.g., the "Received" headers) to estimate the received date, but these techniques are error-prone at best. The POP3 provider now provides support for the POP3 UIDL command. The class com.sun.mail.pop3.POP3Folder includes a new method: public String getUID(Message msg); You can use it as follows: if (folder instanceof com.sun.mail.pop3.POP3Folder) { com.sun.mail.pop3.POP3Folder pf = (com.sun.mail.pop3.POP3Folder)folder; String uid = pf.getUID(msg); if (uid != null) ... // use it } You can also pre-fetch all the UIDs for all messages like this: FetchProfile fp = new FetchProfile(); fp.add(UIDFolder.FetchProfileItem.UID); folder.fetch(folder.getMessages(), fp); Then use the technique above to get the UID for each message. Note that this is similar to the technique used with the UIDFolder interface supported by IMAP. NOTE: This new UIDL support is EXPERIMENTAL. It may be changed incompatibly in future releases. Y2K compliance -------------- Summary: The POP3 protocol provider is Option-3 compliant. The POP3 protocol makes no use of dates. This POP3 protocol provider depends on JavaMail API to parse MIME messages, including any dates included in MIME messages. The JavaMail API itself is Option-3 compliant. Since POP3 does not introduce any new date issues, this POP3 protocol provider is also Option-3 compliant. For more information on compliance levels, refer to: http://www.sun.com/y2000 How to give feedback -------------------- Please send your feedback to this email-address: javamail@sun.com Check out our website at http://java.sun.com/products/javamail You can subscribe to our open discussion-list: javamail-interest@java.sun.com. Or you can subscribe to our low-volume mailing-list (where we announce product updates and other relevant information): javamail-announce@java.sun.com. Instructions on how to subscribe are in our website. If you've found a bug, please try to include the following information as well: - a program or code snippet that shows the problem - the platform you are using - the mail server (vendor name, version number) you are using - your environment variable settings - A stack trace, if appropriate ------------------------------------------------------------------