*
* 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.providersjavamail.address.map and
* javamail.default.address.map
* Each javamail.X resource file is searched for using three
* methods in the following order:
*
java.home/conf/javamail.XMETA-INF/javamail.XMETA-INF/javamail.default.X* (Where java.home is the value of the "java.home" System property and * conf is the directory named "conf" if it exists, otherwise the * directory named "lib"; the "conf" directory was introduced in JDK 1.9.) *
* The first method allows the user to include their own version of the resource
* file by placing it in the conf 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 and should not be supplied by users.
*
*
* 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; **
* * The current implementation also supports configuring providers using the Java * SE {@link java.util.ServiceLoader ServiceLoader} mechanism. When creating * your own provider, create a {@link Provider} subclass, for example: * *
* package com.example;
*
* import javax.mail.Provider;
*
* public class MyProvider extends Provider {
* public MyProvider() {
* super(Provider.Type.STORE, "myprot", MyStore.class.getName(), "Example", null);
* }
* }
*
*
* Then include a file named META-INF/services/javax.mail.Provider
* in your jar file that lists the name of your Provider class:
*
* * com.example.MyProvider **
*
* 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 ** * @author John Mani * @author Bill Shannon * @author Max Spivak */ public final class Session { /** * Get a new Session object. * * @param props Properties object that hold relevant properties.
* * 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.
*
* @param props Properties object. Used only if a new Session object is
* created.
* 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.
* @param authenticator Authenticator object. Used only if a new Session object
* is created. Otherwise, it must match the Authenticator
* used to create the Session.
* @return the default Session object
*/
public static synchronized Session getDefaultInstance(Properties props, Authenticator authenticator) {
return null;
}
/**
* 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.
*
* @param props Properties object. Used only if a new Session object is
* created.
* 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.
* @return the default Session object
* @since JavaMail 1.2
*/
public static Session getDefaultInstance(Properties props) {
return null;
}
}