javax.mail

Class Session


public final class Session
extends java.lang.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.

Method Summary

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(String protocol)
Return a Store for the specified protocol.
Store
getStore(Provider provider)
Return the Store specified by the given provider.
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(String protocol)
Return a Transport for the specified protocol.
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(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
setProvider(Provider provider)
Make the supplied Provider the default for its protocol.

Method Details

getDebug

public boolean getDebug()
Get the debug setting for this session.
Returns:
the debug setting

getDebugOut

public PrintStream getDebugOut()
Return the debug output stream.
Returns:
the debug output stream

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

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

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:
MessagingException - if there was a problem accessing the Store

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)

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

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

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

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

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

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

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(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

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

getTransport

public Transport getTransport()
            throws NoSuchProviderException
Return a Transport for the default protocol specified by the mail.transport.protocol property.
Returns:
a Transport

getTransport

public Transport getTransport(String protocol)
            throws NoSuchProviderException
Return a Transport for the specified protocol.
Parameters:
protocol - the protocol to use
Returns:
a Transport

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

getTransport

public Transport getTransport(Provider provider)
            throws NoSuchProviderException
Return the Transport specified by a Provider
Parameters:
provider - the defining Provider
Returns:
a Transport

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

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

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

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

setPasswordAuthentication

public void setPasswordAuthentication(URLName name,
                                      PasswordAuthentication authenticator)
Set the password authentication associated with a URL.
Parameters:
name - the url
authenticator - the authenticator

setProvider

public void setProvider(Provider provider)
            throws NoSuchProviderException
Make the supplied Provider the default for its protocol.
Parameters:
provider - the new default Provider