Ian Moraes

Subscribe to Ian Moraes: eMailAlertsEmail Alerts
Get Ian Moraes: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

Related Topics: Java Developer Magazine

Java Developer : Article

Java Mail

Java Mail

E-mail functionality is an important system requirement in areas such as e-commerce, customer care, work-flow management and unified messaging. In addition, some application architectures may need to support not only standard mail protocols but also proprietary ones. If you're charged with the task of developing an e-mail client application in Java, you have a number of architectural and design options: building your own services layer to support multiple mail protocols, purchasing third-party components that provide e-mail features or using JavaSoft's JavaMail framework.

This article focuses on the JavaMail framework for developing Internet-based e-mail client applications. The JavaMail API shields application developers from implementation details of specific mail protocols by providing a layer of abstraction designed to support current e-mail standards and any future enhancements. JavaMail increases a developer's productivity by allowing the developer to focus on the business logic of an application rather than on mail protocol implementation. It provides a platform- and protocol-independent means of adding e-mail client features to your applications. JavaMail version 1.1 is a standard Java extension and requires JDK/JRE 1.1.x or higher.

Overview of Internet Mail Protocols
Before getting into the details of JavaMail, a quick overview of some messaging terms and Internet e-mail protocols (IMAP, POP, SMTP) is in order. A message is described in terms of a header and content. A message header comprises information such as sender (from), recipient (to), and message ID (a unique message identifier). A message's content is the actual message body and can comprise multiple parts in the form of text and attachments, as shown in Figure 1.

An e-mail client is used to transfer messages to and from an e-mail server, which is responsible for sending and receiving e-mail messages across the Internet. These servers store a user's messages either permanently or until retrieved by an e-mail client.

To develop an e-mail client you need to deal with protocols for sending and receiving messages. As shown in Figure 2, the common protocol for sending Internet e-mail messages is SMTP (Simple Mail Transfer Protocol). The original SMTP specification limited messages to a certain line length and allowed only 7-bit ASCII characters. The MIME (Multipurpose Internet Mail Extensions) specification builds on SMTP by removing the maximum line length for messages and allowing new types of content (e.g., images, binary files) to be included in e-mail messages. The MIME specification overcomes these limitations by defining additional fields in a message header to describe new types of content and message structure. MIME defines the content-type header to specify the type and subtype of message content. For example, a message with an HTML attachment would have a content-type header set to "text/html". SMTP and MIME are typically used together to send Internet e-mail messages.

Two types of protocols are used to retrieve messages from Internet mail servers: POP3 (Post Office Protocol 3) and IMAP4 (Internet Message Access Protocol 4). Although POP3 is more widely used than IMAP4, the latter has a number of advantages. First, IMAP supports multiple folders on a remote mail server whereas POP3 supports only the Inbox folder. Second, IMAP supports message status flags (e.g., indicates whether a message has been previously seen); POP3 doesn't. These types of protocol features are important considerations in designing your application.

JavaMail provides implementations of SMTP, IMAP4 and POP3. For more information on these Internet mail protocols, you can consult the pertinent RFCs.

JavaMail Architecture
Now that you have a basic understanding of Internet mail terms, we can begin to discuss the JavaMail architecture. As shown in Figure 3, the architecture can be described in terms of three main layers. JavaMail's layered architecture allows clients to use the JavaMail API with different message access protocols (POP3, IMAP4) and message transport protocols (SMTP).

The top layer is the application layer that uses the JavaMail API. The second layer is the JavaMail API that defines a set of abstract classes and interfaces for supporting e-mail client functionality. This is the layer that frees a developer from having to deal with protocol-specific complexities. JavaMail provides concrete subclasses of these abstract classes for Internet mail. The JavaMail API layer depends on concrete implementations of protocols.

The implementation layer forms the third layer of the JavaMail architecture. Since JavaMail is protocol independent, it's up to service providers to implement specific message access and message transfer protocols. Service provider implementations play a role similar to that of JDBC drivers. A provider registry allows service providers to register their protocol implementations to be used by JavaMail APIs. The JavaMail Web site has more information on third-party service providers.

JavaBeans Activation Framework
JavaMail interacts with message content through an intermediate layer called the JavaBeans Activation Framework (JAF), part of the Glasgow specification (a future release of the JavaBeans component model specification). In terms of dealing with e-mail messages, JAF provides a uniform way of determining the type of a message's content and encapsulating access to it. The JAF is implemented as a standard Java extension. Sun provides a royalty-free implementation of JAF that requires JDK 1.1.x or higher.

