javax.mail
Class Session

java.lang.Object
  javax.mail.Session

public final class Session
extends Object

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.

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: 702537 $ $Date: 2008-10-07 12:39:34 -0400 (Tue, 07 Oct 2008) $

Method Summary

void	addProvider(Provider provider) Add a provider to the Session managed provider list.
boolean	getDebug() Get the debug setting for this session.
PrintStream	getDebugOut() Return the debug output stream.
static Session	getDefaultInstance(Properties properties) Get the "default" instance assuming no authenticator is required.
static Session	getDefaultInstance(Properties properties, Authenticator authenticator) Get the "default" session.
Folder	getFolder(URLName name) Return a closed folder for the supplied URLName, or null if it cannot be obtained.
static Session	getInstance(Properties properties) Create a new session initialized with the supplied properties with no authenticator.
static Session	getInstance(Properties properties, Authenticator authenticator) Create a new session initialized with the supplied properties which uses the supplied authenticator.
PasswordAuthentication	getPasswordAuthentication(URLName name) Get the password authentication associated with a URL
Properties	getProperties() Return the properties object for this Session; this is a live collection.
String	getProperty(String property) Return the specified property.
Provider	getProvider(String protocol) Return the provider for a specific protocol.
Provider[]	getProviders() Return the list of providers available to this application.
Store	getStore() Return a Store for the default protocol defined by the mail.store.protocol property.
Store	getStore(Provider provider) Return the Store specified by the given provider.
Store	getStore(String protocol) Return a Store for the specified protocol.
Store	getStore(URLName url) Return a Store for the protocol specified in the given URL
Transport	getTransport() Return a Transport for the default protocol specified by the mail.transport.protocol property.
Transport	getTransport(Address address) Return a transport for the protocol associated with the type of this address.
Transport	getTransport(Provider provider) Return the Transport specified by a Provider
Transport	getTransport(String protocol) Return a Transport for the specified protocol.
Transport	getTransport(URLName name) Return a transport for the protocol specified in the URL.
PasswordAuthentication	requestPasswordAuthentication(InetAddress host, int port, String protocol, String prompt, String defaultUserName) Call back to the application supplied authenticator to get the needed username add password.
void	setDebug(boolean debug) Enable debugging for this session.
void	setDebugOut(PrintStream out) Set the output stream where debug information should be sent.
void	setPasswordAuthentication(URLName name, PasswordAuthentication authenticator) Set the password authentication associated with a URL.
void	setProtocolForAddress(String addressType, String protocol) Add a mapping between an address type and a protocol used to process that address type.
void	setProvider(Provider provider) Make the supplied Provider the default for its protocol.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static Session getInstance(Properties properties,
                                  Authenticator authenticator)

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:

• mail.store.protocol
• mail.transport.protocol
• mail.host
• mail.user
• mail.from

Parameters:

properties - the session properties

authenticator - an authenticator for callbacks to the user

Returns:

a new session

getInstance

public static Session getInstance(Properties properties)

Create a new session initialized with the supplied properties with no authenticator.

Parameters:

properties - the session properties

Returns:

a new session

See Also:

getInstance(java.util.Properties, Authenticator)

getDefaultInstance

public static Session getDefaultInstance(Properties properties)

Get the "default" instance assuming no authenticator is required.

Parameters:

properties - the session properties

Returns:

if "default" session

Throws:

SecurityException - if the does not have permission to access the default session

getDefaultInstance

public static Session getDefaultInstance(Properties properties,
                                         Authenticator authenticator)

Get the "default" session. If there is not current "default", a new Session is created and installed as the default.

Parameters:

properties -

authenticator -

Returns:

if "default" session

Throws:

SecurityException - if the does not have permission to access the default session

setDebug

public void setDebug(boolean debug)

Enable debugging for this session. Debugging can also be enabled by setting the "mail.debug" property to true when the session is being created.

Parameters:

debug - the debug setting

getDebug

public boolean getDebug()

Get the debug setting for this session.

Returns:

the debug setting

setDebugOut

public void setDebugOut(PrintStream out)

Set the output stream where debug information should be sent. If set to null, System.out will be used.

Parameters:

out - the stream to write debug information to

getDebugOut

public PrintStream getDebugOut()

Return the debug output stream.

Returns:

the debug output stream

getProviders

public Provider[] getProviders()

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.

As searching for providers is potentially expensive, this implementation maintains a WeakHashMap of providers indexed by ClassLoader.

Returns:

an array of providers

getProvider

public Provider getProvider(String protocol)
                     throws NoSuchProviderException

