Session

java.lang.Object
- javax.mail.Session

```
public final class Session
extends java.lang.Object
```
OK, so we have a final class in the API with a heck of a lot of implementation required... let's try and figure out what it is meant to do.
It is supposed to collect together properties and defaults so that they can be shared by multiple applications on a desktop; with process isolation and no real concept of shared memory, this seems challenging. These properties and defaults rely on system properties, making management in a app server harder, and on resources loaded from "mail.jar" which may lead to skew between differnet independent implementations of this API.

Version:

$Rev: 509956 $ $Date: 2007-02-21 11:07:05 +0100 (Wed, 21 Feb 2007) $

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addProvider(Provider provider)` Add a provider to the Session managed provider list.
`boolean`	`getDebug()` Get the debug setting for this session.
`java.io.PrintStream`	`getDebugOut()` Return the debug output stream.
`static Session`	`getDefaultInstance(java.util.Properties properties)` Get the "default" instance assuming no authenticator is required.
`static Session`	`getDefaultInstance(java.util.Properties properties, Authenticator authenticator)` Get the "default" session.
`Folder`	`getFolder(URLName name)` Return a closed folder for the supplied URLName, or null if it cannot be obtained.
`static Session`	`getInstance(java.util.Properties properties)` Create a new session initialized with the supplied properties with no authenticator.
`static Session`	`getInstance(java.util.Properties properties, Authenticator authenticator)` Create a new session initialized with the supplied properties which uses the supplied authenticator.
`PasswordAuthentication`	`getPasswordAuthentication(URLName name)` Get the password authentication associated with a URL
`java.util.Properties`	`getProperties()` Return the properties object for this Session; this is a live collection.
`java.lang.String`	`getProperty(java.lang.String property)` Return the specified property.
`Provider`	`getProvider(java.lang.String protocol)` Return the provider for a specific protocol.
`Provider[]`	`getProviders()` Return the list of providers available to this application.
`Store`	`getStore()` Return a Store for the default protocol defined by the mail.store.protocol property.
`Store`	`getStore(Provider provider)` Return the Store specified by the given provider.
`Store`	`getStore(java.lang.String protocol)` Return a Store for the specified protocol.
`Store`	`getStore(URLName url)` Return a Store for the protocol specified in the given URL
`Transport`	`getTransport()` Return a Transport for the default protocol specified by the `mail.transport.protocol` property.
`Transport`	`getTransport(Address address)` Return a transport for the protocol associated with the type of this address.
`Transport`	`getTransport(Provider provider)` Return the Transport specified by a Provider
`Transport`	`getTransport(java.lang.String protocol)` Return a Transport for the specified protocol.
`Transport`	`getTransport(URLName name)` Return a transport for the protocol specified in the URL.
`PasswordAuthentication`	`requestPasswordAuthentication(java.net.InetAddress host, int port, java.lang.String protocol, java.lang.String prompt, java.lang.String defaultUserName)` Call back to the application supplied authenticator to get the needed username add password.
`void`	`setDebug(boolean debug)` Enable debugging for this session.
`void`	`setDebugOut(java.io.PrintStream out)` Set the output stream where debug information should be sent.
`void`	`setPasswordAuthentication(URLName name, PasswordAuthentication authenticator)` Set the password authentication associated with a URL.
`void`	`setProtocolForAddress(java.lang.String addressType, java.lang.String protocol)` Add a mapping between an address type and a protocol used to process that address type.
`void`	`setProvider(Provider provider)` Make the supplied Provider the default for its protocol.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstance
```
public static Session getInstance(java.util.Properties properties,
                                  Authenticator authenticator)
```
    Create a new session initialized with the supplied properties which uses the supplied authenticator. Clients should ensure the properties listed in Appendix A of the JavaMail specification are set as the defaults are unlikey to work in most scenarios; particular attention should be given to:
    - mail.store.protocol
    - mail.transport.protocol
    - mail.host
    - mail.user
    - mail.from
    Parameters:
    
    properties - the session properties
    
    authenticator - an authenticator for callbacks to the user
    
    Returns:
    
    a new session
  - getInstance
```
public static Session getInstance(java.util.Properties properties)
```
    Create a new session initialized with the supplied properties with no authenticator.
    
    Parameters:
    
    properties - the session properties
    
    Returns:
    
    a new session
    
    See Also:
    
    getInstance(java.util.Properties, Authenticator)
  - getDefaultInstance
```
public static Session getDefaultInstance(java.util.Properties properties)
```
    Get the "default" instance assuming no authenticator is required.
    
    Parameters:
    
    properties - the session properties
    
    Returns:
    
    if "default" session
    
    Throws:
    
    java.lang.SecurityException - if the does not have permission to access the default session
  - getDefaultInstance
```
public static Session getDefaultInstance(java.util.Properties properties,
                                         Authenticator authenticator)