JAF is used to get and set a message's text and attachments. JavaMail provides convenient methods to interact with JAF. For example, MimeMessage's setText() method can be used to set a string as a message's content with a MIME type of "text/plain." Another example is MimeMessage's getContent() method, which returns a message's content as a Java object by invoking methods on JAF's DataHandler class.

JAF can also be used to view e-mail attachments such as a text file (.txt) or an image (.gif) by instantiating a JavaBean that supports a particular command (e.g., view) on a specific type of message content. As shown below, the JAF DataSource object, which encapsulates the attachment, is used to create a DataHandler object. The DataHandler object uses a CommandInfo object to retrieve the pertinent JavaBean that can be used to perform a specific operation on an attachment. The JavaBean component can then be added to a frame, as shown in the code snippet below. Currently, reference implementations of JAF-aware JavaBeans are available to view text, GIF and JPEG files. CommandInfo, DataSource and DataHandler are all JAF classes.

// file name represents the attachment
FileDataSource attachFds = new FileDataSource(attachmentFilename);
DataHandler dh = new DataHandler(attachFds);
CommandInfo viewCi = dh.getCommand("view");
Frame attachmentWindow = new Frame("View Attachment");
// add the bean to view the attachment to the main window

Examples Using JavaMail
You now have a basic overview of the JavaMail architecture and JAF so we can discuss the main JavaMail classes and methods needed to support an e-mail client. Table 1 describes some fundamental JavaMail classes.

To illustrate the use of JavaMail in an e-mail client application, I'll consider four major use cases: configuring a connection to e-mail servers, sending a message, getting messages from an e-mail server and deleting messages.

Configuring a Connection to an e-Mail Server
Before you can send or receive messages from your mail server, you need to establish a mail session between the mail client and the remote mail servers. Mail user properties are used to initiate a connection to mail servers. The Session class can manage the mail user properties used by the JavaMail API.

// Setting mail user properties
mailProperties = new Properties();
mailProperties.put("mail.transport.protocol", "smtp");
mailProperties.put("mail.smtp.host", "someSmtpHost");

The Session object is a factory for Store and Transport objects. A Session and Store object can be obtained as follows:

// Get a Session object
Session session = Session.getDefaultInstance(mailProperties, null);
// Get a Store object
Store store = session.getStore();

One issue to consider as you design the application architecture of your e-mail client is the dependency between your business layer and JavaMail. To reduce tight coupling between your application's business layer and the JavaMail subsystem, the Facade design pattern can be used. For example, mail user configuration can be passed into a Facade (singleton) to assemble the appropriate JavaMail objects (Session, Transport and Store) and perform any other initialization (e.g., security). As a result, dependencies between your business layer classes and the JavaMail subsystem are reduced, and your business layer can use a simpler interface such as MailFacade.configure(Properties p).

A use case pertaining to e-mail server connectivity is support for "disconnected e-mail operation," which involves maintaining e-mail message stores on both the remote server and a local client, performing operations on both stores, and then being able to synchronize these two stores. JavaSoft's IMAP provider implements interfaces that can be used to support disconnected operation.

At the time of this writing, secure messaging (e.g., support for S/MIME) is currently missing from JavaMail. S/MIME builds security on top of MIME to provide secure electronic messaging for Internet mail in the form of message authentication and data security. Although not available in JavaMail, it can be obtained from a third party. The JavaMail Web site has more information on this and other third-party Web sites.

Sending e-Mail Messages
Once a mail session has been established, an e-mail message can be created and sent. First, a MimeMessage object needs to be constructed. Then, as shown below, the message object is initialized with the recipient's e-mail address(es), the subject of the message and the message text. The message is then sent using the Transport object.

// Create new message
Message msg = new MimeMessage(session);
// Initialize the message
msg.setFrom(new InternetAddress(senderEmailAddress));

JavaMail can also be used for developing mail-enabled servlets (e.g., using a browser to send e-mail to a support center). An important architectural consideration is reuse of the mail functionality in your business layer by both Web and Java clients. This can be accomplished by using a layered architecture and appropriate design patterns. For example, a simple mail Facade that shields a client from the JavaMail API can be used by both a Java client and a servlet to send an e-mail messge; a client needs to provide the view and controller components (Model-View-Controller design pattern) of the application.

When sending messages, users assume that e-mail clients support address books, but JavaMail currently does not. However, the JavaMail API doesn't preclude you from developing your own mechanism (e.g., using XML - for implementing local address books or using JNDI to access an LDAP-enabled server for global address book features). Getting e-Mail Messages

