Transport Protocols and Mechanisms in JavaMail

Transport Protocols and Mechanisms

The Transport abstract class defines the message submission and transport protocol. Subclasses of the Transport class implement SMTP and other transport protocols.

---

Obtaining the Transport Object

The Transport object is seldom explicitly created. The getTransport method obtains a Transport object from the Session factory. The JavaMail API provides three versions of the getTransport method:

public class Session {

        /**
         * 1.getTransport(Address address) returns the implementation of the
         * transport class based on the address type. A user-extensible map
         * defines which transport type to use for a particular address. For
         * example, if the address is an InternetAddress, and InternetAddress is
         * mapped to a protocol that supports SMTP then SMTPTransport can be
         * returned.
         */
        public Transport getTransport(Address address);

        /**
         * 2.The client can also call getTransport(“smtp”) to request SMTP, or
         * another transport implementation protocol.
         */
        public Transport getTransport(String protocol);

        /**
         * 3.getTransport() returns the transport specified in the
         * mail.transport.protocol property.
         */
        public Transport getTransport();
    }

Transport Methods

The Transport class provides the connect and protocolConnect methods, which operate similarly to those on the Store class.

A Transport object generates a ConnectionEvent to notify its listeners of a successful or a failed connection. A Transport object can throw an IOException if the connection fails.

Transport implementations should ensure that the message specified is of a known type. If the type is known, then the Transport object sends the message to its specified destinations. If the type is not known, then the Transport object can attempt to reformat the Message object into a suitable version using gatewaying techniques, or it can throw a MessagingException, indicating failure. For example, the SMTP transport implementation recognizes MimeMessages. It invokes the writeTo method on a MimeMessage object to generate a RFC822 format byte stream that is sent to the SMTP host.

The message is sent using the Transport.send static method or the sendMessage instance method. The Transport.send method is a convenience method that instantiates the transports necessary to send the message, depending on the recipients’ addresses, and then passes the message to each transport’s sendMessage method. Alternatively, the client can get the transport that implements a particular protocol itself and send the message using the sendMessage method. This adds the benefit of being able to register as event listeners on the individual transports.

Note that the Address[] argument passed to the send and sendMessage methods do not need to match the addresses provided in the message headers. Although these arguments usually will match, the end-user determines where the messages are actually sent. This is useful for implementing the Bcc: header, and other similar functions.

---

Transport Events

Clients can register as listeners for events generated by transport implementations. (Note that the abstract Transport class doesn’t fire any events, only particular protocol implementations generate events). There are two events generated: ConnectionEvent and TransportEvent.

ConnectionEvent

If the transport connects successfully, it will fire the ConnectionEvent with the type set to OPENED. If the connection times out or is closed, ConnectionEvent with type CLOSED is generated.

TransportEvent

The sendMessage method generates a TransportEvent to its listeners. That event contains information about the method’s success or failure. There are three types of TransportEvent: MESSAGE_DELIVERED, MESSAGE_NOT_DELIVERED, MESSAGE_PARTIALLY_DELIVERED. The event contains three arrays of addresses: validSent[], validUnsent[], and invalid[] that list the valid and invalid addresses for this message and protocol.

Transport Event	Description
MESSAGE_DELIVERED	When the message has been successfully sent to all recipients by this transport. validSent[] contains all the addresses. validUnsent[] and invalid[] are null.
MESSAGE_NOT_DELIVERED	When ValidSent[] is null, the message was not successfully sent to any recipients. validUnsent[] may have addresses that are valid. invalidSent[] may contain invalid addresses.
MESSAGE_PARTIALLY_DELIVERED	Message was successfully sent to some recipients but not to all. ValidSent[] holds addresses of recipients to whom the message was sent. validUnsent[] holds valid addresses but the message wasn’t sent to them. invalid[] holds invalid addresses.

---

Using The Transport Class

The code segment below sends a MimeMessage using a Transport class implementing the SMTP protocol. The client creates two InternetAddress objects that specify the recipients and retrieves a Transport object from the default Session that supports sending messages to Internet addresses. Then the Session object uses a Transport object to send the message.

// Get a session
Session session = Session.getInstance(props, null);

// Create an empty MimeMessage and its part
Message msg = new MimeMessage(session);
//... add headers and message parts as before

// create two destination addresses
Address[] addrs = {new InternetAddress("mickey@disney.com"),
new InternetAddress("goofy@disney.com")};

// get a transport that can handle sending message to
// InternetAddresses. This will probably map to a transport
// that supports SMTP.
Transport trans = session.getTransport(addrs[0]);

// add ourselves as ConnectionEvent and TransportEvent listeners
trans.addConnectionListener(this);
trans.addTransportListener(this);

// connect method determines what host to use from the
// session properties
trans.connect();

// send the message to the addresses we specified above
trans.sendMessage(msg, addrs);

---

REF:JavaMailTM API Design Specification Version 1.5