/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ package javax.mail; import java.io.BufferedReader; import java.io.File; import java.io.FileInputStream; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.PrintStream; import java.lang.reflect.Constructor; import java.lang.reflect.InvocationTargetException; import java.net.InetAddress; import java.net.URL; import java.util.ArrayList; import java.util.Collection; import java.util.Enumeration; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Properties; import java.util.StringTokenizer; import java.util.WeakHashMap; import org.apache.geronimo.osgi.locator.ProviderLocator; import org.apache.geronimo.mail.MailProviderRegistry; /** * OK, so we have a final class in the API with a heck of a lot of implementation required... * let's try and figure out what it is meant to do. * <p/> * It is supposed to collect together properties and defaults so that they can be * shared by multiple applications on a desktop; with process isolation and no * real concept of shared memory, this seems challenging. These properties and * defaults rely on system properties, making management in a app server harder, * and on resources loaded from "mail.jar" which may lead to skew between * differnet independent implementations of this API. * * @version $Rev: 924365 $ $Date: 2010-03-17 12:52:03 -0400 (Wed, 17 Mar 2010) $ */ public final class Session { private static final Class[] PARAM_TYPES = {Session.class, URLName.class}; private static final WeakHashMap addressMapsByClassLoader = new WeakHashMap(); private static Session DEFAULT_SESSION; private Map passwordAuthentications = new HashMap(); private final Properties properties; private final Authenticator authenticator; private boolean debug; private PrintStream debugOut = System.out; private static final WeakHashMap providersByClassLoader = new WeakHashMap(); /** * No public constrcutor allowed. */ private Session(Properties properties, Authenticator authenticator) { this.properties = properties; this.authenticator = authenticator; debug = Boolean.valueOf(properties.getProperty("mail.debug")).booleanValue(); } /** * Create a new session initialized with the supplied properties which uses the supplied authenticator. * Clients should ensure the properties listed in Appendix A of the JavaMail specification are * set as the defaults are unlikey to work in most scenarios; particular attention should be given * to: * <ul> * <li>mail.store.protocol</li> * <li>mail.transport.protocol</li> * <li>mail.host</li> * <li>mail.user</li> * <li>mail.from</li> * </ul> * * @param properties the session properties * @param authenticator an authenticator for callbacks to the user * @return a new session */ public static Session getInstance(Properties properties, Authenticator authenticator) { // if we have a properties bundle, we need a copy of the provided one if (properties != null) { properties = (Properties)properties.clone(); } return new Session(properties, authenticator); } /** * Create a new session initialized with the supplied properties with no authenticator. * * @param properties the session properties * @return a new session * @see #getInstance(java.util.Properties, Authenticator) */ public static Session getInstance(Properties properties) { return getInstance(properties, null); } /** * Get the "default" instance assuming no authenticator is required. * * @param properties the session properties * @return if "default" session * @throws SecurityException if the does not have permission to access the default session */ public synchronized static Session getDefaultInstance(Properties properties) { return getDefaultInstance(properties, null); } /** * Get the "default" session. * If there is not current "default", a new Session is created and installed as the default. * * @param properties * @param authenticator * @return if "default" session * @throws SecurityException if the does not have permission to access the default session */ public synchronized static Session getDefaultInstance(Properties properties, Authenticator authenticator) { if (DEFAULT_SESSION == null) { DEFAULT_SESSION = getInstance(properties, authenticator); } else { if (authenticator != DEFAULT_SESSION.authenticator) { if (authenticator == null || DEFAULT_SESSION.authenticator == null || authenticator.getClass().getClassLoader() != DEFAULT_SESSION.authenticator.getClass().getClassLoader()) { throw new SecurityException(); } } // todo we should check with the SecurityManager here as well } return DEFAULT_SESSION; } /** * Enable debugging for this session. * Debugging can also be enabled by setting the "mail.debug" property to true when * the session is being created. * * @param debug the debug setting */ public void setDebug(boolean debug) { this.debug = debug; } /** * Get the debug setting for this session. * * @return the debug setting */ public boolean getDebug() { return debug; } /** * Set the output stream where debug information should be sent. * If set to null, System.out will be used. * * @param out the stream to write debug information to */ public void setDebugOut(PrintStream out) { debugOut = out == null ? System.out : out; } /** * Return the debug output stream. * * @return the debug output stream */ public PrintStream getDebugOut() { return debugOut; } /** * Return the list of providers available to this application. * This method searches for providers that are defined in the javamail.providers * and javamail.default.providers resources available through the current context * classloader, or if that is not available, the classloader that loaded this class. * <p/> * As searching for providers is potentially expensive, this implementation maintains * a WeakHashMap of providers indexed by ClassLoader. * * @return an array of providers */ public Provider[] getProviders() { ProviderInfo info = getProviderInfo(); return (Provider[]) info.all.toArray(new Provider[info.all.size()]); } /** * Return the provider for a specific protocol. * This implementation initially looks in the Session properties for an property with the name * "mail.<protocol>.class"; if found it attempts to create an instance of the class named in that * property throwing a NoSuchProviderException if the class cannot be loaded. * If this property is not found, it searches the providers returned by {@link #getProviders()} * for a entry for the specified protocol. * * @param protocol the protocol to get a provider for * @return a provider for that protocol * @throws NoSuchProviderException */ public Provider getProvider(String protocol) throws NoSuchProviderException { ProviderInfo info = getProviderInfo(); Provider provider = null; String providerName = properties.getProperty("mail." + protocol + ".class"); if (providerName != null) { provider = (Provider) info.byClassName.get(providerName); if (debug) { writeDebug("DEBUG: new provider loaded: " + provider.toString()); } } // if not able to locate this by class name, just grab a registered protocol. if (provider == null) { provider = (Provider) info.byProtocol.get(protocol); } if (provider == null) { throw new NoSuchProviderException("Unable to locate provider for protocol: " + protocol); } if (debug) { writeDebug("DEBUG: getProvider() returning provider " + provider.toString()); } return provider; } /** * Make the supplied Provider the default for its protocol. * * @param provider the new default Provider * @throws NoSuchProviderException */ public void setProvider(Provider provider) throws NoSuchProviderException { ProviderInfo info = getProviderInfo(); info.byProtocol.put(provider.getProtocol(), provider); } /** * Return a Store for the default protocol defined by the mail.store.protocol property. * * @return the store for the default protocol * @throws NoSuchProviderException */ public Store getStore() throws NoSuchProviderException { String protocol = properties.getProperty("mail.store.protocol"); if (protocol == null) { throw new NoSuchProviderException("mail.store.protocol property is not set"); } return getStore(protocol); } /** * Return a Store for the specified protocol. * * @param protocol the protocol to get a Store for * @return a Store * @throws NoSuchProviderException if no provider is defined for the specified protocol */ public Store getStore(String protocol) throws NoSuchProviderException { Provider provider = getProvider(protocol); return getStore(provider); } /** * Return a Store for the protocol specified in the given URL * * @param url the URL of the Store * @return a Store * @throws NoSuchProviderException if no provider is defined for the specified protocol */ public Store getStore(URLName url) throws NoSuchProviderException { return (Store) getService(getProvider(url.getProtocol()), url); } /** * Return the Store specified by the given provider. * * @param provider the provider to create from * @return a Store * @throws NoSuchProviderException if there was a problem creating the Store */ public Store getStore(Provider provider) throws NoSuchProviderException { if (Provider.Type.STORE != provider.getType()) { throw new NoSuchProviderException("Not a Store Provider: " + provider); } return (Store) getService(provider, null); } /** * Return a closed folder for the supplied URLName, or null if it cannot be obtained. * <p/> * The scheme portion of the URL is used to locate the Provider and create the Store; * the returned Store is then used to obtain the folder. * * @param name the location of the folder * @return the requested folder, or null if it is unavailable * @throws NoSuchProviderException if there is no provider * @throws MessagingException if there was a problem accessing the Store */ public Folder getFolder(URLName name) throws MessagingException { Store store = getStore(name); return store.getFolder(name); } /** * Return a Transport for the default protocol specified by the * <code>mail.transport.protocol</code> property. * * @return a Transport * @throws NoSuchProviderException */ public Transport getTransport() throws NoSuchProviderException { String protocol = properties.getProperty("mail.transport.protocol"); if (protocol == null) { throw new NoSuchProviderException("mail.transport.protocol property is not set"); } return getTransport(protocol); } /** * Return a Transport for the specified protocol. * * @param protocol the protocol to use * @return a Transport * @throws NoSuchProviderException */ public Transport getTransport(String protocol) throws NoSuchProviderException { Provider provider = getProvider(protocol); return getTransport(provider); } /** * Return a transport for the protocol specified in the URL. * * @param name the URL whose scheme specifies the protocol * @return a Transport * @throws NoSuchProviderException */ public Transport getTransport(URLName name) throws NoSuchProviderException { return (Transport) getService(getProvider(name.getProtocol()), name); } /** * Return a transport for the protocol associated with the type of this address. * * @param address the address we are trying to deliver to * @return a Transport * @throws NoSuchProviderException */ public Transport getTransport(Address address) throws NoSuchProviderException { String type = address.getType(); // load the address map from the resource files. Map addressMap = getAddressMap(); String protocolName = (String)addressMap.get(type); if (protocolName == null) { throw new NoSuchProviderException("No provider for address type " + type); } return getTransport(protocolName); } /** * Return the Transport specified by a Provider * * @param provider the defining Provider * @return a Transport * @throws NoSuchProviderException */ public Transport getTransport(Provider provider) throws NoSuchProviderException { return (Transport) getService(provider, null); } /** * Set the password authentication associated with a URL. * * @param name the url * @param authenticator the authenticator */ public void setPasswordAuthentication(URLName name, PasswordAuthentication authenticator) { if (authenticator == null) { passwordAuthentications.remove(name); } else { passwordAuthentications.put(name, authenticator); } } /** * Get the password authentication associated with a URL * * @param name the URL * @return any authenticator for that url, or null if none */ public PasswordAuthentication getPasswordAuthentication(URLName name) { return (PasswordAuthentication) passwordAuthentications.get(name); } /** * Call back to the application supplied authenticator to get the needed username add password. * * @param host the host we are trying to connect to, may be null * @param port the port on that host * @param protocol the protocol trying to be used * @param prompt a String to show as part of the prompt, may be null * @param defaultUserName the default username, may be null * @return the authentication information collected by the authenticator; may be null */ public PasswordAuthentication requestPasswordAuthentication(InetAddress host, int port, String protocol, String prompt, String defaultUserName) { if (authenticator == null) { return null; } return authenticator.authenticate(host, port, protocol, prompt, defaultUserName); } /** * Return the properties object for this Session; this is a live collection. * * @return the properties for the Session */ public Properties getProperties() { return properties; } /** * Return the specified property. * * @param property the property to get * @return its value, or null if not present */ public String getProperty(String property) { return getProperties().getProperty(property); } /** * Add a provider to the Session managed provider list. * * @param provider The new provider to add. */ public synchronized void addProvider(Provider provider) { ProviderInfo info = getProviderInfo(); info.addProvider(provider); } /** * Add a mapping between an address type and a protocol used * to process that address type. * * @param addressType * The address type identifier. * @param protocol The protocol name mapping. */ public void setProtocolForAddress(String addressType, String protocol) { Map addressMap = getAddressMap(); // no protocol specified is a removal if (protocol == null) { addressMap.remove(addressType); } else { addressMap.put(addressType, protocol); } } private Service getService(Provider provider, URLName name) throws NoSuchProviderException { try { if (name == null) { name = new URLName(provider.getProtocol(), null, -1, null, null, null); } ClassLoader cl = getClassLoader(); Class clazz = null; try { clazz = ProviderLocator.loadClass(provider.getClassName(), this.getClass(), cl); } catch (ClassNotFoundException e) { throw (NoSuchProviderException) new NoSuchProviderException("Unable to load class for provider: " + provider).initCause(e); } Constructor ctr = clazz.getConstructor(PARAM_TYPES); return(Service) ctr.newInstance(new Object[]{this, name}); } catch (NoSuchMethodException e) { throw (NoSuchProviderException) new NoSuchProviderException("Provider class does not have a constructor(Session, URLName): " + provider).initCause(e); } catch (InstantiationException e) { throw (NoSuchProviderException) new NoSuchProviderException("Unable to instantiate provider class: " + provider).initCause(e); } catch (IllegalAccessException e) { throw (NoSuchProviderException) new NoSuchProviderException("Unable to instantiate provider class: " + provider).initCause(e); } catch (InvocationTargetException e) { throw (NoSuchProviderException) new NoSuchProviderException("Exception from constructor of provider class: " + provider).initCause(e.getCause()); } } private ProviderInfo getProviderInfo() { ClassLoader cl = getClassLoader(); synchronized (providersByClassLoader) { ProviderInfo info = (ProviderInfo) providersByClassLoader.get(cl); if (info == null) { info = loadProviders(cl); } return info; } } private Map getAddressMap() { ClassLoader cl = getClassLoader(); Map addressMap = (Map)addressMapsByClassLoader.get(cl); if (addressMap == null) { addressMap = loadAddressMap(cl); } return addressMap; } /** * Resolve a class loader used to resolve context resources. The * class loader used is either a current thread context class * loader (if set), the class loader used to load an authenticator * we've been initialized with, or the class loader used to load * this class instance (which may be a subclass of Session). * * @return The class loader used to load resources. */ private ClassLoader getClassLoader() { ClassLoader cl = Thread.currentThread().getContextClassLoader(); if (cl == null) { if (authenticator != null) { cl = authenticator.getClass().getClassLoader(); } else { cl = this.getClass().getClassLoader(); } } return cl; } private ProviderInfo loadProviders(ClassLoader cl) { // we create a merged map from reading all of the potential address map entries. The locations // searched are: // 1. java.home/lib/javamail.address.map // 2. META-INF/javamail.address.map // 3. META-INF/javamail.default.address.map // ProviderInfo info = new ProviderInfo(); // NOTE: Unlike the addressMap, we process these in the defined order. The loading routine // will not overwrite entries if they already exist in the map. try { File file = new File(System.getProperty("java.home"), "lib/javamail.providers"); InputStream is = new FileInputStream(file); try { loadProviders(info, is); if (debug) { writeDebug("Loaded lib/javamail.providers from " + file.toString()); } } finally{ is.close(); } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } try { Enumeration e = cl.getResources("META-INF/javamail.providers"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); if (debug) { writeDebug("Loading META-INF/javamail.providers from " + url.toString()); } InputStream is = url.openStream(); try { loadProviders(info, is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } // we could be running in an OSGi environment, so there might be some globally defined // providers try { Collection<URL> l = MailProviderRegistry.getProviders(); for (URL url : l) { if (debug) { writeDebug("Loading META-INF/javamail.providers from " + url.toString()); } InputStream is = url.openStream(); try { loadProviders(info, is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } try { Enumeration e = cl.getResources("META-INF/javamail.default.providers"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); if (debug) { writeDebug("Loading javamail.default.providers from " + url.toString()); } InputStream is = url.openStream(); try { loadProviders(info, is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } // we could be running in an OSGi environment, so there might be some globally defined // providers try { Collection<URL> l = MailProviderRegistry.getDefaultProviders(); for (URL url : l) { if (debug) { writeDebug("Loading META-INF/javamail.providers from " + url.toString()); } InputStream is = url.openStream(); try { loadProviders(info, is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } // make sure this is added to the global map. providersByClassLoader.put(cl, info); return info; } private void loadProviders(ProviderInfo info, InputStream is) throws IOException { BufferedReader reader = new BufferedReader(new InputStreamReader(is)); String line; while ((line = reader.readLine()) != null) { // Lines beginning with "#" are just comments. if (line.startsWith("#")) { continue; } StringTokenizer tok = new StringTokenizer(line, ";"); String protocol = null; Provider.Type type = null; String className = null; String vendor = null; String version = null; while (tok.hasMoreTokens()) { String property = tok.nextToken(); int index = property.indexOf('='); if (index == -1) { continue; } String key = property.substring(0, index).trim().toLowerCase(); String value = property.substring(index+1).trim(); if (protocol == null && "protocol".equals(key)) { protocol = value; } else if (type == null && "type".equals(key)) { if ("store".equals(value)) { type = Provider.Type.STORE; } else if ("transport".equals(value)) { type = Provider.Type.TRANSPORT; } } else if (className == null && "class".equals(key)) { className = value; } else if ("vendor".equals(key)) { vendor = value; } else if ("version".equals(key)) { version = value; } } if (protocol == null || type == null || className == null) { //todo should we log a warning? continue; } if (debug) { writeDebug("DEBUG: loading new provider protocol=" + protocol + ", className=" + className + ", vendor=" + vendor + ", version=" + version); } Provider provider = new Provider(type, protocol, className, vendor, version); // add to the info list. info.addProvider(provider); } } /** * Load up an address map associated with a using class loader * instance. * * @param cl The class loader used to resolve the address map. * * @return A map containing the entries associated with this classloader * instance. */ private static Map loadAddressMap(ClassLoader cl) { // we create a merged map from reading all of the potential address map entries. The locations // searched are: // 1. java.home/lib/javamail.address.map // 2. META-INF/javamail.address.map // 3. META-INF/javamail.default.address.map // // if all of the above searches fail, we just set up some "default" defaults. // the format of the address.map file is defined as a property file. We can cheat and // just use Properties.load() to read in the files. Properties addressMap = new Properties(); // add this to the tracking map. addressMapsByClassLoader.put(cl, addressMap); // NOTE: We are reading these resources in reverse order of what's cited above. This allows // user defined entries to overwrite default entries if there are similarly named items. try { Enumeration e = cl.getResources("META-INF/javamail.default.address.map"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); InputStream is = url.openStream(); try { // load as a property file addressMap.load(is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } try { Enumeration e = cl.getResources("META-INF/javamail.address.map"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); InputStream is = url.openStream(); try { // load as a property file addressMap.load(is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } try { File file = new File(System.getProperty("java.home"), "lib/javamail.address.map"); InputStream is = new FileInputStream(file); try { // load as a property file addressMap.load(is); } finally{ is.close(); } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } try { Enumeration e = cl.getResources("META-INF/javamail.address.map"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); InputStream is = url.openStream(); try { // load as a property file addressMap.load(is); } finally{ is.close(); } } } catch (SecurityException e) { // ignore } catch (IOException e) { // ignore } // if unable to load anything, at least create the MimeMessage-smtp protocol mapping. if (addressMap.isEmpty()) { addressMap.put("rfc822", "smtp"); } return addressMap; } /** * Private convenience routine for debug output. * * @param msg The message to write out to the debug stream. */ private void writeDebug(String msg) { debugOut.println(msg); } private static class ProviderInfo { private final Map byClassName = new HashMap(); private final Map byProtocol = new HashMap(); private final List all = new ArrayList(); public void addProvider(Provider provider) { String className = provider.getClassName(); if (!byClassName.containsKey(className)) { byClassName.put(className, provider); } String protocol = provider.getProtocol(); if (!byProtocol.containsKey(protocol)) { byProtocol.put(protocol, provider); } all.add(provider); } } }