Introducing the JavaMail API - JavaMail API - page 2

necessarily) organized into one package. Some of these (IMAP, SMTP) are provided
with the reference implementation in the undocumented com.sun.mail package. Oth‐
ers (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 don't 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 provider's 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 re‐
written.
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 topic covers Version 1.5 of the JavaMail API. The JavaMail API is a standard ex‐
tension 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, you'll need to download
it separately from Oracle and install it on your system. It's 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 topic, you'll
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 you're using Java 5, you will also need to install the JavaBeans Activation Framework.
(It's bundled with the JDK starting in Java 6.) You can download it from Oracle's web‐
site . This download contains the activation.jar archive, which you'll also need to place
in your class path.
Finally, you may want to add some additional providers. Oracle's implementation in‐
cludes POP3, SMTP, Gmail, and IMAP providers. However, third parties have written
providers for other protocols such as Hotmail, NNTP, Exchange, and more. Table 1-1
lists some of these.