/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright 1997-2007 Sun Microsystems, Inc. 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://glassfish.dev.java.net/public/CDDL+GPL.html * or glassfish/bootstrap/legal/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 glassfish/bootstrap/legal/LICENSE.txt. * Sun designates this particular file as subject to the "Classpath" exception * as provided by Sun in the GPL Version 2 section of the License file that * accompanied this code.  If applicable, add the following below the License * Header, with the fields enclosed by brackets [] replaced by your own * identifying information: "Portions Copyrighted [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. *//* * @(#)Session.java	1.76 07/05/04 */package javax.mail;import java.lang.reflect.*;import java.io.*;import java.net.*;import java.security.*;import java.util.Enumeration;import java.util.Hashtable;import java.util.Properties;import java.util.StringTokenizer;import java.util.Vector;import javax.activation.*;import com.sun.mail.util.LineInputStream;/** * The Session class represents a mail session and is not subclassed. * It collects together properties and defaults used by the mail API's. * A single default session can be shared by multiple applications on the * desktop.  Unshared sessions can also be created. <p> * * The Session class provides access to the protocol providers that * implement the <code>Store</code>, <code>Transport</code>, and related * classes.  The protocol providers are configured using the following files: * <ul> *  <li> <code>javamail.providers</code> and * 	<code>javamail.default.providers</code> </li> *  <li> <code>javamail.address.map</code> and * 	<code>javamail.default.address.map</code> </li> * </ul> * <p> * Each <code>javamail.</code><i>X</i> resource file is searched for using * three methods in the following order: * <ol> *  <li> <code>java.home/lib/javamail.</code><i>X</i> </li> *  <li> <code>META-INF/javamail.</code><i>X</i> </li> *  <li> <code>META-INF/javamail.default.</code><i>X</i> </li> * </ol> * <p> * The first method allows the user to include their own version of the * resource file by placing it in the <code>lib</code> directory where the * <code>java.home</code> property points.  The second method allows an * application that uses the JavaMail APIs to include their own resource * files in their application's or jar file's <code>META-INF</code> * directory.  The <code>javamail.default.</code><i>X</i> default files * are part of the JavaMail <code>mail.jar</code> file. <p> * * File location depends upon how the <code>ClassLoader</code> method * <code>getResource</code> is implemented.  Usually, the * <code>getResource</code> method searches through CLASSPATH until it * finds the requested file and then stops.  JDK 1.1 has a limitation that * the number of files of each name that will be found in the CLASSPATH is * limited to one.  However, this only affects method two, above; method * one is loaded from a specific location (if allowed by the * SecurityManager) and method three uses a different name to ensure that * the default resource file is always loaded successfully.  J2SE 1.2 and * later are not limited to one file of a given name. <p> * * The ordering of entries in the resource files matters.  If multiple * entries exist, the first entries take precedence over the later * entries.  For example, the first IMAP provider found will be set as the * default IMAP implementation until explicitly changed by the * application.  The user- or system-supplied resource files augment, they * do not override, the default files included with the JavaMail APIs. * This means that all entries in all files loaded will be available. <p> * * <b><code>javamail.providers</code></b> and * <b><code>javamail.default.providers</code></b><p> * * These resource files specify the stores and transports that are * available on the system, allowing an application to "discover" what * store and transport implementations are available.  The protocol * implementations are listed one per line.  The file format defines four * attributes that describe a protocol implementation.  Each attribute is * an "="-separated name-value pair with the name in lowercase. Each * name-value pair is semi-colon (";") separated.  The following names * are defined. <p> * * <table border=1> * <caption> * Attribute Names in Providers Files * </caption> * <tr> * <th>Name</th><th>Description</th> * </tr> * <tr> * <td>protocol</td> * <td>Name assigned to protocol. * For example, <code>smtp</code> for Transport.</td> * </tr> * <tr> * <td>type</td> * <td>Valid entries are <code>store</code> and <code>transport</code>.</td> * </tr> * <tr> * <td>class</td> * <td>Class name that implements this protocol.</td> * </tr> * <tr> * <td>vendor</td> * <td>Optional string identifying the vendor.</td> * </tr> * <tr> * <td>version</td> * <td>Optional string identifying the version.</td> * </tr> * </table><p> * * Here's an example of <code>META-INF/javamail.default.providers</code> * file contents: * <pre> * protocol=imap; type=store; class=com.sun.mail.imap.IMAPStore; vendor=Sun Microsystems, Inc.; * protocol=smtp; type=transport; class=com.sun.mail.smtp.SMTPTransport; vendor=Sun Microsystems, Inc.; * </pre><p> * * <b><code>javamail.address.map</code></b> and * <b><code>javamail.default.address.map</code></b><p> * * These resource files map transport address types to the transport * protocol.  The <code>getType</code> method of * </code>javax.mail.Address</code> returns the address type.  The * <code>javamail.address.map</code> file maps the transport type to the * protocol.  The file format is a series of name-value pairs.  Each key * name should correspond to an address type that is currently installed * on the system; there should also be an entry for each * <code>javax.mail.Address</code> implementation that is present if it is * to be used.  For example, the * <code>javax.mail.internet.InternetAddress</code> method * <code>getType</code> returns "rfc822". Each referenced protocol should * be installed on the system.  For the case of <code>news</code>, below, * the client should install a Transport provider supporting the nntp * protocol. <p> * * Here are the typical contents of a <code>javamail.address.map</code> file: * <pre> * rfc822=smtp * news=nntp * </pre> * * @version 1.76, 07/05/04 * @author John Mani * @author Bill Shannon * @author Max Spivak */public final class Session {    private final Properties props;    private final Authenticator authenticator;    private final Hashtable authTable = new Hashtable();    private boolean debug = false;    private PrintStream out;			// debug output stream    private final Vector providers = new Vector();    private final Hashtable providersByProtocol = new Hashtable();    private final Hashtable providersByClassName = new Hashtable();    private final Properties addressMap = new Properties();						// maps type to protocol    // The default session.    private static Session defaultSession = null;    // Constructor is not public    private Session(Properties props, Authenticator authenticator) {	this.props = props;	this.authenticator = authenticator;	if (Boolean.valueOf(props.getProperty("mail.debug")).booleanValue())	    debug = true;	if (debug)	    pr("DEBUG: JavaMail version " + Version.version);	// get the Class associated with the Authenticator	Class cl;	if (authenticator != null)	    cl = authenticator.getClass();	else	    cl = this.getClass();	// load the resources	loadProviders(cl);	loadAddressMap(cl);    }    /**     * Get a new Session object.     *     * @param	props	Properties object that hold relevant properties.<br>     *                  It is expected that the client supplies values     *                  for the properties listed in Appendix A of the     *                  JavaMail spec (particularly  mail.store.protocol,      *                  mail.transport.protocol, mail.host, mail.user,      *                  and mail.from) as the defaults are unlikely to      *                  work in all cases.     * @param	authenticator Authenticator object used to call back to     *			the application when a user name and password is     *			needed.     * @return		a new Session object     * @see	javax.mail.Authenticator     */    public static Session getInstance(Properties props,					Authenticator authenticator) {	return new Session(props, authenticator);    }    /**     * Get a new Session object.     *     * @param	props	Properties object that hold relevant properties.<br>     *                  It is expected that the client supplies values     *                  for the properties listed in Appendix A of the     *                  JavaMail spec (particularly  mail.store.protocol,      *                  mail.transport.protocol, mail.host, mail.user,      *                  and mail.from) as the defaults are unlikely to      *                  work in all cases.     * @return		a new Session object     * @since		JavaMail 1.2     */    public static Session getInstance(Properties props) {	return new Session(props, null);    }    /**     * Get the default Session object. If a default has not yet been     * setup, a new Session object is created and installed as the      * default. <p>     *     * Since the default session is potentially available to all     * code executing in the same Java virtual machine, and the session     * can contain security sensitive information such as user names     * and passwords, access to the default session is restricted.     * The Authenticator object, which must be created by the caller,     * is used indirectly to check access permission.  The Authenticator     * object passed in when the session is created is compared with     * the Authenticator object passed in to subsequent requests to     * get the default session.  If both objects are the same, or are     * from the same ClassLoader, the request is allowed.  Otherwise,     * it is denied.  <p>     *     * Note that if the Authenticator object used to create the session     * is null, anyone can get the default session by passing in null.  <p>     *     * Note also that the Properties object is used only the first time     * this method is called, when a new Session object is created.     * Subsequent calls return the Session object that was created by the     * first call, and ignore the passed Properties object.  Use the     * <code>getInstance</code> method to get a new Session object every     * time the method is called. <p>     *     * In JDK 1.2, additional security Permission objects may be used to     * control access to the default session.     *     * @param	props	Properties object. Used only if a new Session     *			object is created.<br>     *                  It is expected that the client supplies values     *                  for the properties listed in Appendix A of the     *                  JavaMail spec (particularly  mail.store.protocol,      *                  mail.transport.protocol, mail.host, mail.user,      *                  and mail.from) as the defaults are unlikely to      *                  work in all cases.     * @param	authenticator Authenticator object.  Used only if a     *			new Session object is created.  Otherwise,      *			it must match the Authenticator used to create     *			the Session.     * @return		the default Session object     */    public static synchronized Session getDefaultInstance(Properties props,					Authenticator authenticator) {	if (defaultSession == null)	    defaultSession = new Session(props, authenticator);	else {	    // have to check whether caller is allowed to see default session	    if (defaultSession.authenticator == authenticator)		;	// either same object or both null, either way OK	    else if (defaultSession.authenticator != null &&		    authenticator != null &&		    defaultSession.authenticator.getClass().getClassLoader() ==			authenticator.getClass().getClassLoader())		;	// both objects came from the same class loader, OK	    else		// anything else is not allowed		throw new SecurityException("Access to default session denied");	}	return defaultSession;    }    /**     * Get the default Session object. If a default has not yet been     * setup, a new Session object is created and installed as the      * default. <p>     *     * Note that a default session created with no Authenticator is     * available to all code executing in the same Java virtual     * machine, and the session can contain security sensitive     * information such as user names and passwords.     *     * @param	props	Properties object. Used only if a new Session     *			object is created.<br>     *                  It is expected that the client supplies values     *                  for the properties listed in Appendix A of the     *                  JavaMail spec (particularly  mail.store.protocol,      *                  mail.transport.protocol, mail.host, mail.user,      *                  and mail.from) as the defaults are unlikely to      *                  work in all cases.     * @return		the default Session object     * @since		JavaMail 1.2     */    public static Session getDefaultInstance(Properties props) {        return getDefaultInstance(props, null);    }    /**     * Set the debug setting for this Session.     * <p>     * Since the debug setting can be turned on only after the Session     * has been created, to turn on debugging in the Session     * constructor, set the property <code>mail.debug</code> in the     * Properties object passed in to the constructor to true.  The     * value of the <code>mail.debug</code> property is used to     * initialize the per-Session debugging flag.  Subsequent calls to     * the <code>setDebug</code> method manipulate the per-Session     * debugging flag and have no affect on the <code>mail.debug</code>     * property.     *     * @param debug	Debug setting     */    public synchronized void setDebug(boolean debug) {	this.debug = debug;	if (debug)	    pr("DEBUG: setDebug: JavaMail version " + Version.version);    }    /**     * Get the debug setting for this Session.     *     * @return current debug setting     */    public synchronized boolean getDebug() {	return debug;    }    /**     * Set the stream to be used for debugging output for this session.     * If <code>out</code> is null, <code>System.out</code> will be used.     * Note that debugging output that occurs before any session is created,     * as a result of setting the <code>mail.debug</code> system property,     * will always be sent to <code>System.out</code>.     *     * @param	out	the PrintStream to use for debugging output     * @since		JavaMail 1.3     */    public synchronized void setDebugOut(PrintStream out) {	this.out = out;    }    /**     * Returns the stream to be used for debugging output.  If no stream     * has been set, <code>System.out</code> is returned.     *     * @return		the PrintStream to use for debugging output     * @since		JavaMail 1.3     */    public synchronized PrintStream getDebugOut() {	if (out == null)	    return System.out;	else	    return out;    }    /**     * This method returns an array of all the implementations installed      * via the javamail.[default.]providers files that can     * be loaded using the ClassLoader available to this application.     *     * @return Array of configured providers     */    public synchronized Provider[] getProviders() {	Provider[] _providers = new Provider[providers.size()];	providers.copyInto(_providers);	return _providers;    }    /**     * Returns the default Provider for the protocol     * specified. Checks mail.&lt;protocol&gt;.class property     * first and if it exists, returns the Provider     * associated with this implementation. If it doesn't exist,