Bug 53665 - Minor JNDI Howto document enhancement concerning mail properties
Summary: Minor JNDI Howto document enhancement concerning mail properties
Alias: None
Product: Tomcat 7
Classification: Unclassified
Component: Documentation (show other bugs)
Version: trunk
Hardware: PC Linux
: P2 enhancement with 1 vote (vote)
Target Milestone: ---
Assignee: Tomcat Developers Mailing List
Depends on:
Reported: 2012-08-06 20:06 UTC by Mark Eggers
Modified: 2013-06-20 14:27 UTC (History)
0 users

SVN diff against current Tomcat 7 branch (847 bytes, patch)
2012-08-06 20:06 UTC, Mark Eggers
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Mark Eggers 2012-08-06 20:06:36 UTC
Created attachment 29175 [details]
SVN diff against current Tomcat 7 branch

When configuring mail sessions via JNDI and the Resource element, there is no mention of a password attribute. This attribute is useful if you wish Tomcat to manage the remote connection. One such use case is where the source code to the web application is not available, but requires authenticated connection to an external mail server.

Tomcat has this capability in the default org.apache.naming.factory.MailSessionFactory class, but it's not documented.

The proposed patch amends the jndi-howto document with this information.
Comment 1 David Bullock 2012-10-15 00:27:15 UTC
I was about to file this one, and noticed I had been beaten to the punch.  My description for the issue would have been: 

"Documentation of JavaMail JNDI resource factories fails to document the 'password' attribute".

I was lucky to have found http://stackoverflow.com/questions/6372171/documentation-of-java-mail-api-configuration-for-jndi-in-tomcat or else I'd have been reading the source-code myself.

It's great that when we get a javax.mail.Session via JNDI, Tomcat can arrange for it to have an administrator-configured javax.mail.Authenticator already.

But you do need to:

a) tell the administrator:
   i) what they're doing (causing the Session to issue Transports with Authenitcators already set); and
  ii) how to do it (using the 'password' attribute in combination with various JavaMail provider attributes)

b) re-assure the coder that:
   i) Transport.send(aMessage) ... is right; and using
  ii) aTransport.sendMessage() ... is not *necessary*, because
 iii) the behaviour of Transport.send(Message), in calling aTransport.connect() is OK so long as the deployer knew his work.

c) document who "wins" when the coder calls aTransport.connect(String,String,String) and aTransport.sendMessage(Message) in lieu of using Transport.send(Message)... BUT the deployer already set things up such that the Transport has an Authenticator.  Who will prevail?  (NB.  This is an entirely legitimate use of the Transport, at least as far as the JavaMail FAQ is concerned: http://www.oracle.com/technetwork/java/faq-135477.html#send   I'm not sure if the JavaEE spec says anything about it. (I hope it does, but hopes are not high, and I don't have time to hunt for it rght now).
Comment 2 Mark Thomas 2013-06-20 14:27:39 UTC
This has been fixed in trunk and 7.0.x and will be included in 7.0.42 onwards.

I based the changes on the information in the SO question rather than the suggested patch as it provides a little more concrete information about what is going on.