Jakarta EE 11.0.0 · jakarta.mail.Session · APIdia, the JavaDoc alternative

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:

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.

Attribute Names in Providers Files
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

Field Summary

Modifier and Type	Field and Description
private final Properties	addressMap
private final Authenticator	authenticator
private final Hashtable<URLName, PasswordAuthentication>	authTable
private static final String	confDir
private boolean	debug
private static final String	DEFAULT_PROVIDER
private static Session	defaultSession
private MailLogger	logger
private PrintStream	out
private final Properties	props
private final List<Provider>	providers
private final Map<String, Provider>	providersByClassName
private final Map<String, Provider>	providersByProtocol
private final EventQueue	q
private final StreamProvider	streamProvider

Constructor Summary

Access	Constructor and Description
private	Session(Properties props, Authenticator authenticator)

Method Summary

Modifier and Type	Method and Description
public synchronized void	addProvider(Provider the provider to add provider) Add a provider to the session.
pack-priv static boolean	containsDefaultProvider(Provider provider)
private static ClassLoader[]	getClassLoaders(final Class<?>... classes)
pack-priv static ClassLoader	getContextClassLoader()
public synchronized boolean	Returns: current debug setting getDebug() Get the debug setting for this Session.
public synchronized PrintStream	Returns: the PrintStream to use for debugging output getDebugOut() Returns the stream to be used for debugging output.
public static synchronized Session	Returns: the default Session object getDefaultInstance(Properties 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. props, Authenticator Authenticator object. Used only if a new Session object is created. Otherwise, it must match the Authenticator used to create the Session. authenticator) Get the default Session object.
public static Session	Returns: the default Session object getDefaultInstance(Properties 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. props) Get the default Session object.
pack-priv EventQueue	getEventQueue()
public Folder	Returns: Folder getFolder(URLName URLName that represents the desired folder url) Get a closed Folder object for the given URLName.
private static Class<?>[]	getHk2ServiceLoaderTargets(Class<?> factoryClass)
public static Session	Returns: a new Session object getInstance(Properties 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. props, Authenticator Authenticator object used to call back to the application when a user name and password is needed. authenticator) Get a new Session object.
public static Session	Returns: a new Session object getInstance(Properties 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. props) Get a new Session object.
public PasswordAuthentication	Returns: the PasswordAuthentication corresponding to the URLName getPasswordAuthentication(URLName the URLName url) Return any saved PasswordAuthentication for this (store or transport) URLName.
public Properties	Returns: Properties object getProperties() Returns the Properties object associated with this Session
public String	Returns: String that is the property value getProperty(String the property name name) Returns the value of the specified property.
public synchronized Provider	Returns: Currently configured Provider for the specified protocol getProvider(String Configured protocol (i.e. smtp, imap, etc) protocol) Returns the default Provider for the protocol specified.
public synchronized Provider[]	Returns: Array of configured providers 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.
private static InputStream	getResourceAsStream(final Class<?> c, final String name)
private static URL[]	getResources(final ClassLoader cl, final String name)
private <T extends Service> T	getService(Provider which provider to use provider, URLName which URLName to use (can be null) url, Class<T> the service type (class) type) Get a Service object.
public Store	Returns: a Store object getStore() Get a Store object that implements this user's desired Store protocol.
public Store	Returns: a Store object getStore(String the Store protocol protocol) Get a Store object that implements the specified protocol.
public Store	Returns: a closed Store object getStore(URLName URLName that represents the desired Store url) Get a Store object for the given URLName.
public Store	Returns: Instantiated Store getStore(Provider Store Provider that will be instantiated provider) Get an instance of the store specified by Provider.
private Store	Returns: Instantiated Store getStore(Provider Store Provider that will be instantiated provider, URLName URLName used to instantiate the Store url) Get an instance of the store specified by Provider.
public StreamProvider	Returns: the stream provider getStreamProvider() Get the stream provider instance of the session.
private static URL[]	getSystemResources(final String name)
public Transport	Returns: a Transport object getTransport() Get a Transport object that implements this user's desired Transport protcol.
public Transport	Returns: a Transport object getTransport(String the Transport protocol protocol) Get a Transport object that implements the specified protocol.
public Transport	Returns: a closed Transport object getTransport(URLName URLName that represents the desired Transport url) Get a Transport object for the given URLName.
public Transport	Returns: Instantiated Transport getTransport(Provider Transport Provider that will be instantiated provider) Get an instance of the transport specified in the Provider.
public Transport	Returns: A Transport object getTransport(Address an address for which a Transport is needed address) Get a Transport object that can transport a Message of the specified address type.
private Transport	Returns: A Transport object getTransport(Provider the provider to use provider, URLName urlname to use (can be null) url) Get a Transport object using the given provider and urlname.
private final synchronized void	initLogger()
private void	loadAddressMap(Class<?> cl)
private void	loadAllResources(String name, Class<?> cl, StreamLoader loader) Load all of the named resource.
private void	loadFile(String name, StreamLoader loader) Load from the named file.
private void	loadProviders(Class<?> cl) Load the protocol providers config files.
private void	loadProvidersFromStream(InputStream is)
private void	loadResource(String name, Class<?> cl, StreamLoader loader, boolean expected) Load from the named resource.
private <T> Iterator<T>	lookupUsingHk2ServiceLoader(Class<T> factoryId, ClassLoader loader)
private static InputStream	openStream(final URL url)
public PasswordAuthentication	Returns: the authentication which was collected by the authenticator; may be null. requestPasswordAuthentication(InetAddress InetAddress of the host. may be null. addr, int the port on the host port, String protocol scheme (e.g. imap, pop3, etc.) protocol, String any additional String to show as part of the prompt; may be null. prompt, String the default username. may be null. defaultUserName) Call back to the application to get the needed user name and password.
public synchronized void	setDebug(boolean Debug setting debug) Set the debug setting for this Session.
public synchronized void	setDebugOut(PrintStream the PrintStream to use for debugging output out) Set the stream to be used for debugging output for this session.
public void	setPasswordAuthentication(URLName the URLName url, PasswordAuthentication the PasswordAuthentication to save pw) Save a PasswordAuthentication for this (store or transport) URLName.
public synchronized void	setProtocolForAddress(String type of address addresstype, String name of protocol protocol) Set the default transport protocol to use for addresses of the specified type.
public synchronized void	setProvider(Provider Currently configured Provider which will be set as the default for the protocol provider) Set the passed Provider to be the default implementation for the protocol in Provider.protocol overriding any previous values.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

