Creating Email Components

Now that we've created and configured a Mail Session object to be used with our WebLogic Server installation, we can get into the business of creating email components that can send, retrieve, forward, and authenticate messages, and utilize attachments.

Sending Messages

Sending an email message in a WebLogic Server application involves three main steps:

The following will walk you through each of these steps in putting together a simple program that sends a message with the SMTP protocol.

First, we must import the packages for JavaMail, JAF, and JNDI:

import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;

Next, we obtain a Session object. There are two ways to do this. The first way is using the WebLogic Mail Session via JNDI. We'll use the MyMail Session object that we created in the previous section. This is done in the body of a try/catch block:

try{
 InitialContext ctx = new InitialContext();
 Session session = (Session)ctx.lookup("MyMail");
} catch (NamingException ne) {}

Please note that javax.mail.Session is not serializable. The preceding code is meant only for a server-side component such as a servlet, JSP, or EJB. A standalone Java client will not be able to look up the mail session from the JNDI tree on WebLogic Server. However, a standalone client can create its own Session directly, as shown in the following code snippet.

The second way to create a Session object is to create it from scratch by using the static Session.getInstance() or Session.getDefaultInstance() method. This can be used when no Session objects are declared in the server configuration or a standalone client uses JavaMail without using WebLogic Server. The following sample code snippet shows the usage for a standalone client that does not access the JNDI tree on WebLogic server:

Properties env = new Properties();
String host = "myCompany.com";
String username = "user";
String password = "pwd";
String protocol = "smtp";
env.put("mail.store.protocol", protocol);
env.put("mail.smtp.host", host);
Session session = Session.getInstance(env);

After we have the Session, we can construct a message to send. We'll create an instance of a subclass of the Message class: the MimeMessage class. The new MimeMessage is created by using its constructor and passing it in the current Mail Session object:

Message message = new MimeMessage(session);

Next we'll define some attributes for the message. The new Mail Message object is empty until we define its attributes, such as its subject, recipient, sender, and content.

To add the subject of the message, we use the setSubject method:

message.setSubject("Mail sent through Java Mail" );

Next we add the recipient of the message with the addRecipient method. This method takes a Message.RecipientType object and an Address object. The Message.RecipientType object can be TO, CC (carbon copy), or BCC (blind carbon copy), which are given as:

Message.RecipientType.TO
Message.RecipientType.CC
Message.RecipientType.BCC

In our example, we'll define two recipients: a TO and a CC. Recipients are defined by their email addresses, and these email addresses are given as a subclass of the Address class. So, before we can add the recipients, we must create objects that represent the recipients and then assign the recipient types.

The subclass of the Address class used to define email addresses is InternetAddress. To create a new instance of the InternetAddress class, we pass it one or two parameters to its constructor: a string of the actual email address and (optionally) a string that represents the name associated with the email address. The following code snippet creates two Address objects—one that will be for our message recipient type TO, and another that will be for the CC:

Address address1 = new InternetAddress("wkidd@adventuregalley.com", "William Kidd");

Address address2 = new InternetAddress("sbonnet@revenge.com", "Stede Bonnet");

Now that we've created the Address objects, we can go back and add them to our Message object with the addRecipient method:

message.addRecipient(Message.RecipientType.TO, address1);
message.addRecipient(Message.RecipientType.CC, address2);

If your application has a large number of recipients, the addRecipient method conveniently accepts an array of Address objects. The following code snippet defines a number of To recipients from the Address array spamlist:

Address [] spamlist = new Address[]( { address1, address2 } );
setRecipients(Message.RecipientType.TO, spamlist);

Now that we've defined to whom we're sending the message, we'll define who the message is from. The From is also defined by an InternetAddress object, and we'll pass it to the MimeMessage object's setFrom method. The following code snippet will create an Address object to be used as our From, and will then pass it to the setFrom method:

Address fromAddress = new InternetAddress("broberts@royalfortune.com", "Black Bart");
message.setFrom(fromAddress);

If you want to show multiple From addresses, you can pass an array of Address objects to the addFrom method, as in the following:

Address spammersgroup[] = {fromAddress1, fromAddress2};
message.addFrom(spammersgroup);

