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.
getDebug
public boolean getDebug()
Get the debug setting for this Session.
getDebugOut
public PrintStream getDebugOut()
Returns the stream to be used for debugging output. If no stream has
been set, System.out is returned.
- JavaMail 1.3
getDefaultInstance
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.
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.
getDefaultInstance
public static 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.
In JDK 1.2, additional security Permission objects may be used to control
access to the default session.
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.
getFolder
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.
url - URLName that represents the desired folder
getInstance
public static Session getInstance(Properties props)
Get a new Session object.
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.
getInstance
public static Session getInstance(Properties props,
Authenticator authenticator) Get a new Session object.
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.
getPasswordAuthentication
public PasswordAuthentication getPasswordAuthentication(URLName url)
Return any saved PasswordAuthentication for this(store or transport)
URLName. Normally used only by store or transport implementations.
getProperties
public Properties getProperties()
Returns the Properties object associated with this Session.
getProperty
public String getProperty(String name)
Returns the value of the specified property.
Returns null if this property does not exist.
getProvider
public 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
protocol - Configured protocol(i.e. smtp, imap, etc)
getProviders
public 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.
getStore
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
getStore
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.
getStore
public Store getStore(Provider provider)
throws NoSuchProviderException Get an instance of the store specified by Provider.
Instantiates the store and returns it.
provider - Store Provider that will be instantiated
getStore
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.
url - URLName that represents the desired Store
getTransport
public Transport getTransport()
throws NoSuchProviderException Get a Transport object that implements this user's desired Transport
protocol.
The 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.
getTransport
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.
NoSuchProviderException - If the provider is not found.
getTransport
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.
url - URLName that represents the desired Transport
NoSuchProviderException - If the provider is not found.
requestPasswordAuthentication
public PasswordAuthentication requestPasswordAuthentication(InetAddress address,
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 mail service on host , port .
User Name:
Password:
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.
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 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.
setDebugOut
public 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 property, will always be
sent to System.out.
out - the PrintStream to use for debugging output
- JavaMail 1.3
setPasswordAuthentication
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.
setProvider
public 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.