addressMap	back to summary
private final Properties addressMap

authenticator	back to summary
private final Authenticator authenticator

authTable	back to summary
private final Hashtable<URLName, PasswordAuthentication> authTable

confDir	back to summary
private static final String confDir

debug	back to summary
private boolean debug

DEFAULT_PROVIDER	back to summary
private static final String DEFAULT_PROVIDER

defaultSession	back to summary
private static Session defaultSession

logger	back to summary
private MailLogger logger

out	back to summary
private PrintStream out

props	back to summary
private final Properties props

providers	back to summary
private final List<Provider> providers

providersByClassName	back to summary
private final Map<String, Provider> providersByClassName

providersByProtocol	back to summary
private final Map<String, Provider> providersByProtocol

q	back to summary
private final EventQueue q

streamProvider	back to summary
private final StreamProvider streamProvider

Constructor Detail

Session	back to summary
private Session(Properties props, Authenticator authenticator)

Method Detail

addProvider	back to summary
public synchronized void addProvider(Provider provider) Add a provider to the session. Parameters provider:Provider the provider to add Since JavaMail 1.4

addProvider

back to summary

public synchronized void addProvider(Provider provider)

Add a provider to the session.

Parameters

provider:Provider: the provider to add

Since

JavaMail 1.4

containsDefaultProvider	back to summary
pack-priv static boolean containsDefaultProvider(Provider provider)

getClassLoaders	back to summary
private static ClassLoader[] getClassLoaders(final Class<?>... classes)

getContextClassLoader	back to summary
pack-priv static ClassLoader getContextClassLoader()

getDebug	back to summary
public synchronized boolean getDebug() Get the debug setting for this Session. Returns:boolean current debug setting

getDebug

back to summary

public synchronized boolean getDebug()

Get the debug setting for this Session.

Returns:boolean: current debug setting

getDebugOut back to summary

getDebugOut	back to summary
public synchronized PrintStream getDebugOut() Returns the stream to be used for debugging output. If no stream has been set, `System.out` is returned. Returns:PrintStream the PrintStream to use for debugging output Since JavaMail 1.3