The last part to constructing our message is to define some content. This is done with the setContent method of the MimeMessage object.

The setContent method takes a couple of different parameters, depending on the content of your message. If your message is of one object kind, say either text or an HTML document, you would pass in the content object as the first parameter, followed by a string describing the MIME type. For instance:

message.setContent("Hello dude!", "text/plain");

However, if your message consists of multiple parts, say a body of text, as well as an attachment, you must set the content with those body parts. This is done by creating a MultiPart object, which is a container for all the body parts, and then passing it to the setContent method. Let's look at an example to demonstrate this. We'll create a message that consists of a body of text and an attached JPEG file.

First, let's create objects for our two body parts. This is done by defining a subclass of the abstract BodyPart object, MimeBodyPart, as in the following:

BodyPart bp1 = new MimeBodyPart();
BodyPart bp2 = new MimeBodyPart();

To define the content of our MimeBodyPart, we can use its setContent method much like the setContent method of the MimeMessage object used for single-part messages.

Let's define the first body part as some text, as in the following:

bp1.setContent("Hello world.", "text/plain");

bp1.setText("Hello world.");

Now let's define the second body part as a JPEG file attachment. To use an attachment, we must make use of the DataSource and DataHandler objects. These are two of those helper classes from the JavaBeans Activation Framework that are used to recognize and define how to handle different types of files. We don't need to go into the details of how each works to use them in our example, other than to say that they help to define and handle the attachment. Because our JPEG is a file, we'll use the file subclass FileDataSource and pass in the name of the file, vacation.jpg, as a string:

DataSource ds = new FileDataSource("vacation.jpg");
bp2.setDataHandler(new DataHandler(ds));
bp2.setFileName("vacation.jpg");

We have our two body parts, bp1 and bp2, which have their content wrapped inside. Recall that the setContent method of our message takes a MultiPart object, so we must first combine our body parts into a single MultiPart. To do so, we'll use the abstract MultiPart's subclass MimeMultiPart, and then add the body parts with the addBodyPart method:

MultiPart mp = new MimeMultiPart();
mp.addBodyPart(bp1);
mp.addBodyPart(bp2);

The last part to our message construction is to set the content of the message with our MimeMultiPart object, as in the following:

message.setContent(mp);

Our message is now completely defined and ready to send.

The Transport object is used to send messages. This is simply done by passing the message object to the send method, as in the following:

Transport.send(message);

And those are the basics of creating and sending your bare-bones message. Altogether, our simple text message-sending program is shown in Listing 13.1.

Listing 13.1 jspMailSender.jsp

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ page import="javax.activation.*" %>
<%@ page import="javax.mail.*" %>
<%@ page import="javax.naming.*" %>
<%@ page import="javax.mail.internet.*" %>
<%
String host = "myCompany.com";
String username = "user";
String password = "pwd";
String protocol = "smtp";
String mailLookUp = "MyMail";
InitialContext ic = new InitialContext();
javax.mail.Session lookupMailSession = (javax.mail.Session) ic.lookup(mailLookUp);

Properties env = new Properties();
env.put("mail.store.protocol", protocol);
env.put("mail.smtp.host", host);
javax.mail.Session mailSession= lookupMailSession.getInstance(env);

 Message message = new MimeMessage(mailSession);
//set the subject
message.setSubject("Mail sent through Java Mail");

//Construct and set the recipient addresses
Address address1 = new InternetAddress("wkidd@adventuregalley.com", "William Kidd");
Address address2 = new InternetAddress("sbonnet@revenge.com", "Stede Bonnet");

message.addRecipient(Message.RecipientType.TO, address1);
message.addRecipient(Message.RecipientType.CC, address2);

//construct and set the sender address
Address fromAddress = new InternetAddress("author@myCompany.com", "Gurpreet Singh Bhasin");
message.setFrom(fromAddress);

//set the content of the message
 message.setContent("Hello dude!", "text/plain");

//send the message
Transport.send(message);
%>
<html>
<HEAD>
<TITLE>Mailer
</TITLE></HEAD>
<BODY bgcolor=white TOPMARGIN="0" LEFTMARGIN="0" RIGHTMARGIN="0" MARGINWIDTH="0"
 MARGINHEIGHT="0">