Return the provider for a specific protocol. This implementation initially looks in the Session properties for an property with the name "mail..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 getProviders() for a entry for the specified protocol.

Parameters:

protocol - the protocol to get a provider for

Returns:

a provider for that protocol

Throws:

NoSuchProviderException

setProvider

public void setProvider(Provider provider)
                 throws NoSuchProviderException

Make the supplied Provider the default for its protocol.

Parameters:

provider - the new default Provider

Throws:

NoSuchProviderException

getStore

public Store getStore()
               throws NoSuchProviderException

Return a Store for the default protocol defined by the mail.store.protocol property.

Returns:

the store for the default protocol

Throws:

NoSuchProviderException

getStore

public Store getStore(String protocol)
               throws NoSuchProviderException

Return a Store for the specified protocol.

Parameters:

protocol - the protocol to get a Store for

Returns:

a Store

Throws:

NoSuchProviderException - if no provider is defined for the specified protocol

getStore

public Store getStore(URLName url)
               throws NoSuchProviderException

Return a Store for the protocol specified in the given URL

Parameters:

url - the URL of the Store

Returns:

a Store

Throws:

NoSuchProviderException - if no provider is defined for the specified protocol

getStore

public Store getStore(Provider provider)
               throws NoSuchProviderException

Return the Store specified by the given provider.

Parameters:

provider - the provider to create from

Returns:

a Store

Throws:

NoSuchProviderException - if there was a problem creating the Store

getFolder

public Folder getFolder(URLName name)
                 throws MessagingException

Return a closed folder for the supplied URLName, or null if it cannot be obtained.

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.

Parameters:

name - the location of the folder

Returns:

the requested folder, or null if it is unavailable

Throws:

NoSuchProviderException - if there is no provider

MessagingException - if there was a problem accessing the Store

getTransport

public Transport getTransport()
                       throws NoSuchProviderException

Return a Transport for the default protocol specified by the mail.transport.protocol property.

Returns:

a Transport

Throws:

NoSuchProviderException

getTransport

public Transport getTransport(String protocol)
                       throws NoSuchProviderException

Return a Transport for the specified protocol.

Parameters:

protocol - the protocol to use

Returns:

a Transport

Throws:

NoSuchProviderException

getTransport

public Transport getTransport(URLName name)
                       throws NoSuchProviderException

Return a transport for the protocol specified in the URL.

Parameters:

name - the URL whose scheme specifies the protocol

Returns:

a Transport

Throws:

NoSuchProviderException

getTransport

public Transport getTransport(Address address)
                       throws NoSuchProviderException

Return a transport for the protocol associated with the type of this address.

Parameters:

address - the address we are trying to deliver to

Returns:

a Transport

Throws:

NoSuchProviderException

getTransport

public Transport getTransport(Provider provider)
                       throws NoSuchProviderException

Return the Transport specified by a Provider

Parameters:

provider - the defining Provider

Returns:

a Transport

Throws:

NoSuchProviderException

setPasswordAuthentication

public void setPasswordAuthentication(URLName name,
                                      PasswordAuthentication authenticator)

Set the password authentication associated with a URL.

Parameters:

name - the url

authenticator - the authenticator

getPasswordAuthentication

public PasswordAuthentication getPasswordAuthentication(URLName name)

Get the password authentication associated with a URL

Parameters:

name - the URL

Returns:

any authenticator for that url, or null if none

requestPasswordAuthentication

public PasswordAuthentication requestPasswordAuthentication(InetAddress host,
                                                            int port,
                                                            String protocol,
                                                            String prompt,
                                                            String defaultUserName)

Call back to the application supplied authenticator to get the needed username add password.

Parameters:

host - the host we are trying to connect to, may be null

port - the port on that host

protocol - the protocol trying to be used

prompt - a String to show as part of the prompt, may be null

defaultUserName - the default username, may be null

Returns:

the authentication information collected by the authenticator; may be null

getProperties

public Properties getProperties()

Return the properties object for this Session; this is a live collection.

Returns:

the properties for the Session

getProperty

public String getProperty(String property)

Return the specified property.

Parameters:

property - the property to get

Returns:

its value, or null if not present

addProvider

public void addProvider(Provider provider)

Add a provider to the Session managed provider list.

Parameters:

provider - The new provider to add.

setProtocolForAddress

public void setProtocolForAddress(String addressType,
                                  String protocol)

Add a mapping between an address type and a protocol used to process that address type.

Parameters:

addressType - The address type identifier.

protocol - The protocol name mapping.