public synchronized PrintStream getDebugOut()

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

Returns:PrintStream: the PrintStream to use for debugging output
Since: JavaMail 1.3

getDefaultInstance back to summary

getDefaultInstance	back to summary
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. 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 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 Authenticator object. Used only if a new Session object is created. Otherwise, it must match the Authenticator used to create the Session. Returns:Session the default Session object

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.

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: 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: Authenticator object. Used only if a new Session object is created. Otherwise, it must match the Authenticator used to create the Session.

Returns:Session

the default Session object

getDefaultInstance	back to summary
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 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:Session the default Session object Since JavaMail 1.2

getDefaultInstance

back to summary

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

the default Session object

Since

JavaMail 1.2

getEventQueue	back to summary
pack-priv EventQueue getEventQueue()

getFolder back to summary

getFolder	back to summary
public Folder getFolder(URLName url) throws MessagingException 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 URLName that represents the desired folder Returns:Folder Folder Exceptions MessagingException: if the Folder could not be located or created. NoSuchProviderException: If a provider for the given URLName is not found. See Also `getStore(URLName)`, `jakarta.mail.URLName`

public Folder getFolder(URLName url) throws MessagingException

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: URLName that represents the desired folder

Returns:Folder

Folder

Exceptions

MessagingException:: if the Folder could not be located or created.
NoSuchProviderException:: If a provider for the given URLName is not found.

getHk2ServiceLoaderTargets	back to summary
private static Class<?>[] getHk2ServiceLoaderTargets(Class<?> factoryClass)

getInstance back to summary

getInstance	back to summary
public static Session getInstance(Properties props, Authenticator authenticator) Get a new Session object. Parameters props:Properties 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 Authenticator object used to call back to the application when a user name and password is needed. Returns:Session a new Session object See Also `jakarta.mail.Authenticator`

public static Session getInstance(Properties props, Authenticator authenticator)

Get a new Session object.

Parameters

props:Properties: 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: Authenticator object used to call back to the application when a user name and password is needed.

Returns:Session

a new Session object

See Also

jakarta.mail.Authenticator

getInstance	back to summary
public static Session getInstance(Properties props) Get a new Session object. Parameters props:Properties 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:Session a new Session object Since JavaMail 1.2

getInstance

back to summary

public static Session getInstance(Properties props)

Get a new Session object.

Parameters

props:Properties: 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:Session

a new Session object

Since

JavaMail 1.2

getPasswordAuthentication	back to summary
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:URLName the URLName Returns:PasswordAuthentication the PasswordAuthentication corresponding to the URLName

getPasswordAuthentication

back to summary

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:URLName: the URLName

Returns:PasswordAuthentication

the PasswordAuthentication corresponding to the URLName

getProperties	back to summary
public Properties getProperties() Returns the Properties object associated with this Session Returns:Properties Properties object

getProperties

back to summary

public Properties getProperties()

Returns the Properties object associated with this Session

Returns:Properties: Properties object

getProperty	back to summary
public String getProperty(String name) Returns the value of the specified property. Returns null if this property does not exist. Parameters name:String the property name Returns:String String that is the property value

getProperty

back to summary

public String getProperty(String name)

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

Parameters

name:String: the property name

Returns:String

String that is the property value

getProvider	back to summary
public synchronized Provider getProvider(String protocol) throws NoSuchProviderException 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:String Configured protocol (i.e. smtp, imap, etc) Returns:Provider Currently configured Provider for the specified protocol Exceptions NoSuchProviderException: If a provider for the given protocol is not found.

getProvider

back to summary

public synchronized Provider getProvider(String protocol) throws NoSuchProviderException

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:String: Configured protocol (i.e. smtp, imap, etc)

Returns:Provider

Currently configured Provider for the specified protocol

Exceptions

NoSuchProviderException:: If a provider for the given protocol is not found.

getProviders	back to summary
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:Provider[] Array of configured providers

getProviders

back to summary

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:Provider[]: Array of configured providers

getResourceAsStream	back to summary
private static InputStream getResourceAsStream(final Class<?> c, final String name) throws IOException

getResources	back to summary
private static URL[] getResources(final ClassLoader cl, final String name)

