Elliotte Rusty Harold - JavaMail API

Elliotte Rusty Harold is originally from New Orleans to which he returns periodically in search of a decent bowl of gumbo. However, he currently resides in the Prospect Heights neighborhood of Brooklyn with his wife Beth, dog Shayna, and cat Marjorie (named after his mother-in-law). He's a frequent speaker at industry conferences including Software Development, Dr. Dobb's Architecure & Design World, SD Best Practices, Extreme Markup Languages, and too many user groups to count. His open source projects include the XOM Library for processing XML with Java and the Amateur media player.

The JavaMail API is a fairly high-level representation of the basic components of any email system. The components are represented by abstract classes in the javax.mail package. For instance, the abstract class javax.mail.Message represents an email message. It declares abstract methods to get and set various kinds of envelope information for the message, such as the sender and addressee, the date sent, and the subject. The abstract class javax.mail.Folder represents a message container. It declares abstract methods to retrieve messages from a folder, move messages between folders, and delete messages from a folder.

These classes are all abstract because they dont make many assumptions about how the email is stored or transferred between machines. For instance, they do not assume that messages are sent using SMTP or that theyre structured as specified in RFC 822. Concrete subclasses of these classes specialize the abstract classes to particular protocols and mail formats. If you want to work with standard Internet email, you might use javax.mail.MimeMessage instead of javax.mail.Message, javax.mail.InternetAddress instead of javax.mail.Address, and com.sun.mail.imap.IMAPStore instead of javax.mail.Store. If you were writing code for a Microsoft Exchange-based system, youd use different concrete implementation classes but the same abstract base classes.

The JavaMail API roughly follows the abstract factory design pattern. This pattern allows you to write your code based on the abstract superclasses without worrying too much about the lower-level details. The protocols and formats used and the associated concrete implementation classes are determined mostly by one line of code early in the program that names the protocol. Changing the protocol name goes 90% of the way toward porting your program from one protocol (say, POP) to another (say, IMAP).

Service providers implement particular protocols. A service provider is a group of concrete subclasses of the abstract JavaMail API classes that specialize the general API to a particular protocol and mail format. These subclasses are probably (though not necessarily) organized into one package. Some of these (IMAP, SMTP) are provided with the reference implementation in the undocumented com.sun.mail package. Others (NNTP, Exchange) are available from third parties. And some (POP) are available from both Oracle and third parties. The purpose of the abstract JavaMail API is to shield you from low-level details like this. You dont write code to access an IMAP server or a POP server; you write code that speaks to the JavaMail API. Then the JavaMail API uses the service provider to speak to the server using its native protocol. This is middleware for email. All you need to do to add a new protocol is install the service providers JAR file. Simple, carefully designed programs that use only the core features of the JavaMail API may be able to use the new provider without even being recompiled. Of course, programs that make use of special features of individual protocols may need to be rewritten.

Since mail arrives from the network at unpredictable times, the JavaMail API relies on an event-based callback mechanism to handle incoming mail. This is exactly the same pattern (even using some of the same classes) found in the Swing and JavaBeans. The javax.mail.event package defines about half a dozen different kinds of mail events, as well as the associated listener interfaces and adapter classes for these events.

While many people still fondly recall the early days of ASCII email and even ASCII pictures, modern email messages contain a bewildering array of multilingual text and multimedia data encoded in formats such as Base64, quoted-printable, BinHex, and uuencode. To handle this, the JavaMail API uses the JavaBeans Activation Framework (JAF) to describe and display this content.

This book covers Version 1.5 of the JavaMail API. The JavaMail API is a standard extension to Java, not part of the core JDK or JRE class library, even in Java 8. (It is a standard part of Java Enterprise Edition (JEE)). Consequently, youll need to download it separately from Oracle and install it on your system. Its freely available from Java. It comes as a JAR archive named javax.mail.jar . This file contains the actual .class files that implement the JavaMail API. To compile or run the examples in this book, youll need to add this file to your class path, either by adding its path to the CLASSPATH environment variable or by placing javax.mail.jar in your jre/lib/ext directory.

If youre using Java 5, you will also need to install the JavaBeans Activation Framework. (Its bundled with the JDK starting in Java 6.) You can download it from Oracles website. This download contains the activation.jar archive, which youll also need to place in your class path.

Finally, you may want to add some additional providers. Oracles implementation includes POP3, SMTP, Gmail, and IMAP providers. However, third parties have written providers for other protocols such as Hotmail, NNTP, Exchange, and more. lists some of these.

Sending messages is the most basic email need of a Java program. While email clients like Thunderbird and mailing list managers like listproc are the only common programs that receive messages, all sorts of programs send messages. For instance, web browsers can submit HTML forms via email. Security scanning tools can run in the background and email their results to the administrator when theyre done. When the Unix cron program detects a misconfigured