12 Programming JavaMail with WebLogic Server

The following sections contains information on additional WebLogic Server programming topics:

Overview of Using JavaMail with WebLogic Server Applications

WebLogic Server includes the JavaMail API version 1.4 reference implementation from Sun Microsystems. Using the JavaMail API, you can add email capabilities to your WebLogic Server applications. JavaMail provides access from Java applications to Internet Message Access Protocol (IMAP)- and Simple Mail Transfer Protocol (SMTP)-capable mail servers on your network or the Internet. It does not provide mail server functionality; you must have access to a mail server to use JavaMail.

Complete documentation for using the JavaMail API is available on the JavaMail page on the Sun Web site (http://java.sun.com/products/javamail/index.html). This section describes how you can use JavaMail in the WebLogic Server environment.

The weblogic.jar file contains the following JavaMail API packages from Sun:

  • javax.mail

  • javax.mail.event

  • javax.mail.internet

  • javax.mail.search

The weblogic.jar also contains the Java Activation Framework (JAF) package, which JavaMail requires.

The javax.mail package includes providers for Internet Message Access protocol (IMAP) and Simple Mail Transfer Protocol (SMTP) mail servers. Sun has a separate POP3 provider for JavaMail, which is not included in weblogic.jar. You can download the POP3 provider from Sun and add it to the WebLogic Server classpath if you want to use it.

Understanding JavaMail Configuration Files

JavaMail depends on configuration files that define the mail transport capabilities of the system. The weblogic.jar file contains the standard configuration files from Sun, which enable IMAP and SMTP mail servers for JavaMail and define the default message types JavaMail can process.

Unless you want to extend JavaMail to support additional transports, protocols, and message types, you do not have to modify any JavaMail configuration files. If you do want to extend JavaMail, download JavaMail from Sun and follow Sun's instructions for adding your extensions. Then add your extended JavaMail package in the WebLogic Server classpath in front of weblogic.jar.

Configuring JavaMail for WebLogic Server

To configure JavaMail for use in WebLogic Server, you create a mail session in the WebLogic Server Administration Console. This allows server-side modules and applications to access JavaMail services with JNDI, using Session properties you preconfigure for them. For example, by creating a mail session, you can designate the mail hosts, transport and store protocols, and the default mail user in the Administration Console so that modules that use JavaMail do not have to set these properties. Applications that are heavy email users benefit because the mail session creates a single javax.mail.Session object and makes it available via JNDI to any module that needs it.

For information on using the Administration Console to create a mail session, see "Configure access to JavaMail" in the Oracle WebLogic Server Administration Console Help.

You can override any properties set in the mail session in your code by creating a java.util.Properties object containing the properties you want to override. See Sending Messages with JavaMail. Then, after you look up the mail session object in JNDI, call the Session.getInstance() method with your Properties object to get a customized Session.

Sending Messages with JavaMail

Here are the steps to send a message with JavaMail from within a WebLogic Server module:

  1. Import the JNDI (naming), JavaBean Activation, and JavaMail packages. You will also need to import java.util.Properties:

    import java.util.*;
    import javax.activation.*;
    import javax.mail.*;
    import javax.mail.internet.*;
    import javax.naming.*;
    
  2. Look up the Mail Session in JNDI:

    InitialContext ic = new InitialContext();
    Session session = (Session) ic.lookup("myMailSession");
    
  3. If you need to override the properties you set for the Session in the Administration Console, create a java.util.Properties object and add the properties you want to override. Then call getInstance() to get a new Session object with the new properties.

    Properties props = new Properties();
    props.put("mail.transport.protocol", "smtp");
    props.put("mail.smtp.host", "mailhost");
    // use mail address from HTML form for from address
    props.put("mail.from", emailAddress);
    Session session2 = session.getInstance(props);
    
  4. Construct a MimeMessage. In the following example, to, subject, and messageTxt are String variables containing input from the user.

    Message msg = new MimeMessage(session2);
    msg.setFrom();
    msg.setRecipients(Message.RecipientType.TO, 
                      InternetAddress.parse(to, false));
    msg.setSubject(subject);
    msg.setSentDate(new Date());
    // Content is stored in a MIME multi-part message
    // with one body part
    MimeBodyPart mbp = new MimeBodyPart();
    mbp.setText(messageTxt);
    Multipart mp = new MimeMultipart();
    mp.addBodyPart(mbp);
    msg.setContent(mp);
    
  5. Send the message.

    Transport.send(msg);
    

The JNDI lookup can throw a NamingException on failure. JavaMail can throw a MessagingException if there are problems locating transport classes or if communications with the mail host fails. Be sure to put your code in a try block and catch these exceptions.

Reading Messages with JavaMail

The JavaMail API allows you to connect to a message store, which could be an IMAP server or POP3 server. Messages are stored in folders. With IMAP, message folders are stored on the mail server, including folders that contain incoming messages and folders that contain archived messages. With POP3, the server provides a folder that stores messages as they arrive. When a client connects to a POP3 server, it retrieves the messages and transfers them to a message store on the client.

Folders are hierarchical structures, similar to disk directories. A folder can contain messages or other folders. The default folder is at the top of the structure. The special folder name INBOX refers to the primary folder for the user, and is within the default folder. To read incoming mail, you get the default folder from the store, and then get the INBOX folder from the default folder.

The API provides several options for reading messages, such as reading a specified message number or range of message numbers, or pre-fetching specific parts of messages into the folder's cache. See the JavaMail API for more information.

Here are steps to read incoming messages on a POP3 server from within a WebLogic Server module:

  1. Import the JNDI (naming), JavaBean Activation, and JavaMail packages. You will also need to import java.util.Properties:

    import java.util.*;
    import javax.activation.*;
    import javax.mail.*;
    import javax.mail.internet.*;
    import javax.naming.*;
    
  2. Look up the Mail Session in JNDI:

    InitialContext ic = new InitialContext();
    Session session = (Session) ic.lookup("myMailSession");
    
  3. If you need to override the properties you set for the Session in the Administration Console, create a Properties object and add the properties you want to override. Then call getInstance() to get a new Session object with the new properties:

    Properties props = new Properties();
    props.put("mail.store.protocol", "pop3");
    props.put("mail.pop3.host", "mailhost");
    Session session2 = session.getInstance(props);
    
  4. Get a Store object from the Session and call its connect() method to connect to the mail server. To authenticate the connection, you need to supply the mailhost, username, and password in the connect method:

    Store store = session.getStore();
    store.connect(mailhost, username, password);
    
  5. Get the default folder, then use it to get the INBOX folder:

    Folder folder = store.getDefaultFolder();
    folder = folder.getFolder("INBOX");
    
  6. Read the messages in the folder into an array of Messages:

    Message[] messages = folder.getMessages();
    
  7. Operate on messages in the Message array. The Message class has methods that allow you to access the different parts of a message, including headers, flags, and message contents.

Reading messages from an IMAP server is similar to reading messages from a POP3 server. With IMAP, however, the JavaMail API provides methods to create and manipulate folders and transfer messages between them. If you use an IMAP server, you can implement a full-featured, Web-based mail client with much less code than if you use a POP3 server. With POP3, you must provide code to manage a message store via WebLogic Server, possibly using a database or file system to represent folders.