Documentation of Java Mail API configuration for JNDI in Tomcat

Question

I spend several days to figure out how to configure an javax.mail.Session in Tomcat via JNDI with authentication, now I get it but only after a deep dive in the code.

In this time I have seen the worst code ever: javax.mail.Service#connect(String,String,String,String) Version 1.4.1

    if (user == null) {
    user = url.getUsername();
    if (password == null)   // get password too if we need it
        password = url.getPassword();
    } else {
    if (password == null && user.equals(url.getUsername()))
        // only get the password if it matches the username
        password = url.getPassword();
    }

When is the password assigned? and why is it checked against null twice? – and then realize that the else does not belong to the if above. (This is the original indentation). Back to topic.

At least I found that the correct resource definition is:

<Resource name="email/session"
    type="javax.mail.Session"
    auth="Container"
    password="secret"

    mail.debug="false"
    mail.transport.protocol="smtp"

    mail.smtp.auth="true"
    mail.smtp.user="testi"
    mail.smtp.host="smtp.xxx.org"
    mail.smtp.from="test@example.com"       
    />

Pay attention to the fact that it is „password“ and „mail.smtp.user“ or „mail.user“ but not „mail.smtp.password“ or “user”.

At least the magic is done in Tomcats org.apache.naming.factory.MailSessionFactory. This factory add an javax.mail.Authenticator to the mail session if an property password and an property mail.smtp.user or mail.user exits.

Now my question is where is the documentation for all that stuff. Especially about configuration of username and password?

Btw: I explained it a bit more detailed to help other how has the same problem.

Answer 1

Tomcat documentation is limited but the source code is here: http://javasourcecode.org/html/open-source/tomcat/tomcat-7.0.19/org/apache/naming/factory/MailSessionFactory.java.html

Answer 2

This is simply a bug in the documentation. Someone has already raised this on the Tomcat bug tracker

https://bz.apache.org/bugzilla/show_bug.cgi?id=53665

I suggest you register and vote for the bug.