</BODY>
</html>

Listing 13.2 is a standalone JavaMail client. Note that in this listing no attempt is made to look up the JNDI tree.

Listing 13.2 MailSender.java

/**
 * @author Gurpreet Singh Bhasin
 */

import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;

public class MailSender {

  public static void main(String[] args) {
    try {
      Properties env = new Properties();
      String host = "myCompany.com";
      String username = "user";
      String password = "pwd";
      String protocol = "smtp";

      env.put("mail.store.protocol", protocol);
      env.put("mail.smtp.host", host);
      Session session = Session.getInstance(env);

      Message message = new MimeMessage(session);
      //set the subject
      message.setSubject("Mail sent through Java Mail");
      Address address1 =
               new InternetAddress(
                 "wkidd@adventuregalley.com",
                 "William Kidd");

      Address address2 =
               new InternetAddress("sbonnet@revenge.com", "Stede Bonnet");

      //construct and set the recipient addresses

      message.addRecipient(Message.RecipientType.TO, address1);
      message.addRecipient(Message.RecipientType.CC, address2);

      //construct and set the sender address
      Address fromAddress =
                new InternetAddress(
                  "author@myCompany.com",
                  "Gurpreet Singh Bhasin");

      message.setFrom(fromAddress);

      //set the content of the message
      message.setContent("Hello, dude!", "text/plain");

      //send the message
      Transport.send(message);
    } catch (Exception e) {
      System.out.println("Exception......");
      e.printStackTrace();
    }
  }
}

Retrieving Messages

Now that we know how to construct and send messages, let's take a look at retrieving messages. Retrieving an email message in a WebLogic Server application involves four main steps:

The following walks you through each of these steps in putting together a simple program that retrieves messages from a POP server with the POP3 protocol.

First, we must import the packages for JavaMail, JAF, and JNDI:

import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;

Next, we get the mail session via JNDI. This is done in the body of a try/catch block:

try{
 InitialContext ctx = new InitialContext();
 Session lookupMailSession = (Session)ctx.lookup("MyMail");
} catch (NamingException ne) {}

As with sending messages, if you need to override any properties defined in the WebLogic Mail Session, create a Properties object and add the properties you want to override. Then call the getInstance method to get a new Session object with the new properties, such as:

Properties env = new Properties();
String host = "mycompany.com";
String username = "userName";
String password = "pwd";
String protocol = "pop3";
env.put("mail.store.protocol", protocol);
env.put("mail.pop3.host", host);
Session session = Session.getInstance(env);

After we have the Mail Session, we can make a connection to the Store object with the getStore method:

Store store = session.getStore();

To connect to the store server, we call the connect method from the Store's parent class Service. Authenticating to the store is done by passing in the parameters for the mailhost, username, and password as String values, such as

store.connect(host, username, password);

where host is the name of the POP3 server, username is the username, and password is the password associated with that username.

Next, we connect to the default Folder object. In the case of POP mail, there's only one default folder, INBOX:

Folder folder = folder.getFolder("INBOX");

Folder folder = folder.getFolder("INBOX");
Folder.open(FOLDER.READ_WRITE);
Message[] messages = folder.getMessages();
For (int count=0; count <messages.length, count++){
  Messages[i].setFlag(Flags.Flag.DELETED, true);
}

Next, we use the Folder's getMessages method to fetch the messages into an array of Message objects:

Message[] messages = folder.getMessages();

Now that we have our messages, we can perform operations on each, such as picking out the headers, content, subject, and to and from fields, and display them in some meaningful manner. For instance, the Message object's getFrom method returns the sender (as an array of Address objects), and the getSubject method returns the subject line of the message:

for (int i = 0, n = message.length; i < n; i++) {
  System.out.println(i + ": "+ message[i].getFrom()[0]
    + "\t" + message[i].getSubject());
}

Those are the basics of retrieving messages from a store. To finish up, remember to close the connection and resources:

folder.close(false);
store.close();

Altogether, our message-retrieval program is a JSP shown in Listing 13.3.

