public final class

Session

extends Object
java.lang.Object
   ↳ com.google.code.javax.mail.Session

Class Overview

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.

The Session class provides access to the protocol providers that implement the Store, Transport, and related classes. The protocol providers are configured using the following files:

  • java-gmail-imap.providers and java-gmail-imap.default.providers
  • java-gmail-imap.address.map and java-gmail-imap.default.address.map

Each java-gmail-imap.X resource file is searched for using three methods in the following order:

  1. java.home/lib/java-gmail-imap.X
  2. META-INF/java-gmail-imap.X
  3. META-INF/java-gmail-imap.default.X

The first method allows the user to include their own version of the resource file by placing it in the lib directory where the java.home 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 META-INF directory. The java-gmail-imap.default.X default files are part of the JavaMail mail.jar file.

File location depends upon how the ClassLoader method getResource is implemented. Usually, the getResource 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.

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.

java-gmail-imap.providers and java-gmail-imap.default.providers

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.

Attribute Names in Providers Files
NameDescription
protocol Name assigned to protocol. For example, smtp for Transport.
type Valid entries are store and transport.
class Class name that implements this protocol.
vendor Optional string identifying the vendor.
version Optional string identifying the version.

Here's an example of META-INF/java-gmail-imap.default.providers file contents: 

 protocol=imap; type=store; class=com.google.code.com.sun.mail.imap.IMAPStore; vendor=Sun Microsystems, Inc.;
 protocol=smtp; type=transport; class=com.google.code.com.sun.mail.smtp.SMTPTransport; vendor=Sun Microsystems, Inc.;

java-gmail-imap.address.map and java-gmail-imap.default.address.map

These resource files map transport address types to the transport protocol. The getType method of javax.mail.Address returns the address type. The javamail.address.map 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 javax.mail.Address implementation that is present if it is to be used. For example, the javax.mail.internet.InternetAddress method getType returns "rfc822". Each referenced protocol should be installed on the system. For the case of news, below, the client should install a Transport provider supporting the nntp protocol.

Here are the typical contents of a javamail.address.map file: 

 rfc822=smtp
 news=nntp

Summary

Fields
private final Properties addressMap
private final Hashtable authTable
private final Authenticator authenticator
private boolean debug
private static Session defaultSession
private PrintStream out
private final Properties props
private final Vector providers
private final Hashtable providersByClassName
private final Hashtable providersByProtocol
Public Methods
synchronized void addProvider(Provider provider)
Add a provider to the session.
synchronized boolean getDebug()
Get the debug setting for this Session.
synchronized PrintStream getDebugOut()
Returns the stream to be used for debugging output.
synchronized static Session getDefaultInstance(Properties props, Authenticator authenticator)
Get the default Session object.
static Session getDefaultInstance(Properties props)
Get the default Session object.
Folder getFolder(URLName url)
Get a closed GmailFolder object for the given URLName.
static Session getInstance(Properties props)
Get a new Session object.
static Session getInstance(Properties props, Authenticator authenticator)
Get a new Session object.
PasswordAuthentication getPasswordAuthentication(URLName url)
Return any saved PasswordAuthentication for this (store or transport) URLName.
Properties getProperties()
Returns the Properties object associated with this Session
String getProperty(String name)
Returns the value of the specified property.
synchronized Provider getProvider(String protocol)
Returns the default Provider for the protocol specified.
synchronized Provider[] getProviders()
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.
Store getStore(Provider provider)
Get an instance of the store specified by Provider.
Store getStore(URLName url)
Get a Store object for the given URLName.
Store getStore(String protocol)
Get a Store object that implements the specified protocol.
Store getStore()
Get a Store object that implements this user's desired Store protocol.
Transport getTransport(URLName url)
Get a Transport object for the given URLName.
Transport getTransport()
Get a Transport object that implements this user's desired Transport protcol.
Transport getTransport(String protocol)
Get a Transport object that implements the specified protocol.
Transport getTransport(Address address)
Get a Transport object that can transport a Message of the specified address type.
Transport getTransport(Provider provider)
Get an instance of the transport specified in the Provider.
PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName)
Call back to the application to get the needed user name and password.
synchronized void setDebug(boolean debug)
Set the debug setting for this Session.
synchronized void setDebugOut(PrintStream out)
Set the stream to be used for debugging output for this session.
void setPasswordAuthentication(URLName url, PasswordAuthentication pw)
Save a PasswordAuthentication for this (store or transport) URLName.
synchronized void setProtocolForAddress(String addresstype, String protocol)
Set the default transport protocol to use for addresses of the specified type.
synchronized void setProvider(Provider provider)
Set the passed Provider to be the default implementation for the protocol in Provider.protocol overriding any previous values.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