After you've successfully established a mail session, an e-mail client can retrieve your e-mail messages. To retrieve your messages use the Session object to obtain a Store object, which can be used to obtain the Inbox folder, as shown below.

// Opening the Inbox Folder
store = session.getStore();
Folder folder = store.getFolder("INBOX");

After a folder has been successfully opened, it's used to get message totals and the messages, as illustrated in the following code snippet.

 // Getting message totals and messages from a folder
int totalMessages = folder.getMessageCount();
Message[] msgs = folder.getMessages();

Note that the Message objects returned from the getMessages() method call are designed to be lightweight objects. For example, the Message objects returned could comprise only message header details. Retrieval of the actual message content is deferred until the message content is actually used. Thus the getMessages() method isn't designed to be a resource-intensive operation.

A typical e-mail client first displays a summary of messages in the form of header details such as sender (from), recipients (to), subject and sent date. A summary line for each message can be obtained as follows.

Address[] from = msgs[i].getFrom();
Address[] to = msgs[i].getRecipients(Message.RecipientType.TO;
String subject = msgs[i].getSubject();
Date d = msgs[i].getSentDate();

After viewing the message summary, a user typically decides to view the actual message content in the form of text and/or attachments. Now we're ready to get a message's content, which can be retrieved in the form of an object. The retrieved object depends on the type of content. If the content is a message with multiple attachments, a Multipart object (a container of BodyPart objects) is returned. If the Part's content is text, then a simple String object is returned. To retrieve a message's content, you can invoke Part's getContent() method, as illustrated below. Note that Part is an interface implemented by Message and BodyPart classes.

Object o = part.getContent();
If (o instanceof String) {
  // content is text
} else if (o instanceof Multipart) {
  // recursively iterate over container's contents to retrieve attachments
} else if (o instanceof Message) {
  // message content could be a message itself

You've now seen how messages are retrieved using JavaMail. If your application supports both IMAP and POP, you may need to develop different algorithms to download messages, depending on your particular use case and performance requirements. For example, when developing applications for use with low bit-rate clients using POP (which doesn't maintain flags to indicate unread messages), downloading all messages each time becomes a performance issue. Thus you may need an algorithm that uses provider-specific methods to prevent a redownload of messages. Depending on your requirements, other algorithms may be needed.

Each of these different download algorithms can be encapsulated as Strategy classes (Strategy design pattern) that share a common interface. A Strategy Factory can return strategy objects that can be used to download messages, depending on particular user configurations. This approach allows you to switch from one download algorithm to another, depending on the user configuration, and avoid having to use protocol-specific conditional statements. For more information on the Strategy and other design patterns, consult Design Patterns by Gamma et al. (1995).

When you download messages from a server, a feature that's available in some popular e-mail clients is an Inbox Assistant to process incoming messages (e.g., delete messages based on user-specified rules). Currently, JavaMail doesn't provide direct support for features such as automated message filtering.

Deleting e-Mail Messages
A standard use case for e-mail clients is deleting a message. Using JavaMail, deleting messages from a folder is a simple two-step process. First, messages are marked for deletion. Those messages that have been marked are then deleted from a folder by either explicitly invoking a Folder's expunge() method or closing a folder with the expunge parameter of the close() method set to true.

// Set delete message flag
message.setFlag(Flags.Flag.DELETED, true);
// Delete marked messages from folder folder.close(true);

This short introduction should help you use JavaMail 1.1 to develop an e-mail client application. JavaMail is a relatively new framework that will inevitably continue to mature and evolve. Nevertheless, it can be used to rapidly develop an e-mail client application using a higher-level API without having to perform the arduous task of implementing specific mail protocols and developing an architectural infrastructure to support multiple protocols. You can obtain more information on JavaMail/JAF, including sample programs for sending and retrieving e-mail messages, from the references listed below.

JavaMail: http://www.javasoft.com/products/javamail/index.html
JavaBeans Activation Framework: http://www.javasoft.com/beans/glasgow/jaf.html
Gamma, E., Helm, R., Johnson, R., and Vlissides, J. (1995).
Design Patterns: Elements of Reusable Object-Oriented Software.

More Stories By Ian Moraes

Ian Moraes, Ph.D., is a principal engineer at Glenayre Electronics, where he works on the architecture and design of a unified messaging system. Ian has developed client/server systems for the telecommunications and financial services industries.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.