Listing 13.3 jspMailReceiver.jsp

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ page import="javax.activation.*" %>
<%@ page import="javax.mail.*" %>
<%@ page import="javax.naming.*" %>
<%
String host = "mycompany.com";
String username = "userName";
String password = "pwd";
String jndiMailName = "MyMail";
String protocol="pop3";
InitialContext ic = new InitialContext();
javax.mail.Session lookupMailSession = (javax.mail.Session) ic.lookup(jndiMailName);

Store store = lookupMailSession.getStore("pop3");
store.connect(host, username, password);
Folder folder = store.getFolder("INBOX");
folder.open(Folder.READ_ONLY);

// Get directory
Message message[] = folder.getMessages();
for (int i = 0, n = message.length; i < n; i++) {
  out.println(i+ ": " + message[i].getFrom()[0]
    + "\t" + message[i].getSubject());
  out.println("<br>");
}
// Close connection
folder.close(false);
store.close();
%>

<html>
<HEAD>
<TITLE>Mailer
</TITLE></HEAD>
<BODY bgcolor=white TOPMARGIN="0" LEFTMARGIN="0" RIGHTMARGIN="0" MARGINWIDTH="0"
 MARGINHEIGHT="0">
</BODY>
</html>

We also list Java code to retrieve mail without using a JNDI tree. The source is as shown in Listing 13.4.

Listing 13.4 MailReceiver.java

/**
 * @author Gurpreet Singh Bhasin
 */

import java.util.*;
import javax.activation.*;
import javax.mail.*;

public class MailReceiver {

  public static void main(String[] args) {
    try {
        Properties env = new Properties();
        String host = "mycompany.com";
        String username = "userName";
        String password = "pwd";
        String protocol = "pop3";
        env.put("mail.store.protocol", protocol);
        env.put("mail.pop3.host", host);
        Session session = Session.getInstance(env);
        Store store = session.getStore(protocol);
        store.connect(host, username, password);
        Folder folder = store.getFolder("INBOX");
        folder.open(Folder.READ_ONLY);

        // Get directory
        Message message[] = folder.getMessages();

        for (int i = 0, n = message.length; i < n; i++) {
          System.out.println(i + ": " + message[i].getFrom()[0]
            + "\t" + message[i].getSubject());
        }

        // Close connection
        folder.close(false);
        store.close();

    } catch (Exception e) {
      System.out.println("Exception................");
      e.printStackTrace();
    }
  }
}

User Authentication

Many SMTP servers require authentication to be able to send mail. If this is the case with your SMTP service provider, you must create and use your own authenticating mail session. To do this, we must make use of our own authentication object. The JavaMail API provides the abstract class Authenticator for just such purposes. The Authenticator defines a getPasswordAuthentication callback method, which when called by the session, returns a PasswordAuthentication object that's used by the session to authenticate against the SMTP host. The PasswordAuthentication object is itself just a wrapper for the username and password strings.

So, the first thing we must do is to create and define our own subclass of Authenticator. The session will use its getPasswordAuthentication method to return the username and password as strings wrapped in a PasswordAuthentication object. How do we get the username and password? The easiest thing to do is to pop up a little Swing pop-up box that takes both inputs delimited by a comma. Listing 13.5 defines a subclass of the Authenticator class, UserAuthenticator.java, which does this.

Listing 13.5 UserAuthenticator.java

import javax.mail.*;
import javax.swing.*;
import java.util.*;

public class UserAuthenticator extends Authenticator
{
  private String username;
  private String password;

  public void setUser(String user)
  {
    username = user;
  }

  public String getUsername()
  {
    return username;
  }

  public void setPassword(String pword)
  {
    password = pword;
  }

  public String getPassword()
  {
    return password;
  }

  public PasswordAuthentication getPasswordAuthentication()
  {
    String input= JOptionPane.showInputDialog("Enter 'username,password'");
    StringTokenizer st = new StringTokenizer(input, ",");
    username = st.nextToken();
    password = st.nextToken();

    return new PasswordAuthentication(username, password);
  }
}