```
    Get the "default" session. If there is not current "default", a new Session is created and installed as the default.
    
    Parameters:
    
    properties -
    
    authenticator -
    
    Returns:
    
    if "default" session
    
    Throws:
    
    java.lang.SecurityException - if the does not have permission to access the default session
  - setDebug
```
public void setDebug(boolean debug)
```
    Enable debugging for this session. Debugging can also be enabled by setting the "mail.debug" property to true when the session is being created.
    
    Parameters:
    
    debug - the debug setting
  - getDebug
```
public boolean getDebug()
```
    Get the debug setting for this session.
    
    Returns:
    
    the debug setting
  - setDebugOut
```
public void setDebugOut(java.io.PrintStream out)
```
    Set the output stream where debug information should be sent. If set to null, System.out will be used.
    
    Parameters:
    
    out - the stream to write debug information to
  - getDebugOut
```
public java.io.PrintStream getDebugOut()
```
    Return the debug output stream.
    
    Returns:
    
    the debug output stream
  - getProviders
```
public Provider[] getProviders()
```
    Return the list of providers available to this application. This method searches for providers that are defined in the javamail.providers and javamail.default.providers resources available through the current context classloader, or if that is not available, the classloader that loaded this class.
    As searching for providers is potentially expensive, this implementation maintains a WeakHashMap of providers indexed by ClassLoader.
    
    Returns:
    
    an array of providers
  - getProvider
```
public Provider getProvider(java.lang.String protocol)
                     throws NoSuchProviderException
```
    Return the provider for a specific protocol. This implementation initially looks in the Session properties for an property with the name "mail..class"; if found it attempts to create an instance of the class named in that property throwing a NoSuchProviderException if the class cannot be loaded. If this property is not found, it searches the providers returned by getProviders() for a entry for the specified protocol.
    
    Parameters:
    
    protocol - the protocol to get a provider for
    
    Returns:
    
    a provider for that protocol
    
    Throws:
    
    NoSuchProviderException
  - setProvider
```
public void setProvider(Provider provider)
                 throws NoSuchProviderException
```
    Make the supplied Provider the default for its protocol.
    
    Parameters:
    
    provider - the new default Provider
    
    Throws:
    
    NoSuchProviderException
  - getStore
```
public Store getStore()
               throws NoSuchProviderException
```
    Return a Store for the default protocol defined by the mail.store.protocol property.
    
    Returns:
    
    the store for the default protocol
    
    Throws:
    
    NoSuchProviderException
  - getStore
```
public Store getStore(java.lang.String protocol)
               throws NoSuchProviderException
```
    Return a Store for the specified protocol.
    
    Parameters:
    
    protocol - the protocol to get a Store for
    
    Returns:
    
    a Store
    
    Throws:
    
    NoSuchProviderException - if no provider is defined for the specified protocol
  - getStore
```
public Store getStore(URLName url)
               throws NoSuchProviderException
```
    Return a Store for the protocol specified in the given URL
    
    Parameters:
    
    url - the URL of the Store
    
    Returns:
    
    a Store
    
    Throws:
    
    NoSuchProviderException - if no provider is defined for the specified protocol
  - getStore
```
public Store getStore(Provider provider)
               throws NoSuchProviderException
```
    Return the Store specified by the given provider.
    
    Parameters:
    
    provider - the provider to create from
    
    Returns:
    
    a Store
    
    Throws:
    
    NoSuchProviderException - if there was a problem creating the Store
  - getFolder
```
public Folder getFolder(URLName name)
                 throws MessagingException
