Java tutorial
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://oss.oracle.com/licenses/CDDL+GPL-1.1 * or LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. */ package javax.mail; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Vector; import javax.mail.event.*; /** * An abstract class that models a message transport. * Subclasses provide actual implementations. <p> * * Note that <code>Transport</code> extends the <code>Service</code> * class, which provides many common methods for naming transports, * connecting to transports, and listening to connection events. * * @author John Mani * @author Max Spivak * @author Bill Shannon * * @see javax.mail.Service * @see javax.mail.event.ConnectionEvent * @see javax.mail.event.TransportEvent */ public abstract class Transport extends Service { /** * Constructor. * * @param session Session object for this Transport. * @param urlname URLName object to be used for this Transport */ public Transport(Session session, URLName urlname) { super(session, urlname); } /** * Send a message. The message will be sent to all recipient * addresses specified in the message (as returned from the * <code>Message</code> method <code>getAllRecipients</code>), * using message transports appropriate to each address. The * <code>send</code> method calls the <code>saveChanges</code> * method on the message before sending it. <p> * * If any of the recipient addresses is detected to be invalid by * the Transport during message submission, a SendFailedException * is thrown. Clients can get more detail about the failure by examining * the exception. Whether or not the message is still sent successfully * to any valid addresses depends on the Transport implementation. See * SendFailedException for more details. Note also that success does * not imply that the message was delivered to the ultimate recipient, * as failures may occur in later stages of delivery. Once a Transport * accepts a message for delivery to a recipient, failures that occur later * should be reported to the user via another mechanism, such as * returning the undeliverable message. <p> * * In typical usage, a SendFailedException reflects an error detected * by the server. The details of the SendFailedException will usually * contain the error message from the server (such as an SMTP error * message). An address may be detected as invalid for a variety of * reasons - the address may not exist, the address may have invalid * syntax, the address may have exceeded its quota, etc. <p> * * Note that <code>send</code> is a static method that creates and * manages its own connection. Any connection associated with any * Transport instance used to invoke this method is ignored and not * used. This method should only be invoked using the form * <code>Transport.send(msg);</code>, and should never be invoked * using an instance variable. * * @param msg the message to send * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException for other failures * @see Message#saveChanges * @see Message#getAllRecipients * @see #send(Message, Address[]) * @see javax.mail.SendFailedException */ public static void send(Message msg) throws MessagingException { msg.saveChanges(); // do this first send0(msg, msg.getAllRecipients(), null, null); } /** * Send the message to the specified addresses, ignoring any * recipients specified in the message itself. The * <code>send</code> method calls the <code>saveChanges</code> * method on the message before sending it. <p> * * @param msg the message to send * @param addresses the addresses to which to send the message * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException for other failures * @see Message#saveChanges * @see #send(Message) * @see javax.mail.SendFailedException */ public static void send(Message msg, Address[] addresses) throws MessagingException { msg.saveChanges(); send0(msg, addresses, null, null); } /** * Send a message. The message will be sent to all recipient * addresses specified in the message (as returned from the * <code>Message</code> method <code>getAllRecipients</code>). * The <code>send</code> method calls the <code>saveChanges</code> * method on the message before sending it. <p> * * Use the specified user name and password to authenticate to * the mail server. * * @param msg the message to send * @param user the user name * @param password this user's password * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException for other failures * @see Message#saveChanges * @see #send(Message) * @see javax.mail.SendFailedException * @since JavaMail 1.5 */ public static void send(Message msg, String user, String password) throws MessagingException { msg.saveChanges(); send0(msg, msg.getAllRecipients(), user, password); } /** * Send the message to the specified addresses, ignoring any * recipients specified in the message itself. The * <code>send</code> method calls the <code>saveChanges</code> * method on the message before sending it. <p> * * Use the specified user name and password to authenticate to * the mail server. * * @param msg the message to send * @param addresses the addresses to which to send the message * @param user the user name * @param password this user's password * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException for other failures * @see Message#saveChanges * @see #send(Message) * @see javax.mail.SendFailedException * @since JavaMail 1.5 */ public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException { msg.saveChanges(); send0(msg, addresses, user, password); } // send, but without the saveChanges private static void send0(Message msg, Address[] addresses, String user, String password) throws MessagingException { if (addresses == null || addresses.length == 0) throw new SendFailedException("No recipient addresses"); /* * protocols is a map containing the addresses * indexed by address type */ Map<String, List<Address>> protocols = new HashMap<>(); // Lists of addresses List<Address> invalid = new ArrayList<>(); List<Address> validSent = new ArrayList<>(); List<Address> validUnsent = new ArrayList<>(); for (int i = 0; i < addresses.length; i++) { // is this address type already in the map? if (protocols.containsKey(addresses[i].getType())) { List<Address> v = protocols.get(addresses[i].getType()); v.add(addresses[i]); } else { // need to add a new protocol List<Address> w = new ArrayList<>(); w.add(addresses[i]); protocols.put(addresses[i].getType(), w); } } int dsize = protocols.size(); if (dsize == 0) throw new SendFailedException("No recipient addresses"); Session s = (msg.session != null) ? msg.session : Session.getDefaultInstance(System.getProperties(), null); Transport transport; /* * Optimize the case of a single protocol. */ if (dsize == 1) { transport = s.getTransport(addresses[0]); try { if (user != null) transport.connect(user, password); else transport.connect(); transport.sendMessage(msg, addresses); } finally { transport.close(); } return; } /* * More than one protocol. Have to do them one at a time * and collect addresses and chain exceptions. */ MessagingException chainedEx = null; boolean sendFailed = false; for (List<Address> v : protocols.values()) { Address[] protaddresses = new Address[v.size()]; v.toArray(protaddresses); // Get a Transport that can handle this address type. if ((transport = s.getTransport(protaddresses[0])) == null) { // Could not find an appropriate Transport .. // Mark these addresses invalid. for (int j = 0; j < protaddresses.length; j++) invalid.add(protaddresses[j]); continue; } try { transport.connect(); transport.sendMessage(msg, protaddresses); } catch (SendFailedException sex) { sendFailed = true; // chain the exception we're catching to any previous ones if (chainedEx == null) chainedEx = sex; else chainedEx.setNextException(sex); // retrieve invalid addresses Address[] a = sex.getInvalidAddresses(); if (a != null) for (int j = 0; j < a.length; j++) invalid.add(a[j]); // retrieve validSent addresses a = sex.getValidSentAddresses(); if (a != null) for (int k = 0; k < a.length; k++) validSent.add(a[k]); // retrieve validUnsent addresses Address[] c = sex.getValidUnsentAddresses(); if (c != null) for (int l = 0; l < c.length; l++) validUnsent.add(c[l]); } catch (MessagingException mex) { sendFailed = true; // chain the exception we're catching to any previous ones if (chainedEx == null) chainedEx = mex; else chainedEx.setNextException(mex); } finally { transport.close(); } } // done with all protocols. throw exception if something failed if (sendFailed || invalid.size() != 0 || validUnsent.size() != 0) { Address[] a = null, b = null, c = null; // copy address lists into arrays if (validSent.size() > 0) { a = new Address[validSent.size()]; validSent.toArray(a); } if (validUnsent.size() > 0) { b = new Address[validUnsent.size()]; validUnsent.toArray(b); } if (invalid.size() > 0) { c = new Address[invalid.size()]; invalid.toArray(c); } throw new SendFailedException("Sending failed", chainedEx, a, b, c); } } /** * Send the Message to the specified list of addresses. An appropriate * TransportEvent indicating the delivery status is delivered to any * TransportListener registered on this Transport. Also, if any of * the addresses is invalid, a SendFailedException is thrown. * Whether or not the message is still sent succesfully to * any valid addresses depends on the Transport implementation. <p> * * Unlike the static <code>send</code> method, the <code>sendMessage</code> * method does <em>not</em> call the <code>saveChanges</code> method on * the message; the caller should do so. * * @param msg The Message to be sent * @param addresses array of addresses to send this message to * @see javax.mail.event.TransportEvent * @exception SendFailedException if the send failed because of * invalid addresses. * @exception MessagingException if the connection is dead or not in the * connected state */ public abstract void sendMessage(Message msg, Address[] addresses) throws MessagingException; // Vector of Transport listeners private volatile Vector<TransportListener> transportListeners = null; /** * Add a listener for Transport events. <p> * * The default implementation provided here adds this listener * to an internal list of TransportListeners. * * @param l the Listener for Transport events * @see javax.mail.event.TransportEvent */ public synchronized void addTransportListener(TransportListener l) { if (transportListeners == null) transportListeners = new Vector<>(); transportListeners.addElement(l); } /** * Remove a listener for Transport events. <p> * * The default implementation provided here removes this listener * from the internal list of TransportListeners. * * @param l the listener * @see #addTransportListener */ public synchronized void removeTransportListener(TransportListener l) { if (transportListeners != null) transportListeners.removeElement(l); } /** * Notify all TransportListeners. Transport implementations are * expected to use this method to broadcast TransportEvents.<p> * * The provided default implementation queues the event into * an internal event queue. An event dispatcher thread dequeues * events from the queue and dispatches them to the registered * TransportListeners. Note that the event dispatching occurs * in a separate thread, thus avoiding potential deadlock problems. * * @param type the TransportEvent type * @param validSent valid addresses to which message was sent * @param validUnsent valid addresses to which message was not sent * @param invalid the invalid addresses * @param msg the message */ protected void notifyTransportListeners(int type, Address[] validSent, Address[] validUnsent, Address[] invalid, Message msg) { if (transportListeners == null) return; TransportEvent e = new TransportEvent(this, type, validSent, validUnsent, invalid, msg); queueEvent(e, transportListeners); } }