CLOSE LOOK ON JAVA MAIL!!

The layout of packages and classes in the Java Mail API demonstrates one of the primary goals of its designers -- that the level of effort required by the developer to build an application should be dictated by the complexity of the application and the level of control required by the developer for the application. In other words, keep the API as simple as possible. The example application included in this article and the examples that ship with the Java Mail API amply demonstrate this point.

On first glance, the number of Java Mail API classes and the detailed layout of these classes may cause you to believe you're in for a heavy learning curve. But in reality, once you get working, you'll find that this API is a simple and handy tool for implementing robust mail/messaging functionality in your applications.

Analysis of the primary Java Mail API package classes provides insight into the common mechanics of e-mail messaging systems. A high-level overview of the classes in the relative order in which they are normally encountered in a typical application reveals the simplicity of the Java Mail API.


Although the Java Mail API contains many more classes than those discussed here, concentrating on some of the core classes to start with makes it easy to understand the essence of the API. The following is a detailed description of these core classes, which include javax.mail.Session, javax.mail.Store, javax.mail.Transport, javax.mail.Folder, and javax.mail.Message.

javax.mail.Session

The javax.mail.Session class is the top-level entry class for the Java Mail API, and its most commonly used methods provide the ability to control and load the classes that represent the service provider implementations (SPI) for various mail protocols. For example, instances of the javax.mail.Store and javax.mail.Session classes -- described below -- are obtained via the Session class. (Note: A service provider is a developer and/or vendor that provides an implementation for an API; examples of Java Mail API implementations include POP3, SMTP, and IMAP4 -


javax.mail.Store

The javax.mail.Store class is implemented by a service provider, such as a POP Mail implementation developer, and allows for read, write, monitor, and search access for a particular mail protocol. The javax.mail.Folder class is accessed through this class and is detailed below.

javax.mail.Transport

The javax.mail.Transport class is another provider-implemented class and is used for sending a message over a specific protocol.

javax.mail.Folder

The javax.mail.Folder class is implemented by a provider; it gives hierarchical organization to mail messages and provides access to e-mail messages in the form of javax.mail.Message class objects.

javax.mail.Message

The javax.mail.Message class is implemented by a provider and models all the details of an actual e-mail message, such as the subject line, sender/recipient e-mail address, sent date, and so on. The guidelines for providers who implement the javax.mail.Message dictate that the actual fetching of e-mail message components should be delayed as long as possible in order to make this class as lightweight as possible.

The Java Mail API and JAF

One design fact worth mentioning is that the Java Mail API is tied to, or rather leverages, another Java extension: the Java Activation Framework (JAF). The JAF is intended to unify the manner of working with the multitude of data formats that are available, whether they be simple text or extremely complex documents composed of images, audio, video, and even "live" objects. In this sense, it might be useful to think of the JAF as providing for Java what plug-ins provide to a Web browser.

A sample Java Mail application

A "list server application" serves as the focal point for a distributed group discussion system based on e-mail. As such, it is a very common and useful way for subscribers to discuss common-interest subjects.

The following Java Mail API-based application is a working example of a useful middletier list server application. The Java Mail API makes this application easy to create (using the default POP3 and SMTP implementations) and ensures that it will easily support any provider-implemented systems that should arise. For example, the current application easily supports POP3, SMTP, and IMAP servers

// create some properties and get the default Session
//
Properties props = new Properties();
props.put("mail.smtp.host", _smtpHost);
Session session = Session.getDefaultInstance(props, null);

// Send newMessage
//
Transport transport = session.getTransport(SMTP_MAIL);
transport.connect(_smtpHost, _user, _password);
transport.sendMessage(newMessage, _toList);



The code for setting up the message fields such as to, from, subject, and date is very simple:



// create a message
//
Address replyToList[] = { new InternetAddress(replyTo) };
Message newMessage = new MimeMessage(session);
if (_fromName != null)
newMessage.setFrom(new InternetAddress(from,
_fromName + " on behalf of " + replyTo));
else
newMessage.setFrom(new InternetAddress(from));
newMessage.setReplyTo(replyToList);
newMessage.setRecipients(Message.RecipientType.BCC, _toList);
newMessage.setSubject(subject);
newMessage.setSentDate(sentDate);


Setting the contents of the message requires reading in the desired contents and then calling the appropriate setContents...() routine as follows:

// Set message contents
//
Object content = message.getContent();
String debugText = "Subject: " + subject + ", Sent date: " + sentDate;
if (content instanceof Multipart)
{
debugMsg("Sending Multipart message (" + debugText + ")");
newMessage.setContent((Multipart)message.getContent());
}
else
{
debugMsg("Sending Text message (" + debugText + ")");
newMessage.setText((String)content);
}