Module jakarta.mail
Package jakarta.mail

Class Session

java.lang.Object
jakarta.mail.Session

public final class Session extends Object
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:

  • javamail.providers and javamail.default.providers
  • javamail.address.map and javamail.default.address.map

Each javamail.X resource file is searched for using three methods in the following order:

  1. java.home/conf/javamail.X
  2. META-INF/javamail.X
  3. META-INF/javamail.default.X

(Where java.home is the value of the "java.home" System property and conf is the directory named "conf" if it exists, otherwise the directory named "lib"; the "conf" directory was introduced in JDK 1.9.)

The first method allows the user to include their own version of the resource file by placing it in the conf directory where the java.home property points. The second method allows an application that uses the Jakarta Mail APIs to include their own resource files in their application's or jar file's META-INF directory. The javamail.default.X default files are part of the Jakarta Mail mail.jar file and should not be supplied by users.

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.

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 Jakarta Mail APIs. This means that all entries in all files loaded will be available.

javamail.providers and javamail.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/javamail.default.providers file contents:

 protocol=imap; type=store; class=com.sun.mail.imap.IMAPStore; vendor=Oracle;
 protocol=smtp; type=transport; class=com.sun.mail.smtp.SMTPTransport; vendor=Oracle;
 

The current implementation also supports configuring providers using the Java SE ServiceLoader mechanism. When creating your own provider, create a Provider subclass, for example:

 package com.example;

 import jakarta.mail.Provider;

 public class MyProvider extends Provider {
     public MyProvider() {
         super(Provider.Type.STORE, "myprot", MyStore.class.getName(),
             "Example", null);
     }
 }
 
Then include a file named META-INF/services/jakarta.mail.Provider in your jar file that lists the name of your Provider class:
 com.example.MyProvider
 

javamail.address.map and javamail.default.address.map

These resource files map transport address types to the transport protocol. The getType method of jakarta.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 jakarta.mail.Address implementation that is present if it is to be used. For example, the jakarta.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