When the session calls the getPasswordAuthentication method to get the PasswordAuthentication object, a Swing pop-up box that looks like the one in Figure 13.6 is displayed to the user.

Okay, now that we have our authentication object, we can use it to create our authenticating mail session. We first define the environment properties of the session, and then create an instance of our authentication object, as in the following code snippet:

Properties env = new Properties();
env.put("mail.pop3.host", host);
Authenticator auth = new UserAuthenticator();

We can then create the mail session by passing the subclass object to the getDefaultInstance method of the Session:

Session session = Session.getDefaultInstance(env, auth);

When authentication is required, the session will invoke the getPasswordAuthentication method on the subclass. The pop-up is displayed, the username and password strings are submitted, and a PasswordAuthentication object is returned.

Please note that there is a another method to get an instance of a Session object, getInstance(), which takes the same arguments as the getDefaultInstance() method. The getInstance() method always gets a new instance of the Session object based on the parameters. On the other hand, the getDefaultInstance() method gets the default Session object. If no Session object exists, a new session is created and set as default.

Also note that the default Session object can contain security information pertaining to the session. Therefore, access to it is controlled. The Authenticator object passed as a parameter is used indirectly to validate access to the default Session object. On subsequent calls to the getDefaultInstance() method, the Authenticator object is compared to the Authenticator object passed in the very first time the method was invoked. Only if both objects are same or are loaded from the same class loader is the default Session object accessible.

Also beware that passing a null Authenticator object the first time while calling getDefaultInstance() leaves the door open for anyone to get access to the default Session object. The current example just shows how to create a mail session. In the real world, caution must be observed when creating default Session objects.

After we have authentication, we can finally connect to the store:

Store store = session.getStore("pop3");
store.connect();

Replying to Messages

Before you can reply to a message, it's assumed that you've already established a mail session and have a retrieved message to which you're replying. The reply then involves the following steps:

We'll use the retrieved message to help create our reply message. Assume that the name of the retrieved object message is receivedMsg. A call to receivedMsg's reply method returns another Message object, but one in which the subject is set to the original message's but prefixed with Re:, and the To value is equal to the original message's From value. Other than that, the new reply message will be empty. We must still assign the From value and set the content. The following code snippet creates a new MimeMessage object replyMsg to illustrate this:

MimeMessage replyMsg = (MimeMessage)receivedMsg.reply(false);

Okay, so now we have our empty reply message. Next, we'll use the setFrom method to set the From field. The setFrom method takes an InternetAddress object, which we can define in the parameter:

reply.setFrom(new InternetAddress(jrackham@treasure.com, "Calico Jack"));

To complete the message, we could add text or define some body parts. For our example, we'll just add some text content:

reply.setContent("Avast, ye!", "text/plain");

To include the original message, we can use the MimeBodyPart classes. This is covered later in the chapter when we send the input message as part of the reply.

Finally, we can use the Transport object to send our reply message:

Transport.send(reply);

Forwarding Messages

Forwarding a message is a little like sending a normal message, but we have to capture the content of the original message. Again, before you can reply to a message, it's assumed that you've already established a mail session, and have a retrieved message that you want to forward. The forward operation involves the following steps:

Let the received message be called recievedMessage. First we create a message object to be our forward message, as shown in the following code snippet:

Message forwardMsg = new MimeMessage(session);

The next step is to define the sender and recipient. The following snippet creates and assigns two InternetAddress objects for a sender and a recipient:

Address add1 = new InternetAddress("abonney@treasure.com", "Anne Bonney");

Address add2 = new InternetAddress("ttew@liberty.com", "Thomas Tew");

forwardMsg.addRecipient(Message.RecipientType.TO, add1);
forwardMsg.setFrom(add2);

To set our subject, we use the getSubject method on the received message:

forwardMsg.setSubject("Fwd: " + receivedMsg.getSubject());

The next step is to add the content. Content of the forwarding message can consist of the original message and attachments, as well as any additional text or attachments you want to add. Because we're dealing with multiple parts, we'll wrap those parts into MimeBodyPart objects, and then wrap those into a single MultiPart object, and finally assign the MultiPart to the forwarding message. For our example, we'll have two body parts: the first will be our added text message, and the second will be the content of the original message.