```
    Return a closed folder for the supplied URLName, or null if it cannot be obtained.
    The scheme portion of the URL is used to locate the Provider and create the Store; the returned Store is then used to obtain the folder.
    
    Parameters:
    
    name - the location of the folder
    
    Returns:
    
    the requested folder, or null if it is unavailable
    
    Throws:
    
    NoSuchProviderException - if there is no provider
    
    MessagingException - if there was a problem accessing the Store
  - getTransport
```
public Transport getTransport()
                       throws NoSuchProviderException
```
    Return a Transport for the default protocol specified by the mail.transport.protocol property.
    
    Returns:
    
    a Transport
    
    Throws:
    
    NoSuchProviderException
  - getTransport
```
public Transport getTransport(java.lang.String protocol)
                       throws NoSuchProviderException
```
    Return a Transport for the specified protocol.
    
    Parameters:
    
    protocol - the protocol to use
    
    Returns:
    
    a Transport
    
    Throws:
    
    NoSuchProviderException
  - getTransport
```
public Transport getTransport(URLName name)
                       throws NoSuchProviderException
```
    Return a transport for the protocol specified in the URL.
    
    Parameters:
    
    name - the URL whose scheme specifies the protocol
    
    Returns:
    
    a Transport
    
    Throws:
    
    NoSuchProviderException
  - getTransport
```
public Transport getTransport(Address address)
                       throws NoSuchProviderException
```
    Return a transport for the protocol associated with the type of this address.
    
    Parameters:
    
    address - the address we are trying to deliver to
    
    Returns:
    
    a Transport
    
    Throws:
    
    NoSuchProviderException
  - getTransport
```
public Transport getTransport(Provider provider)
                       throws NoSuchProviderException
```
    Return the Transport specified by a Provider
    
    Parameters:
    
    provider - the defining Provider
    
    Returns:
    
    a Transport
    
    Throws:
    
    NoSuchProviderException
  - setPasswordAuthentication
```
public void setPasswordAuthentication(URLName name,
                                      PasswordAuthentication authenticator)
```
    Set the password authentication associated with a URL.
    
    Parameters:
    
    name - the url
    
    authenticator - the authenticator
  - getPasswordAuthentication
```
public PasswordAuthentication getPasswordAuthentication(URLName name)
```
    Get the password authentication associated with a URL
    
    Parameters:
    
    name - the URL
    
    Returns:
    
    any authenticator for that url, or null if none
  - requestPasswordAuthentication
```
public PasswordAuthentication requestPasswordAuthentication(java.net.InetAddress host,
                                                            int port,
                                                            java.lang.String protocol,
                                                            java.lang.String prompt,
                                                            java.lang.String defaultUserName)
```
    Call back to the application supplied authenticator to get the needed username add password.
    
    Parameters:
    
    host - the host we are trying to connect to, may be null
    
    port - the port on that host
    
    protocol - the protocol trying to be used
    
    prompt - a String to show as part of the prompt, may be null
    
    defaultUserName - the default username, may be null
    
    Returns:
    
    the authentication information collected by the authenticator; may be null
  - getProperties
```
public java.util.Properties getProperties()
```
    Return the properties object for this Session; this is a live collection.
    
    Returns:
    
    the properties for the Session
  - getProperty
```
public java.lang.String getProperty(java.lang.String property)
```
    Return the specified property.
    
    Parameters:
    
    property - the property to get
    
    Returns:
    
    its value, or null if not present
  - addProvider
```
public void addProvider(Provider provider)
```
    Add a provider to the Session managed provider list.
    
    Parameters:
    
    provider - The new provider to add.
  - setProtocolForAddress
```
public void setProtocolForAddress(java.lang.String addressType,
                                  java.lang.String protocol)
```
    Add a mapping between an address type and a protocol used to process that address type.
    
    Parameters:
    
    addressType - The address type identifier.
    
    protocol - The protocol name mapping.

Class Session

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstance

getDefaultInstance

getDefaultInstance

setDebug

getDebug

setDebugOut

getDebugOut

getProviders

getProvider

setProvider

getStore

getStore

getStore

getStore

getFolder

getTransport

getTransport

getTransport

getTransport

getTransport

setPasswordAuthentication

getPasswordAuthentication

requestPasswordAuthentication

getProperties

getProperty

addProvider

setProtocolForAddress