getService	back to summary
private <T extends Service> T getService(Provider provider, URLName url, Class<T> type) throws NoSuchProviderException Get a Service object. Needs a provider object, but will create a URLName if needed. It attempts to instantiate the correct class. Parameters provider:Provider which provider to use url:URLName which URLName to use (can be null) type:Class<T> the service type (class) Exceptions NoSuchProviderException: thrown when the class cannot be found or when it does not have the correct constructor (Session, URLName), or if it is not derived from Service.

getService

back to summary

private <T extends Service> T getService(Provider provider, URLName url, Class<T> type) throws NoSuchProviderException

Get a Service object. Needs a provider object, but will create a URLName if needed. It attempts to instantiate the correct class.

Parameters

provider:Provider: which provider to use
url:URLName: which URLName to use (can be null)
type:Class<T>: the service type (class)

Exceptions

NoSuchProviderException:: thrown when the class cannot be found or when it does not have the correct constructor (Session, URLName), or if it is not derived from Service.

getStore back to summary

getStore	back to summary
public Store getStore() throws NoSuchProviderException 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:Store a Store object Exceptions NoSuchProviderException: If a provider for the given protocol is not found.

public Store getStore() throws NoSuchProviderException

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

a Store object

Exceptions

NoSuchProviderException:: If a provider for the given protocol is not found.

getStore	back to summary
public Store getStore(String protocol) throws NoSuchProviderException Get a Store object that implements the specified protocol. If an appropriate Store object cannot be obtained, NoSuchProviderException is thrown. Parameters protocol:String the Store protocol Returns:Store a Store object Exceptions NoSuchProviderException: If a provider for the given protocol is not found.

getStore

back to summary

public Store getStore(String protocol) throws NoSuchProviderException

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

Parameters

protocol:String: the Store protocol

Returns:Store

a Store object

Exceptions

NoSuchProviderException:: If a provider for the given protocol is not found.

getStore back to summary

getStore	back to summary
public Store getStore(URLName url) throws NoSuchProviderException 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 URLName that represents the desired Store Returns:Store a closed Store object Exceptions NoSuchProviderException: If a provider for the given URLName is not found. See Also `getFolder(URLName)`, `jakarta.mail.URLName`

public Store getStore(URLName url) throws NoSuchProviderException

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: URLName that represents the desired Store

Returns:Store

a closed Store object

Exceptions

NoSuchProviderException:: If a provider for the given URLName is not found.

getStore	back to summary
public Store getStore(Provider provider) throws NoSuchProviderException Get an instance of the store specified by Provider. Instantiates the store and returns it. Parameters provider:Provider Store Provider that will be instantiated Returns:Store Instantiated Store Exceptions NoSuchProviderException: If a provider for the given Provider is not found.

getStore

back to summary

public Store getStore(Provider provider) throws NoSuchProviderException

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

Parameters

provider:Provider: Store Provider that will be instantiated

Returns:Store

Instantiated Store

Exceptions

NoSuchProviderException:: If a provider for the given Provider is not found.

getStore	back to summary
private Store getStore(Provider provider, URLName url) throws NoSuchProviderException Get an instance of the store specified by Provider. If the URLName is not null, uses it, otherwise creates a new one. Instantiates the store and returns it. This is a private method used by getStore(Provider) and getStore(URLName) Parameters provider:Provider Store Provider that will be instantiated url:URLName URLName used to instantiate the Store Returns:Store Instantiated Store Exceptions NoSuchProviderException: If a provider for the given Provider/URLName is not found.

getStore

back to summary

private Store getStore(Provider provider, URLName url) throws NoSuchProviderException

Get an instance of the store specified by Provider. If the URLName is not null, uses it, otherwise creates a new one. Instantiates the store and returns it. This is a private method used by getStore(Provider) and getStore(URLName)

Parameters

provider:Provider: Store Provider that will be instantiated
url:URLName: URLName used to instantiate the Store

Returns:Store

Instantiated Store

Exceptions

NoSuchProviderException:: If a provider for the given Provider/URLName is not found.

getStreamProvider	back to summary
public StreamProvider getStreamProvider() Get the stream provider instance of the session. Returns:StreamProvider the stream provider Since JavaMail 2.1

getStreamProvider

back to summary

public StreamProvider getStreamProvider()

Get the stream provider instance of the session.

Returns:StreamProvider: the stream provider
Since: JavaMail 2.1

getSystemResources	back to summary
private static URL[] getSystemResources(final String name)