First, let's create the body part for our own content:

BodyPart addedPart = new MimeBodyPart();
addedPart.setContent("FYI...", "text/plain");

Next we capture the original message content into the second body part. The easiest way to do this is use to use the convenient DataHandler object from the JavaBeans Activation Framework:

BodyPart originalPart = new MimeBodyPart();
originalPart.setDataHandler(receivedMsg.getDataHandler());

Now we have our two body parts consisting of our added content and the forwarded content. Next, we'll wrap those into the MultiPart container:

Multipart multipart = new MimeMultipart();
multipart.addBodyPart(addedPart);
multipart.addBodyPart(originalPart);

Next we use the multipart object to the setContent method of the forwarding message:

forwardMsg.setContent(multipart);

Finally, we can send the message:

Transport.send(forwardMsg);

originalPart.setDisposition(Part.ATTACHMENT);

Working with Attachments

In the preceding sections, we introduced attachments by sending an attached JPEG file. Attachments are files associated with messages, such as an image or HTML file or perhaps a Word document.

Files can be embedded into the body of the message content, or may be attached to the message to be detached and saved or opened by another application. The MIME type association of the file helps the client recognize and handle the file.

To illustrate the differences between attaching and embedding, let's take a look at an example. We'll create and send a message with two body parts: a text message and an HTML file.

First, let's define our message object with the appropriate headers:

Message message = new MimeMessage(session);
message.setSubject("Visit the friendly South Pacific!");
Address add1 = new InternetAddress("wbligh@bounty.co.uk", "William Bligh");
Address add2 = new InternetAddress("jcook@resolution.co.uk", "James Cook");
message.addRecipient(Message.RecipinetType.TO, add1)
message.setFrom(add2);

Now let's build the content of the message. We'll need two body parts: one to hold the text message and one to hold the attached HTML file. Here we create the first body part:

BodyPart bp1 = new MimeBodyPart();
bp1.setText("Will return to this friendly island after Alaska.");

Next, let's create a second body part that we'll use to wrap the HTML file:

BodyPart bp2 = new MimeBodyPart();

Before we can wrap the HTML file into the body part, we first need an object of the File class that represents the HTML file:

File htmlFile = new File("hawaii.html");

where Hawaii.html is the name of the file we want to attach.

Next we need set a DataHandler object for the HTML file. We again turn to the JavaBeans Activation Framework—this time to the FileDataSource object, a subclass of DataSource that represents a file-based source:

FileDataSource fds= new FileDataSource(htmlFile);
DataHandler dh = new DataHandler(fds);

Next, pass the DataHandler object to the setDataHandler method of the body part:

bp2.setDataHandler(dh);

The following sets the filename and description of the attachment in the second body part's header:

bp2.setFileName(htmlFile.getName());
bp2.setDescription("Attached file: " + htmlFile.getName());

Now that we've completed both of our body parts, we'll wrap them into a MimeMultiPart:

MultiPart mp = new MimeMultiPart();
mp.addBodyPart(bp1);
mp.addBodyPart(bp2);

Finally the multipart can be added to the message and the message can be sent:

message.setContent(mp);
Transport.send(message);

The recipient of this message will see the text of the first body part in the body of the email message, and the attached file of second body part will appear, by default, as an outside attachment. The attachment will show the name of the file. Clicking on the attachment on the client side will either invoke the associated program to open the attachment or offer to save the file to a directory.

But what if you want the HTML message to be embedded into the body of the message? To do that, we need to set the disposition of the attachment's body part. The disposition determines whether the attachment is to be embedded into the body of the message or attached outside the body. This is done by passing in a String constant of the Part interface to the setDisposition method of the MimeBodyPart class. The Part interface defines the two as follows:

• ATTACHMENT— The part is to be presented as an attachment.

• INLINE— The part is to be presented inline (embedded).

So, to make the HTML page an embedded in the message, use the INLINE parameter:

bp2.setDisposition(Part.INLINE);

To make the HTML page an external attachment, use the ATTACHMENT parameter (the default, if no disposition is defined):

bp2.setDisposition(Part.INLINE);