private final Properties addressMap

private final Hashtable authTable

private final Authenticator authenticator

private boolean debug

private static Session defaultSession

private PrintStream out

private final Properties props

private final Vector providers

private final Hashtable providersByClassName

private final Hashtable providersByProtocol

Public Methods

public synchronized void addProvider (Provider provider)

Add a provider to the session.

Parameters
provider The provider to add

public synchronized boolean getDebug ()

Get the debug setting for this Session.

Returns
  • current debug setting

public synchronized PrintStream getDebugOut ()

Returns the stream to be used for debugging output. If no stream has been set, System.out is returned.

Returns
  • the PrintStream to use for debugging output

public static synchronized Session getDefaultInstance (Properties props, Authenticator authenticator)

Get the default Session object. If a default has not yet been setup, a new Session object is created and installed as the default.

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.

Note that if the Authenticator object used to create the session is null, anyone can get the default session by passing in null.

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 getInstance method to get a new Session object every time the method is called.

In JDK 1.2, additional security Permission objects may be used to control access to the default session.

Parameters
props Properties object. Used only if a new Session object is created.
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.
authenticator Authenticator object. Used only if a new Session object is created. Otherwise, it must match the Authenticator used to create the Session.
Returns
  • the default Session object

public static Session getDefaultInstance (Properties props)

Get the default Session object. If a default has not yet been setup, a new Session object is created and installed as the default.

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.

Parameters
props Properties object. Used only if a new Session object is created.
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.
Returns
  • the default Session object

public Folder getFolder (URLName url)

Get a closed GmailFolder object for the given URLName. If the requested GmailFolder object cannot be obtained, null is returned.

The "scheme" part of the URL string (Refer RFC 1738) is used to locate the Store protocol. The rest of the URL string (that is, the "schemepart", as per RFC 1738) is used by that Store in a protocol dependent manner to locate and instantiate the appropriate GmailFolder object.

Note that RFC 1738 also specifies the syntax for the "schemepart" for IP-based protocols (IMAP4, POP3, etc.). Providers of IP-based mail Stores should implement that syntax for referring to Folders.

Parameters
url URLName that represents the desired folder
Returns
  • GmailFolder
Throws
NoSuchProviderException If a provider for the given URLName is not found.
MessagingException if the GmailFolder could not be located or created.
See Also

public static Session getInstance (Properties props)

Get a new Session object.

Parameters
props Properties object that hold relevant properties.
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.
Returns
  • a new Session object

public static Session getInstance (Properties props, Authenticator authenticator)

Get a new Session object.

Parameters
props Properties object that hold relevant properties.
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.
authenticator Authenticator object used to call back to the application when a user name and password is needed.
Returns
  • a new Session object
See Also
  • javax.mail.Authenticator

public PasswordAuthentication getPasswordAuthentication (URLName url)

Return any saved PasswordAuthentication for this (store or transport) URLName. Normally used only by store or transport implementations.

Parameters
url
Returns
  • the PasswordAuthentication corresponding to the URLName

public Properties getProperties ()

Returns the Properties object associated with this Session

Returns
  • Properties object

public String getProperty (String name)

Returns the value of the specified property. Returns null if this property does not exist.

Parameters
name
Returns
  • String that is the property value

public synchronized Provider getProvider (String protocol)

Returns the default Provider for the protocol specified. Checks mail.<protocol>.class property first and if it exists, returns the Provider associated with this implementation. If it doesn't exist, returns the Provider that appeared first in the configuration files. If an implementation for the protocol isn't found, throws NoSuchProviderException

Parameters
protocol Configured protocol (i.e. smtp, imap, etc)
Returns
  • Currently configured Provider for the specified protocol
Throws
NoSuchProviderException If a provider for the given protocol is not found.

public synchronized Provider[] getProviders ()

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.

Returns
  • Array of configured providers

public Store getStore (Provider provider)

Get an instance of the store specified by Provider. Instantiates the store and returns it.

Parameters
provider Store Provider that will be instantiated
Returns
  • Instantiated Store
Throws
NoSuchProviderException If a provider for the given Provider is not found.

public Store getStore (URLName url)

