If you already have a Message object, one way to create a new Message object is to reply to the existing one using the reply( ) method:

public abstract Message reply(boolean replyToAll) 
 throws MessagingException

This method creates a new Message object with the same subject prefixed with “Re: " and addressed to the sender of the original message. If replyToAll is true, then the message is addressed to all known recipients of the original message. The content of the message is empty. If you want to quote the original message, you’ll have to do that yourself.

You’ve already seen that when you’re reading email, the JavaMail API creates Message objects to represent the messages it finds on the server. The primary means of doing this are the getMessage( ) and getMessages( ) methods in the Folder class:

public abstract Message getMessage(int messageNumber) 
 throws MessagingException
public Message[] getMessages(int start, int end) 
 throws MessagingException
public Message[] getMessages(int[] messageNumbers) 
 throws MessagingException
public Message[] getMessages(  ) throws MessagingException

The first three methods allow the caller to specify which messages it wants. The last simply returns all messages in the folder. What’s actually returned are stubs holding the places of the actual messages. The text and headers of the message won’t necessarily be retrieved until some method of the Message class is invoked that requires this information.

These four methods allow you to get and set the From: field of a message:

public abstract Address[] getFrom(  ) throws MessagingException
public abstract void setFrom(  ) throws MessagingException, 
 IllegalWriteException, IllegalStateException 
public abstract void setFrom(Address address) 
 throws MessagingException, IllegalWriteException, IllegalStateException
public abstract void addFrom(Address[] addresses) 
 throws MessagingException, IllegalWriteException, IllegalStateException

The getFrom( ) method returns an array of Address objects, one for each address listed in the From: header. (In practice, it’s rare for a message to be from more than one address. It’s quite common for a message to be addressed to more than one address.) It returns null if the From: header isn’t present in the message. It throws a MessagingException if the From: header is malformed in some way.

The noargs setFrom( ) and addFrom( ) methods set and modify the From: headers of outgoing email messages. The noargs setFrom( ) method sets the header to the current value of the mail.user property or, as a fallback, the user.name property. The setFrom( ) method with arguments sets the value of the From: header to the listed addresses. The addFrom( ) method adds the listed addresses to any addresses that already exist in the header. All three of these methods can throw a MessagingException if one of the addresses they use isn’t in the right format. They can also throw an IllegalWriteException if the From: field of the given Message object cannot be changed or an IllegalStateException if the entire Message object is read only.

Some messages contain a Reply-to: header indicating that any replies should be sent to a different address than the one that sent the message. There are two methods to set and get these addresses:

public Address[] getReplyTo(  ) throws MessagingException
public void setReplyTo(Address[] addresses) throws MessagingException, 
 MethodNotSupportedException, IllegalWriteException, 
 IllegalStateException

The semantics of these methods are the same as for the equivalent getFrom( ) and setFrom( ) methods—in fact, the default implementation of getReplyTo( ) simply returns getFrom( )--with the single caveat that an implementation that doesn’t support separate Reply-to: addresses may throw a MethodNotSupportedException when setReplyTo( ) is invoked.

Whereas the sender of the message is generally found only in the From: header, the recipients of the message are often split across the To:, Cc:, and Bcc: fields. Rather than providing separate methods for each of these fields, the various getRecipients( ) and setRecipients( ) methods rely on a Message.RecipientType argument to determine which field’s value is desired. RecipientType is a public inner class in javax.mail.Message whose private constructor limits it to exactly these three static objects:

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

There are two methods to find the addressees of the Message:

public abstract Address[]getRecipients(Message.RecipientType type) 
 throws MessagingException
public Address[] getAllRecipients(  ) throws MessagingException

The getRecipients( ) method returns an array of Address objects, one for each address listed in the specified header. It returns null if the specified header isn’t present in the message. It throws a MessagingException if the specified header is malformed in some way. The getAllRecipients( ) method does the same except that it combines the contents of the To:, Cc:, and Bcc: headers.

There are two methods to set the recipients of the message while replacing any previous recipients and two methods to add recipients to the message:

public abstract void setRecipients(Message.RecipientType type, 
 Address[] addresses) throws MessagingException, IllegalWriteException, 
 IllegalStateException
public void setRecipient(Message.RecipientType type, Address address) 
 throws MessagingException, IllegalWriteException
public abstract void addRecipients(Message.RecipientType type, 
 Address[] addresses) throws MessagingException,  
 IllegalWriteException, IllegalStateException
public void addRecipient(Message.RecipientType type, Address address) 
 throws MessagingException, IllegalWriteException

All four of these methods can throw a MessagingException, typically because one of the addresses used isn’t in the right format. They can also throw an IllegalWriteException if the specified field of the given Message object cannot be changed or an IllegalStateException if the entire Message object is read-only.

Since the subject is simply a single string of text, it’s very easy to set and get with these two methods:

public abstract String getSubject(  ) throws MessagingException
public abstract void   setSubject(String subject) throws 
 MessagingException, IllegalWriteException, IllegalStateException

As with earlier setter methods, null is returned if the subject field isn’t present in the message. An IllegalWriteException is thrown if the program isn’t allowed to set the value of the Subject: field, and an IllegalStateException is thrown if the program isn’t allowed to change the message at all.

