public final class Session extends Object
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/lib/javamail.
X META-INF/javamail.
X META-INF/javamail.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 javamail.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.
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.
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;
javamail.address.map
and
javamail.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
Modifier and Type | Method and Description |
---|---|
void |
addProvider(Provider provider)
Add a provider to the session.
|
boolean |
getDebug()
Get the debug setting for this Session.
|
PrintStream |
getDebugOut()
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.
|
Folder |
getFolder(URLName url)
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.
|
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.
|
Provider |
getProvider(String protocol)
Returns the default Provider for the protocol
specified.
|
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()
Get a Store object that implements this user's desired Store
protocol.
|
Store |
getStore(Provider provider)
Get an instance of the store specified by Provider.
|
Store |
getStore(String protocol)
Get a Store object that implements the specified protocol.
|
Store |
getStore(URLName url)
Get a Store object for the given URLName.
|
Transport |
getTransport()
Get a Transport object that implements this user's desired
Transport protcol.
|
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.
|
Transport |
getTransport(String protocol)
Get a Transport object that implements the specified protocol.
|
Transport |
getTransport(URLName url)
Get a Transport object for the given URLName.
|
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.
|
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 |
setPasswordAuthentication(URLName url,
PasswordAuthentication pw)
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.
|
public static Session getInstance(Properties props, Authenticator authenticator)
props
- Properties object that hold relevant properties.authenticator
- Authenticator object used to call back to
the application when a user name and password is
needed.Authenticator
public static Session getInstance(Properties props)
props
- Properties object that hold relevant properties.public static Session getDefaultInstance(Properties props, Authenticator authenticator)
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.
props
- Properties object. Used only if a new Session
object is created.authenticator
- Authenticator object. Used only if a
new Session object is created. Otherwise,
it must match the Authenticator used to create
the Session.public static Session getDefaultInstance(Properties props)
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.
props
- Properties object. Used only if a new Session
object is created.public void setDebug(boolean debug)
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.
debug
- Debug settingpublic boolean getDebug()
public void setDebugOut(PrintStream out)
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
.out
- the PrintStream to use for debugging outputpublic PrintStream getDebugOut()
System.out
is returned.public Provider[] getProviders()
public Provider getProvider(String protocol) throws NoSuchProviderException
protocol
- Configured protocol (i.e. smtp, imap, etc)NoSuchProviderException
- If a provider for the given
protocol is not found.public void setProvider(Provider provider) throws NoSuchProviderException
provider
- Currently configured Provider which will be
set as the default for the protocolNoSuchProviderException
- If the provider passed in
is invalid.public Store getStore() throws NoSuchProviderException
mail.store.protocol
property specifies the
desired protocol. If an appropriate Store object is not obtained,
NoSuchProviderException is thrownNoSuchProviderException
- If a provider for the given
protocol is not found.public Store getStore(String protocol) throws NoSuchProviderException
protocol
- the Store protocolNoSuchProviderException
- If a provider for the given
protocol is not found.public Store getStore(URLName url) throws NoSuchProviderException
url
- URLName that represents the desired StoreNoSuchProviderException
- If a provider for the given
URLName is not found.getFolder(URLName)
,
URLName
public Store getStore(Provider provider) throws NoSuchProviderException
provider
- Store Provider that will be instantiatedNoSuchProviderException
- If a provider for the given
Provider is not found.public Folder getFolder(URLName url) throws MessagingException
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.
url
- URLName that represents the desired folderNoSuchProviderException
- If a provider for the given
URLName is not found.MessagingException
- if the Folder could not be
located or created.getStore(URLName)
,
URLName
public Transport getTransport() throws NoSuchProviderException
mail.transport.protocol
property
specifies the desired protocol. If an appropriate Transport
object cannot be obtained, MessagingException is thrown.NoSuchProviderException
- If the provider is not found.public Transport getTransport(String protocol) throws NoSuchProviderException
protocol
- the Transport protocolNoSuchProviderException
- If provider for the given
protocol is not found.public Transport getTransport(URLName url) throws NoSuchProviderException
url
- URLName that represents the desired TransportNoSuchProviderException
- If a provider for the given
URLName is not found.URLName
public Transport getTransport(Provider provider) throws NoSuchProviderException
provider
- Transport Provider that will be instantiatedNoSuchProviderException
- If provider for the given
provider is not found.public Transport getTransport(Address address) throws NoSuchProviderException
address
- an address for which a Transport is neededNoSuchProviderException
- If provider for the
Address type is not foundAddress
public void setPasswordAuthentication(URLName url, PasswordAuthentication pw)
This is normally used only by the store or transport implementations to allow authentication information to be shared among multiple uses of a session.
url
- the URLNamepw
- the PasswordAuthentication to savepublic PasswordAuthentication getPasswordAuthentication(URLName url)
url
- the URLNamepublic PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName)
Connecting to <protocol> mail service on host <addr>, port <port>. <prompt> User Name: <defaultUserName> Password:
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.public Properties getProperties()
public String getProperty(String name)
name
- the property namepublic void addProvider(Provider provider)
provider
- the provider to addpublic void setProtocolForAddress(String addresstype, String protocol)
javamail.default.address.map
or
javamail.address.map
files or resources.addresstype
- type of addressprotocol
- name of protocolgetTransport(Address)
Copyright © 2016 JBoss by Red Hat. All rights reserved.