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
andjavamail.default.providers
-
javamail.address.map
andjavamail.default.address.map
Each javamail.
X resource file is searched for using
three methods in the following order:
-
java.home/conf/javamail.
X -
META-INF/javamail.
X -
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.
Name | Description |
---|---|
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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addProvider
(Provider provider) Add a provider to the session.boolean
getDebug()
Get the debug setting for this Session.Returns the stream to be used for debugging output.static Session
getDefaultInstance
(Properties props) Get the default Session object.static Session
getDefaultInstance
(Properties props, Authenticator authenticator) Get the default Session object.Get a closed Folder 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.Return any saved PasswordAuthentication for this (store or transport) URLName.Returns the Properties object associated with this SessiongetProperty
(String name) Returns the value of the specified property.getProvider
(String protocol) Returns the default Provider for the protocol specified.Provider[]
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.getStore()
Get a Store object that implements this user's desired Store protocol.Get an instance of the store specified by Provider.Get a Store object for the given URLName.Get a Store object that implements the specified protocol.Get the stream provider instance of the session.Get a Transport object that implements this user's desired Transport protcol.getTransport
(Address address) Get a Transport object that can transport a Message of the specified address type.getTransport
(Provider provider) Get an instance of the transport specified in the Provider.getTransport
(URLName url) Get a Transport object for the given URLName.getTransport
(String protocol) Get a Transport object that implements the specified protocol.requestPasswordAuthentication
(InetAddress addr, int port, String protocol, String prompt, String defaultUserName) Call back to the application to get the needed user name and password.void
setDebug
(boolean debug) Set the debug setting for this Session.void
setDebugOut
(PrintStream out) Set the stream to be used for debugging output for this session.void
Save a PasswordAuthentication for this (store or transport) URLName.void
setProtocolForAddress
(String addresstype, String protocol) Set the default transport protocol to use for addresses of the specified type.void
setProvider
(Provider provider) Set the passed Provider to be the default implementation for the protocol in Provider.protocol overriding any previous values.
-
Method Details
-
getStreamProvider
Get the stream provider instance of the session.- Returns:
- the stream provider
- Since:
- JavaMail 2.1
-
getInstance
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 Jakarta Mail 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:
-
getInstance
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 Jakarta Mail 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
- Since:
- JavaMail 1.2
-
getDefaultInstance
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.Additional security Permission objects may be used to control access to the default session.
In the current implementation, if a SecurityManager is set, the caller must have the
RuntimePermission("setFactory")
permission.- 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 Jakarta Mail 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
-
getDefaultInstance
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 Jakarta Mail 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
- Since:
- JavaMail 1.2
-
setDebug
public 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 themail.debug
property is used to initialize the per-Session debugging flag. Subsequent calls to thesetDebug
method manipulate the per-Session debugging flag and have no effect on themail.debug
property.- Parameters:
debug
- Debug setting
-
getDebug
public boolean getDebug()Get the debug setting for this Session.- Returns:
- current debug setting
-
setDebugOut
Set the stream to be used for debugging output for this session. Ifout
is null,System.out
will be used. Note that debugging output that occurs before any session is created, as a result of setting themail.debug
system property, will always be sent toSystem.out
.- Parameters:
out
- the PrintStream to use for debugging output- Since:
- JavaMail 1.3
-
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
- Since:
- JavaMail 1.3
-
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
-
getProvider
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.
-
setProvider
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.
-
getStore
Get a Store object that implements this user's desired Store protocol. Themail.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.
-
getStore
Get a Store object that implements the specified protocol. If an appropriate Store object cannot be obtained, NoSuchProviderException is thrown.- Parameters:
protocol
- the Store protocol- Returns:
- a Store object
- Throws:
NoSuchProviderException
- If a provider for the given protocol is not found.
-
getStore
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:
-
getStore
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.
-
getFolder
Get a closed Folder object for the given URLName. If the requested Folder 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 Folder 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:
- Folder
- Throws:
NoSuchProviderException
- If a provider for the given URLName is not found.MessagingException
- if the Folder could not be located or created.- See Also:
-
getTransport
Get a Transport object that implements this user's desired Transport protcol. Themail.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.
-
getTransport
Get a Transport object that implements the specified protocol. If an appropriate Transport object cannot be obtained, null is returned.- Parameters:
protocol
- the Transport protocol- Returns:
- a Transport object
- Throws:
NoSuchProviderException
- If provider for the given protocol is not found.
-
getTransport
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:
-
getTransport
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.
-
getTransport
Get a Transport object that can transport a Message of the specified address type.- Parameters:
address
- an address for which a Transport is needed- Returns:
- A Transport object
- Throws:
NoSuchProviderException
- If provider for the Address type is not found- See Also:
-
setPasswordAuthentication
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
- the URLNamepw
- the PasswordAuthentication to save
-
getPasswordAuthentication
Return any saved PasswordAuthentication for this (store or transport) URLName. Normally used only by store or transport implementations.- Parameters:
url
- the URLName- Returns:
- the PasswordAuthentication corresponding to the URLName
-
requestPasswordAuthentication
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
- the port on the hostprotocol
- 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.
-
getProperties
Returns the Properties object associated with this Session- Returns:
- Properties object
-
getProperty
-
addProvider
Add a provider to the session.- Parameters:
provider
- the provider to add- Since:
- JavaMail 1.4
-
setProtocolForAddress
Set the default transport protocol to use for addresses of the specified type. Normally the default is set by thejavamail.default.address.map
orjavamail.address.map
files or resources.- Parameters:
addresstype
- type of addressprotocol
- name of protocol- Since:
- JavaMail 1.4
- See Also:
-