Messages also have sent and received dates. Three methods allow programs to access these fields:

public abstract Date getSentDate(  ) throws MessagingException
public abstract void setSentDate(Date date) throws MessagingException, 
 IllegalWriteException, IllegalStateException
public abstract Date getReceivedDate(  ) throws MessagingException

The underlying implementation is responsible for converting the textual date format found in a message header like “Fri, 5 Aug 2000 10:57:04 +0700” to a java.util.Date object. As usual, a MessagingException indicates some problem with the format of the underlying message; an IllegalWriteException indicates that the field cannot be changed; and an IllegalStateException indicates that the entire message cannot be changed.

Example 19.8 is a simple example program that follows the basic pattern of the last several mail-reading programs. However, this one no longer uses writeTo( ). Instead, it uses the methods in this section to print just the headers. Furthermore, it prints them in a particular order regardless of their order in the actual message on the server. Finally, it ignores the less important headers such as X-UIDL: and Status:. The static InternetAddress.toString( ) method converts the arrays that most of these methods return into simple, comma-separated strings.

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

public class HeaderClient {

  public static void main(String[] args) {
    if (args.length == 0) {
      System.err.println(
       "Usage: java HeaderClient protocol://username@host/foldername");
      return; 
    }
    
    URLName server = new URLName(args[0]);

    try {

      Session session = Session.getDefaultInstance(new Properties(  ), 
       new MailAuthenticator(server.getUsername(  )));

      // Connect to the server and open the folder
      Folder folder = session.getFolder(server);
      if (folder == null) {
        System.out.println("Folder " + server.getFile(  ) + " not found.");
        System.exit(1);
      }  
      folder.open(Folder.READ_ONLY);
      
      // Get the messages from the server
      Message[] messages = folder.getMessages(  );
      for (int i = 0; i < messages.length; i++) {
        System.out.println("------------ Message " + (i+1) 
         + " ------------");
        // Here's the big change...
        String from = InternetAddress.toString(messages[i].getFrom(  ));
        if (from != null) System.out.println("From: " + from);
        String replyTo = InternetAddress.toString(
         messages[i].getReplyTo(  ));
        if (replyTo != null) System.out.println("Reply-to: " 
         + replyTo);
        String to = InternetAddress.toString(
         messages[i].getRecipients(Message.RecipientType.TO));
        if (to != null) System.out.println("To: " + to);
        String cc = InternetAddress.toString(
        messages[i].getRecipients(Message.RecipientType.CC));
        if (cc != null) System.out.println("Cc: " + cc);
        String bcc = InternetAddress.toString(
         messages[i].getRecipients(Message.RecipientType.BCC));
        if (bcc != null) System.out.println("Bcc: " + to);
        String subject = messages[i].getSubject(  );
        if (subject != null) System.out.println("Subject: " + subject);
        Date sent = messages[i].getSentDate(  );
        if (sent != null) System.out.println("Sent: " + sent);
        Date received = messages[i].getReceivedDate(  );
        if (received != null) System.out.println("Received: " + received);
        
        System.out.println(  );
      } 

      // Close the connection 
      // but don't remove the messages from the server
      folder.close(false);
      
    } 
    catch (Exception e) {
      e.printStackTrace(  );
    }  
          
    // Since we may have brought up a GUI to authenticate,
    // we can't rely on returning from main(  ) to exit
    System.exit(0);     
    
  }
}

Here’s some typical output. Several of the requested strings were null because the fields simply weren’t present in the messages in the INBOX; for instance, Cc: and Bcc:. HeaderClient checks for that and simply omits the fields if they’re not present.

% java HeaderClient pop3://[email protected]/INBOX
------------ Message 1 ------------
From: Elliotte Harold <[email protected]>
Reply-to: Elliotte Harold <[email protected]>
To: [email protected]
Subject: test
Sent: Tue Nov 30 13:14:29 PST 1999

------------ Message 2 ------------
From: Elliotte Rusty Harold <[email protected]>
Reply-to: Elliotte Rusty Harold <[email protected]>
To: [email protected]
Subject: New system
Sent: Wed Dec 01 10:55:40 PST 1999

------------ Message 3 ------------
From: Dr. Mickel <[email protected]>
Reply-to: Dr. Mickel <[email protected]>
To: [email protected]
Subject: Breath RX Products now available Online!
Sent: Thu Dec 02 03:45:52 PST 1999

Notice that none of these messages have received dates. That’s because the receive time is not part of the message envelope itself. It has to be provided by the server, and POP servers don’t provide it. An IMAP server would be much more likely to include a received date, as will be shown in Example 19.9.

When you invoke one of the previous set or add methods, some implementations will store the changes immediately. Others, however, may not. The saveChanges( ) method commits the changes made to a Message object:

public abstract void saveChanges(  ) throws MessagingException,
 IllegalWriteException, IllegalStateException

This is not quite a flush. The actual changes may not be committed to disk until the folder containing the message is closed. However, this method does ensure that the changes are stored in the folder and that they will be saved when the folder is saved.