javax.mail

Class 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.

Method Summary
booleangetDebug()
Get the debug setting for this session.
PrintStreamgetDebugOut()
Return the debug output stream.
static SessiongetDefaultInstance(Properties properties)
Get the "default" instance assuming no authenticator is required.
static SessiongetDefaultInstance(Properties properties, Authenticator authenticator)
Get the "default" session.
FoldergetFolder(URLName name)
Return a closed folder for the supplied URLName, or null if it cannot be obtained.
static SessiongetInstance(Properties properties, Authenticator authenticator)
Create a new session initialized with the supplied properties which uses the supplied authenticator.
static SessiongetInstance(Properties properties)
Create a new session initialized with the supplied properties with no authenticator.
PasswordAuthenticationgetPasswordAuthentication(URLName name)
Get the password authentication associated with a URL
PropertiesgetProperties()
Return the properties object for this Session; this is a live collection.
StringgetProperty(String property)
Return the specified property.
ProvidergetProvider(String protocol)
Return the provider for a specific protocol.
Provider[]getProviders()
Return the list of providers available to this application.
StoregetStore()
Return a Store for the default protocol defined by the mail.store.protocol property.
StoregetStore(String protocol)
Return a Store for the specified protocol.
StoregetStore(URLName url)
Return a Store for the protocol specified in the given URL
StoregetStore(Provider provider)
Return the Store specified by the given provider.
TransportgetTransport()
Return a Transport for the default protocol specified by the mail.transport.protocol property.
TransportgetTransport(String protocol)
Return a Transport for the specified protocol.
TransportgetTransport(URLName name)
Return a transport for the protocol specified in the URL.
TransportgetTransport(Address address)
Return a transport for the protocol associated with the type of this address.
TransportgetTransport(Provider provider)
Return the Transport specified by a Provider
PasswordAuthenticationrequestPasswordAuthentication(InetAddress host, int port, String protocol, String prompt, String defaultUserName)
Call back to the application supplied authenticator to get the needed username add password.
voidsetDebug(boolean debug)
Enable debugging for this session.
voidsetDebugOut(PrintStream out)
Set the output stream where debug information should be sent.
voidsetPasswordAuthentication(URLName name, PasswordAuthentication authenticator)
Set the password authentication associated with a URL.
voidsetProvider(Provider provider)
Make the supplied Provider the default for its protocol.

Method Detail

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

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

getFolder

public Folder getFolder(URLName name)
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

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:

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: 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)
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

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

getTransport

public Transport getTransport()
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)
Return a Transport for the specified protocol.

Parameters: protocol the protocol to use

Returns: a Transport

Throws: NoSuchProviderException

getTransport

public Transport getTransport(URLName name)
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)
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)
Return the Transport specified by a Provider

Parameters: provider the defining Provider

Returns: a Transport

Throws: NoSuchProviderException

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)
Make the supplied Provider the default for its protocol.

Parameters: provider the new default Provider

Throws: NoSuchProviderException