Class Session
- java.lang.Object
-
- javax.mail.Session
-
public final class Session extends java.lang.Object
A session represents the context of a messaging transaction. It provides a repository of configuration information in the form of properties.- Version:
- 1.4
- Author:
- Andrew Selkirk, Chris Burdess, Nic Ferrier
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addProvider(Provider provider)
Adds the specified provider to the session.boolean
getDebug()
Get the debug setting for this Session.java.io.PrintStream
getDebugOut()
Returns the stream to be used for debugging output.static Session
getDefaultInstance(java.util.Properties props)
Get the default Session object.static Session
getDefaultInstance(java.util.Properties props, Authenticator authenticator)
Returns the default session.Folder
getFolder(URLName url)
Get a closed Folder object for the given URLName.static Session
getInstance(java.util.Properties props)
Returns a new Session.static Session
getInstance(java.util.Properties props, Authenticator authenticator)
Returns a new session.PasswordAuthentication
getPasswordAuthentication(URLName url)
Return any saved PasswordAuthentication for this(store or transport) URLName.java.util.Properties
getProperties()
Returns the Properties object associated with this Session.java.lang.String
getProperty(java.lang.String name)
Returns the value of the specified property.Provider
getProvider(java.lang.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(java.lang.String protocol)
Get a Store object that implements the specified protocol.Store
getStore(Provider provider)
Get an instance of the store specified by Provider.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 protocol.Transport
getTransport(java.lang.String protocol)
Get a Transport object that implements the specified protocol.Transport
getTransport(Address address)
Get a Transport object that can transport a Message to the specified address type.Transport
getTransport(Provider provider)
Get an instance of the transport specified in the Provider.Transport
getTransport(URLName url)
Get a Transport object for the given URLName.PasswordAuthentication
requestPasswordAuthentication(java.net.InetAddress address, int port, java.lang.String protocol, java.lang.String prompt, java.lang.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(java.io.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(java.lang.String addressType, java.lang.String protocol)
Sets the default transport protocol for the given address 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 Detail
-
getInstance
public static Session getInstance(java.util.Properties props, Authenticator authenticator)
Returns a new session.- Parameters:
props
- a properties object holding relevant properties. It is expected that the client supplies values for the properties listed in Appendix A of the JavaMail spec (particularlymail.store.protocol
,mail.transport.protocol
,mail.host
,mail.user
, andmail.from
) as the defaults are unlikely to work in all cases.authenticator
- an authenticator used to call back to the application when a user name and password is needed.
-
getInstance
public static Session getInstance(java.util.Properties props)
Returns a new Session.- Parameters:
props
- a properties object holding relevant properties. It is expected that the client supplies values for the properties listed in Appendix A of the JavaMail spec (particularlymail.store.protocol
,mail.transport.protocol
,mail.host
,mail.user
, andmail.from
) as the defaults are unlikely to work in all cases.
-
getDefaultInstance
public static Session getDefaultInstance(java.util.Properties props, Authenticator authenticator)
Returns the default session. If a default has not yet been setup, a new session 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.
- 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 JavaMail spec (particularlymail.store.protocol
,mail.transport.protocol
,mail.host
,mail.user
, andmail.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.
-
getDefaultInstance
public static Session getDefaultInstance(java.util.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 object that hold relevant properties. It is expected that the client supplies values for the properties listed in Appendix A of the JavaMail spec(particularlymail.store.protocol
,mail.transport.protocol
,mail.host
,mail.user
, andmail.from
) as the defaults are unlikely to work in all cases.
-
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 affect on themail.debug
property.
-
getDebug
public boolean getDebug()
Get the debug setting for this Session.
-
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.
-
getProvider
public Provider getProvider(java.lang.String protocol) throws NoSuchProviderException
Returns the default Provider for the protocol specified. Checksmail.<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)NoSuchProviderException
- If a provider for the given protocol is not found.- Throws:
NoSuchProviderException
-
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.- Throws:
NoSuchProviderException
-
getStore
public Store getStore() throws NoSuchProviderException
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- Throws:
NoSuchProviderException
-
getStore
public Store getStore(java.lang.String protocol) throws NoSuchProviderException
Get a Store object that implements the specified protocol. If an appropriate Store object cannot be obtained, NoSuchProviderException is thrown.- Throws:
NoSuchProviderException
-
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.- Parameters:
url
- URLName that represents the desired Store- Throws:
NoSuchProviderException
-
getStore
public Store getStore(Provider provider) throws NoSuchProviderException
Get an instance of the store specified by Provider. Instantiates the store and returns it.- Parameters:
provider
- Store Provider that will be instantiated- Throws:
NoSuchProviderException
-
getTransport
public Transport getTransport() throws NoSuchProviderException
Get a Transport object that implements this user's desired Transport protocol. Themail.transport.protocol
property specifies the desired protocol. If an appropriate Transport object cannot be obtained, MessagingException is thrown.- Throws:
NoSuchProviderException
- If the provider is not found.
-
getTransport
public Transport getTransport(java.lang.String protocol) throws NoSuchProviderException
Get a Transport object that implements the specified protocol. If an appropriate Transport object cannot be obtained, null is returned.- Throws:
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.- Parameters:
url
- URLName that represents the desired Transport- Throws:
NoSuchProviderException
- If the provider is not found.
-
getTransport
public Transport getTransport(Provider provider) throws NoSuchProviderException
Get an instance of the transport specified in the Provider. Instantiates the transport and returns it.- Throws:
NoSuchProviderException
- If the provider is not found.
-
getTransport
public Transport getTransport(Address address) throws NoSuchProviderException
Get a Transport object that can transport a Message to the specified address type.- Throws:
NoSuchProviderException
- If the provider is not found.
-
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.
- Parameters:
url
- URLName that represents the desired folderMessagingException
- if the Folder could not be located or created.- Throws:
NoSuchProviderException
- If a provider for the given URLName is not found.MessagingException
-
setPasswordAuthentication
public void setPasswordAuthentication(URLName url, PasswordAuthentication pw)
Save a PasswordAuthentication for this(store or transport) URLName. Ifpw
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.
-
getPasswordAuthentication
public PasswordAuthentication getPasswordAuthentication(URLName url)
Return any saved PasswordAuthentication for this(store or transport) URLName. Normally used only by store or transport implementations.
-
requestPasswordAuthentication
public PasswordAuthentication requestPasswordAuthentication(java.net.InetAddress address, int port, java.lang.String protocol, java.lang.String prompt, java.lang.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: - Parameters:
addr
- InetAddress of the host. may be null.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.
-
getProperties
public java.util.Properties getProperties()
Returns the Properties object associated with this Session.
-
getProperty
public java.lang.String getProperty(java.lang.String name)
Returns the value of the specified property. Returns null if this property does not exist.
-
setDebugOut
public void setDebugOut(java.io.PrintStream out)
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
property, will always be sent toSystem.out
.- Parameters:
out
- the PrintStream to use for debugging output- Since:
- JavaMail 1.3
-
getDebugOut
public java.io.PrintStream getDebugOut()
Returns the stream to be used for debugging output. If no stream has been set,System.out
is returned.- Since:
- JavaMail 1.3
-
addProvider
public void addProvider(Provider provider)
Adds the specified provider to the session.- Parameters:
provider
- the new provider- Since:
- JavaMail 1.4
-
setProtocolForAddress
public void setProtocolForAddress(java.lang.String addressType, java.lang.String protocol)
Sets the default transport protocol for the given address type.- Parameters:
addressType
- the type of address, e.g. "rfc822"protocol
- the transport protocol to use- Since:
- JavaMail 1.4
-
-