RSS RSS feed | Atom Atom feed
Popular Articles: Tom Riddle's Magical Diary | AJAX Lego Robot | AJAX CAPTCHA | SQL Multisets

JavaMail Documentation Annoyances

I recently took a look at the JavaMail documentation for Sun's POP3 implementation. On the bottom of the package documentation page there is a list of the different parameters being used along with a explanation. For the connection timeout:

mail.pop3.connectiontimeout int Socket connection timeout value in milliseconds. Default is infinite timeout.
In practice this "infinite timeout" does not really hold since most modern IP stack implementations sense the idleness, and aborts the connection attempt, resulting in a java.net.ConnectionException. For example on my version of WinXP, the timeout is 20 seconds, on my Redhat 9, it's 190 seconds.

Lacking Documentation

Further more, I couldn't find anything about the properties that would potentially be used by the POP3SSLStore. In fact, it leaves you in the believe that the listed parameters applies to POP3SSLStore as well. I found the hard way you need the following parameter names.
mail.pop3s.user String Default user name for POP3.
mail.pop3s.host String The POP3 server to connect to.
mail.pop3s.port int The POP3 server port to connect to, if the connect() method doesn't explicitly specify one. Defaults to 110.
mail.pop3s.connectiontimeout int Socket connection timeout value in milliseconds. Default is infinite timeout.
mail.pop3s.timeout int Socket I/O timeout value in milliseconds. Default is infinite timeout.
mail.pop3s.rsetbeforequit boolean Send a POP3 RSET command when closing the folder, before sending the QUIT command. Useful with POP3 servers that implicitly mark all messages that are read as "deleted"; this will prevent such messages from being deleted and expunged unless the client requests so. Default is false.
mail.pop3s.message.class String Class name of a subclass of com.sun.mail.pop3.POP3Message. The subclass can be used to handle (for example) non-standard Content-Type headers. The subclass must have a public constructor of the form MyPOP3Message(Folder f, int msgno) throws MessagingException.
mail.pop3s.localaddress String Local address (host name) to bind to when creating the POP3 socket. Defaults to the address picked by the Socket class. Should not normally need to be set, but useful with multi-homed hosts where it's important to pick a particular local address to bind to.
mail.pop3s.localport int Local port number to bind to when creating the POP3 socket. Defaults to the port number picked by the Socket class.
mail.pop3s.apop.enable boolean If set to true, use APOP instead of USER/PASS to login to the POP3 server, if the POP3 server supports APOP. APOP sends a digest of the password rather than the clear text password. Defaults to false.
mail.pop3s.socketFactory.class String If set, specifies the name of a class that implements the javax.net.SocketFactory interface. This class will be used to create POP3 sockets.
mail.pop3s.socketFactory.fallback boolean If set to true, failure to create a socket using the specified socket factory class will cause the socket to be created using the java.net.Socket class. Defaults to true.
mail.pop3s.socketFactory.port int Specifies the port to connect to when using the specified socket factory. If not set, the default port will be used.
mail.pop3s.disabletop boolean If set to true, the POP3 TOP command will not be used to fetch message headers. This is ueful for POP3 servers that don't properly implement the TOP command, or that provide incorrect information in the TOP command results. Defaults to false.
mail.pop3s.forgettopheaders boolean If set to true, the headers that might have been retrieved using the POP3 TOP command will be forgotten and replaced by headers retrieved as part ofthe POP3 RETR command. Some servers, such as some version of Microsft Exchange, will return slightly different headers each time the TOP or RETR command is used. To allow the POP3 provider to properly parse the message content returned from the RETR command, the headers also returned by the RETR command must be used. Setting this property to true will cause these headers to be used, even if they differ from the headers returned previously as a result of using the TOP command. Defaults to false.

IMAP too

The same applies to the IMAPSSLStore
mail.imaps.connectiontimeout int Socket connection timeout value in milliseconds. Default is infinite timeout.
mail.imaps.timeout int Socket I/O timeout value in milliseconds. Default is infinite timeout.

Code Snippet

To summarize. If you want to dictate the different timeouts for both POP3 and IMAP connections, this is how you do it
Properties props = new Properties(); final String timeout = "5000"; props.setProperty("mail.imap.connectiontimeout", timeout); props.setProperty("mail.imaps.connectiontimeout", timeout); props.setProperty("mail.pop3.connectiontimeout", timeout); props.setProperty("mail.pop3s.connectiontimeout", timeout); props.setProperty("mail.imap.timeout", timeout); props.setProperty("mail.imaps.timeout", timeout); props.setProperty("mail.pop3.timeout", timeout); props.setProperty("mail.pop3s.timeout", timeout); Session session = Session.getInstance(props,null); Store store = session.getStore(protocol); store.connect(host,port,email,password);
Probably the same applies to the SMTP implementation, haven't yet tested it.

Google And Yahoo Search

At the time of this writing, a search for "mail.pop3s.connectiontimeout" returns no result on the major search engines.
slashdot digg del.icio.us technorati [more]



Re: JavaMail Documentation Annoyances

Thanks for putting this up. I recenlty needed this information. Thanks!

Add a comment Send a TrackBack