Get a Store object for the given URLName. If the requested Store object cannot be obtained, NoSuchProviderException is thrown. The "scheme" part of the URL string (Refer RFC 1738) is used to locate the Store protocol.

Parameters
url URLName that represents the desired Store
Returns
  • a closed Store object
Throws
NoSuchProviderException If a provider for the given URLName is not found.
See Also

public Store getStore (String protocol)

Get a Store object that implements the specified protocol. If an appropriate Store object cannot be obtained, NoSuchProviderException is thrown.

Parameters
protocol
Returns
  • a Store object
Throws
NoSuchProviderException If a provider for the given protocol is not found.

public Store getStore ()

Get a Store object that implements this user's desired Store protocol. The mail.store.protocol property specifies the desired protocol. If an appropriate Store object is not obtained, NoSuchProviderException is thrown

Returns
  • a Store object
Throws
NoSuchProviderException If a provider for the given protocol is not found.

public Transport getTransport (URLName url)

Get a Transport object for the given URLName. If the requested Transport object cannot be obtained, NoSuchProviderException is thrown. The "scheme" part of the URL string (Refer RFC 1738) is used to locate the Transport protocol.

Parameters
url URLName that represents the desired Transport
Returns
  • a closed Transport object
Throws
NoSuchProviderException If a provider for the given URLName is not found.
See Also
  • javax.mail.URLName

public Transport getTransport ()

Get a Transport object that implements this user's desired Transport protcol. The mail.transport.protocol property specifies the desired protocol. If an appropriate Transport object cannot be obtained, MessagingException is thrown.

Returns
  • a Transport object
Throws
NoSuchProviderException If the provider is not found.

public Transport getTransport (String protocol)

Get a Transport object that implements the specified protocol. If an appropriate Transport object cannot be obtained, null is returned.

Parameters
protocol
Returns
  • a Transport object
Throws
NoSuchProviderException If provider for the given protocol is not found.

public Transport getTransport (Address address)

Get a Transport object that can transport a Message of the specified address type.

Parameters
address
Returns
  • A Transport object
Throws
NoSuchProviderException If provider for the Address type is not found
See Also
  • javax.mail.Address

public Transport getTransport (Provider provider)

Get an instance of the transport specified in the Provider. Instantiates the transport and returns it.

Parameters
provider Transport Provider that will be instantiated
Returns
  • Instantiated Transport
Throws
NoSuchProviderException If provider for the given provider is not found.

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

Call back to the application to get the needed user name and password. The application should put up a dialog something like: 

 Connecting to <protocol> mail service on host <addr>, port <port>.
 <prompt>

 User Name: <defaultUserName>
 Password:

Parameters
addr InetAddress of the host. may be null.
port
protocol Protocol scheme (e.g. imap, pop3, etc.)
prompt Any additional String to show as part of the prompt; may be null.
defaultUserName The default username. may be null.
Returns
  • the authentication which was collected by the authenticator; may be null.

public synchronized void setDebug (boolean debug)

Set the debug setting for this Session.

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 mail.debug in the Properties object passed in to the constructor to true. The value of the mail.debug property is used to initialize the per-Session debugging flag. Subsequent calls to the setDebug method manipulate the per-Session debugging flag and have no affect on the mail.debug property.

Parameters
debug Debug setting

public synchronized void setDebugOut (PrintStream out)

Set the stream to be used for debugging output for this session. If out is null, System.out will be used. Note that debugging output that occurs before any session is created, as a result of setting the mail.debug system property, will always be sent to System.out.

Parameters
out The PrintStream to use for debugging output

public void setPasswordAuthentication (URLName url, PasswordAuthentication pw)

Save a PasswordAuthentication for this (store or transport) URLName. If pw is null the entry corresponding to the URLName is removed.

This is normally used only by the store or transport implementations to allow authentication information to be shared among multiple uses of a session.

Parameters
url
pw

public synchronized void setProtocolForAddress (String addresstype, String protocol)

Set the default transport protocol to use for addresses of the specified type. Normally the default is set by the javamail.default.address.map or javamail.address.map files or resources.

Parameters
addresstype Type of address
protocol Name of protocol
See Also

public synchronized void setProvider (Provider provider)

Set the passed Provider to be the default implementation for the protocol in Provider.protocol overriding any previous values.

Parameters
provider Currently configured Provider which will be set as the default for the protocol
Throws
NoSuchProviderException If the provider passed in is invalid.