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.
getDebug
public boolean getDebug()
Get the debug setting for this session.
getDebugOut
public PrintStream getDebugOut()
Return the debug output stream.
getDefaultInstance
public static Session getDefaultInstance(Properties properties)
Get the "default" instance assuming no authenticator is required.
properties
- the session properties
getDefaultInstance
public static Session getDefaultInstance(Properties properties,
Authenticator authenticator)
Get the "default" session.
If there is not current "default", a new Session is created and installed as the default.
properties
- authenticator
-
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.
name
- the location of the folder
- the requested folder, or null if it is unavailable
getInstance
public static Session getInstance(Properties properties)
Create a new session initialized with the supplied properties with no authenticator.
properties
- the session properties
getInstance(java.util.Properties, Authenticator)
getInstance
public static Session getInstance(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
properties
- the session propertiesauthenticator
- an authenticator for callbacks to the user
getPasswordAuthentication
public PasswordAuthentication getPasswordAuthentication(URLName name)
Get the password authentication associated with a URL
- any authenticator for that url, or null if none
getProperties
public Properties getProperties()
Return the properties object for this Session; this is a live collection.
- the properties for the Session
getProperty
public String getProperty(String property)
Return the specified property.
property
- the property to get
- its value, or null if not present
getProvider
public Provider getProvider(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.
protocol
- the protocol to get a provider for
- a provider for that protocol
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.
getStore
public Store getStore()
throws NoSuchProviderException
Return a Store for the default protocol defined by the mail.store.protocol property.
- the store for the default protocol
getStore
public Store getStore(String protocol)
throws NoSuchProviderException
Return a Store for the specified protocol.
protocol
- the protocol to get a Store for
getTransport
public Transport getTransport()
throws NoSuchProviderException
Return a Transport for the default protocol specified by the
mail.transport.protocol
property.
getTransport
public Transport getTransport(String protocol)
throws NoSuchProviderException
Return a Transport for the specified protocol.
protocol
- the protocol to use
getTransport
public Transport getTransport(Address address)
throws NoSuchProviderException
Return a transport for the protocol associated with the type of this address.
address
- the address we are trying to deliver to
getTransport
public Transport getTransport(URLName name)
throws NoSuchProviderException
Return a transport for the protocol specified in the URL.
name
- the URL whose scheme specifies the protocol
requestPasswordAuthentication
public PasswordAuthentication requestPasswordAuthentication(InetAddress host,
int port,
String protocol,
String prompt,
String defaultUserName)
Call back to the application supplied authenticator to get the needed username add password.
host
- the host we are trying to connect to, may be nullport
- the port on that hostprotocol
- the protocol trying to be usedprompt
- a String to show as part of the prompt, may be nulldefaultUserName
- the default username, may be null
- the authentication information collected by the authenticator; may be null
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.
debug
- the debug setting
setDebugOut
public void setDebugOut(PrintStream out)
Set the output stream where debug information should be sent.
If set to null, System.out will be used.
out
- the stream to write debug information to
setPasswordAuthentication
public void setPasswordAuthentication(URLName name,
PasswordAuthentication authenticator)
Set the password authentication associated with a URL.
name
- the urlauthenticator
- the authenticator
setProvider
public void setProvider(Provider provider)
throws NoSuchProviderException
Make the supplied Provider the default for its protocol.
provider
- the new default Provider