getTransport back to summary

getTransport	back to summary
public Transport getTransport() throws NoSuchProviderException 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:Transport a Transport object Exceptions NoSuchProviderException: If the provider is not found.

public Transport getTransport() throws NoSuchProviderException

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

a Transport object

Exceptions

NoSuchProviderException:: If the provider is not found.

getTransport	back to summary
public Transport getTransport(String protocol) throws NoSuchProviderException Get a Transport object that implements the specified protocol. If an appropriate Transport object cannot be obtained, null is returned. Parameters protocol:String the Transport protocol Returns:Transport a Transport object Exceptions NoSuchProviderException: If provider for the given protocol is not found.

getTransport

back to summary

public Transport getTransport(String protocol) throws NoSuchProviderException

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

Parameters

protocol:String: the Transport protocol

Returns:Transport

a Transport object

Exceptions

NoSuchProviderException:: If provider for the given protocol is not found.

getTransport back to summary

public Transport getTransport(URLName url) throws NoSuchProviderException

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: URLName that represents the desired Transport

Returns:Transport

a closed Transport object

Exceptions

NoSuchProviderException:: If a provider for the given URLName is not found.

See Also

jakarta.mail.URLName

getTransport

back to summary

public Transport getTransport(Provider provider) throws NoSuchProviderException

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

Parameters

provider:Provider: Transport Provider that will be instantiated

Returns:Transport

Instantiated Transport

Exceptions

NoSuchProviderException:: If provider for the given provider is not found.

getTransport back to summary

public Transport getTransport(Address address) throws NoSuchProviderException

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

Parameters

address:Address: an address for which a Transport is needed

Returns:Transport

A Transport object

Exceptions

NoSuchProviderException:: If provider for the Address type is not found

See Also

jakarta.mail.Address

getTransport

back to summary

private Transport getTransport(Provider provider, URLName url) throws NoSuchProviderException

Get a Transport object using the given provider and urlname.

Parameters

provider:Provider: the provider to use
url:URLName: urlname to use (can be null)

Returns:Transport

A Transport object

Exceptions

NoSuchProviderException:: If no provider or the provider was the wrong class.

initLogger	back to summary
private final synchronized void initLogger()

loadAddressMap	back to summary
private void loadAddressMap(Class<?> cl)

loadAllResources	back to summary
private void loadAllResources(String name, Class<?> cl, StreamLoader loader) Load all of the named resource.

loadFile	back to summary
private void loadFile(String name, StreamLoader loader) Load from the named file.

loadProviders	back to summary
private void loadProviders(Class<?> cl) Load the protocol providers config files.

loadProvidersFromStream	back to summary
private void loadProvidersFromStream(InputStream is) throws IOException

loadResource	back to summary
private void loadResource(String name, Class<?> cl, StreamLoader loader, boolean expected) Load from the named resource.

lookupUsingHk2ServiceLoader	back to summary
private <T> Iterator<T> lookupUsingHk2ServiceLoader(Class<T> factoryId, ClassLoader loader) Annotations @SuppressWarnings:unchecked

openStream	back to summary
private static InputStream openStream(final URL url) throws IOException

requestPasswordAuthentication

back to summary

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: InetAddress of the host. may be null.
port:int: the port on the host
protocol:String: protocol scheme (e.g. imap, pop3, etc.)
prompt:String: any additional String to show as part of the prompt; may be null.
defaultUserName:String: the default username. may be null.

Returns:PasswordAuthentication

the authentication which was collected by the authenticator; may be null.

setDebug back to summary

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 effect on the mail.debug property.

Parameters

debug:boolean: Debug setting

setDebugOut back to summary

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:PrintStream: the PrintStream to use for debugging output

Since

JavaMail 1.3

setPasswordAuthentication

back to summary

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:URLName: the URLName
pw:PasswordAuthentication: the PasswordAuthentication to save

setProtocolForAddress back to summary

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:String: type of address
protocol:String: name of protocol

Since

JavaMail 1.4

See Also

getTransport(Address)

setProvider

back to summary

public synchronized void setProvider(Provider provider) throws NoSuchProviderException

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

Parameters

provider:Provider: Currently configured Provider which will be set as the default for the protocol

Exceptions

NoSuchProviderException:: If the provider passed in is invalid.

public final Class Session

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail