This post in its entirety turned out to be quite a bit longer than I originally thought it would be, so I am going to break it into parts. Caution: This is going to be very basic and is written for beginners. I felt that there was a need out there for this type of introductory tutorial based on a hosted email account, especially Gmail. So, if you’re looking for an in-depth guide, the JavaMail documentation is a better place to start. If you wish to continue, here’s part 1, stay tuned for parts 2, 3, and 4
In developing a simple email client for a customer that needed to programmatically (no UI) send, receive, and read email from a Gmail account, I had to do a lot more research into the JavaMail API than I really wanted to. I, just like a lot of people, was simply looking for a code snippet that would point me in the right direction for logging into a Gmail account and performing the most basic of operations. In searching for examples and trying to apply certain aspects of them to my application, I found that there is a lot of code out there that is over-coded and a lot that simply doesn’t work.
It seems that many people find the example code packaged with the JavaMail API confusing. I can’t say that I agree with this perception, nor can I say I don’t disagree because many of the simple examples people are looking for are either not covered in a simple, “JavaMail-for-Dummies” manner or not covered specifically. Also, some examples make extensive use of command-line arguments for configuration. The following of the command-line arguments through the code and, of course, the configuration itself are very likely to confuse newbies.
The biggest problem I see with the code I found on the Internet is the over-coding. People have a tendency to code in tons of configuration properties that are totally unnecessary. This over-coding comes from a lack of understanding about what information is needed for what situation and how to communicate that to the API. There seems to be several ways to pass this configuration information to the API. These are listed in rough order that they will override the settings in each “higher-level” technique. Disclaimer: What follows is too simplified an explanation. The reasons for using the different methods of setting up the API exist for very different reasons for each application and I certainly don’t profess to know all the ins and outs of the entire API. Also, for our purposes, we don’t need to know all this, but you can refer to the JavaMail Specification or the API JavaDocs for more info.
1. The API can be initialized with “registry” files that can be placed in a location that the API searches for.
2. A Session object is created with the appropriate settings passed as an argument to the static Session.getInstance(Properties props) factory method as a Java Properties object (This is the most common way).
3. Settings can be passed into factory methods on Session that create the JavaMail objects, Transport and Store, and settings can be passed into their connect() methods.
4. There are setters for a few of the settings.
One of the things that frustrates beginners is that some of the properties that can be passed into the static Session.getInstance() method via a Java Properties object are not documented. This seems to be where a lot of the over-coding comes from. I see a ton of code out there that specifies ports, SSL socket factory classes, and other unnecessary information. If you use the correct methods and specify the correct protocol, JavaMail does the rest. All that extraneous information is needless for interfacing with a simple hosted email account and must be the result of cutting and pasting from more advanced code. The whole purpose of Javamail is to make the job of interfacing with different email server protocols and designs easier!
