javax.mail
クラス Session

java.lang.Object
  上位を拡張 javax.mail.Session

public final class Session
extends Object

Session クラスはメールセッションを表し、サブクラス化されません。 Session クラスは、メール API により使用されるプロパティとデフォルトを収集します。 1 つのデフォルトセッションを、デスクトップ上の複数のアプリケーションにより共有可能です。 共有されないセッションを作成する事もできます。

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:

Each javamail.X resource file is searched for using three methods in the following order:

  1. java.home/lib/javamail.X
  2. META-INF/javamail.X
  3. META-INF/javamail.default.X

The first method allows the user to include their own version of the resource file by placing it in the lib 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.

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. JDK 1.1 has a limitation that the number of files of each name that will be found in the CLASSPATH is limited to one. However, this only affects method two, above; method one is loaded from a specific location (if allowed by the SecurityManager) and method three uses a different name to ensure that the default resource file is always loaded successfully. J2SE 1.2 and later are not limited to one file of a given name.

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.

Attribute Names in Providers Files
NameDescription
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=Sun Microsystems, Inc.;
 protocol=smtp; type=transport; class=com.sun.mail.smtp.SMTPTransport; vendor=Sun Microsystems, Inc.;
 

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
 


メソッドの概要
 void addProvider(Provider provider)
          Add a provider to the session.
 boolean getDebug()
          この Session のデバッグ設定を取得します。
 PrintStream getDebugOut()
          Returns the stream to be used for debugging output.
static Session getDefaultInstance(Properties props)
          デフォルトの Session オブジェクトを取得します。
static Session getDefaultInstance(Properties props, Authenticator authenticator)
          デフォルトの Session オブジェクトを取得します。
 Folder getFolder(URLName url)
          指定された URLName の閉じた Folder オブジェクトを取得します。
static Session getInstance(Properties props)
          新しい Session オブジェクトを取得します。
static Session getInstance(Properties props, Authenticator authenticator)
          新しい Session オブジェクトを取得します。
 PasswordAuthentication getPasswordAuthentication(URLName url)
          この (ストア又はトランスポート) URLName の任意の保存された PasswordAuthentication を返します。
 Properties getProperties()
          この Session に関連付けられた Properties オブジェクトを返します。
 String getProperty(String name)
          指定されたプロパティの値を返します。
 Provider getProvider(String protocol)
          指定されたプロトコルのデフォルトの Provider を返します。
 Provider[] getProviders()
          このメソッドは、このアプリケーションで使用可能な ClassLoader によりロード できる javamail.
 Store getStore()
          このユーザが望む Store プロトコルを実装する Store オブジェクトを取得します。
 Store getStore(Provider provider)
          Provider により指定されたストアのインスタンスを取得します。
 Store getStore(String protocol)
          指定されたプロトコルを実装する Store オブジェクトを取得します。
 Store getStore(URLName url)
          指定された URLName の Store オブジェクトを取得します。
 Transport getTransport()
          このユーザが望む Transport プロトコルを実装する Transport オブジェクトを取得します。
 Transport getTransport(Address address)
          Message を指定されたアドレス型にトランスポート可能な Transport オブジェクトを取得します。
 Transport getTransport(Provider provider)
          Provider 中に指定されたトランスポートのインスタンスを取得します。
 Transport getTransport(String protocol)
          指定されたプロトコルを実装する Transport オブジェクトを取得します。
 Transport getTransport(URLName url)
          指定された URLName の Transport オブジェクトを取得します。
 PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName)
          必要なユーザ名とパスワードを取得する為に、アプリケーションにコールバックします。
 void setDebug(boolean debug)
          この Session のデバッグ設定を行います。
 void setDebugOut(PrintStream out)
          Set the stream to be used for debugging output for this session.
 void setPasswordAuthentication(URLName url, PasswordAuthentication pw)
          この (ストア又はトランスポート) URLName の PasswordAuthentication を保存します。
 void setProtocolForAddress(String addresstype, String protocol)
          Set the default transport protocol to use for addresses of the specified type.
 void setProvider(Provider provider)
          渡された Provider を、以前の全ての値をオーバーライドすることにより、 Provider.protocol 中のプロトコルに対するデフォルトの実装として設定します。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

メソッドの詳細

getInstance

public static Session getInstance(Properties props,
                                  Authenticator authenticator)
新しい Session オブジェクトを取得します。

パラメータ:
props - 関連プロパティを保持する Properties オブジェクト
クライアントは、JavaMail 仕様の付録 A に記載されるプロパティ (特に mail.store.protocol、 mail.transport.protocol、mail.host、mail.user、及び mail.from) の値を供給しなければなりません。 これは、デフォルトが全ての場合に機能するとは限らない為です。
authenticator - ユーザ名とパスワードが必要な場合、 アプリケーションにコールバックする為に使用される Authenticator オブジェクト
戻り値:
新しい Session オブジェクト
関連項目:
Authenticator

getInstance

public static Session getInstance(Properties props)
新しい Session オブジェクトを取得します。

パラメータ:
props - 関連プロパティを保持する Properties オブジェクト
クライアントは、JavaMail 仕様の付録 A に記載されるプロパティ (特に mail.store.protocol、 mail.transport.protocol、mail.host、mail.user、及び mail.from) の値を供給しなければなりません。 これは、デフォルトが全ての場合に機能するとは限らない為です。
戻り値:
新しい Session オブジェクト
導入されたバージョン:
JavaMail 1.2

getDefaultInstance

public static Session getDefaultInstance(Properties props,
                                         Authenticator authenticator)
デフォルトの Session オブジェクトを取得します。 デフォルトがまだ設定されていない場合、新しい Session オブジェクトが作成され、 デフォルトとしてインストールされます。

デフォルトのセッションは同じ Java 仮想マシン中で実行する全てのコードで使用できる可能性があり、 セッションはユーザ名やパスワードといったセキュリティ上機密の情報を含む事があるので、 デフォルトのセッションへのアクセスは制限されます。 呼び出し側により作成されなければならない Authenticator オブジェクトは、 アクセス権限をチェックする為に間接的に使用されます。 セッションが作成される際に渡される Authenticator オブジェクトは、 デフォルトのセッションを取得する為の後続要求に渡される Authenticator オブジェクトと比較されます。 2 つのオブジェクトが同じ場合、又は同じ ClassLoader の場合、要求は許可されます。 そうでない場合は拒否されます。

セッションを作成する為に使用される Authenticator オブジェクトが null の場合、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.

JDK 1.2 では、デフォルトのセッションへのアクセスを制御する為に、 追加のセキュリティ Permission オブジェクトを使用できます。

パラメータ:
props - Properties オブジェクト。新しい Session オブジェクトが作成される場合にのみ使用されます。
クライアントは、JavaMail 仕様の付録 A に記載されるプロパティ (特に mail.store.protocol、 mail.transport.protocol、mail.host、mail.user、及び mail.from) の値を供給しなければなりません。 これは、デフォルトが全ての場合に機能するとは限らない為です。
authenticator - Authenticator オブジェクト。 新しい Session オブジェクトが作成される場合にのみ使用されます。 そうでない場合、Session を作成する為に使用される Authenticator に一致しなければなりません。
戻り値:
デフォルトの Session オブジェクト

getDefaultInstance

public static Session getDefaultInstance(Properties props)
デフォルトの Session オブジェクトを取得します。 デフォルトがまだ設定されていない場合、新しい Session オブジェクトが作成され、 デフォルトとしてインストールされます。

Authenticator なしで作成されたデフォルトのセッションは、 同じ Java 仮想マシンで実行中の全てのコードが使用可能であり、 セッションにはユーザ名やパスワードといったセキュリティ上機密の情報が含まれる場合があります。

パラメータ:
props - Properties オブジェクト。新しい Session オブジェクトが作成される場合にのみ使用されます。
クライアントは、JavaMail 仕様の付録 A に記載されるプロパティ (特に mail.store.protocol、 mail.transport.protocol、mail.host、mail.user、及び mail.from) の値を供給しなければなりません。 これは、デフォルトがすべての場合に機能するとは限らない為です。
戻り値:
デフォルトの Session オブジェクト
導入されたバージョン:
JavaMail 1.2

setDebug

public void setDebug(boolean debug)
この Session のデバッグ設定を行います。

Session を作成した後にしかデバッグ設定を有効にできない為、 Session コンストラクタ中のデバッギングを有効にするには、 コンストラクタに渡される Properties オブジェクト 中の mail.debug プロパティを true に設定します。 mail.debug プロパティの値は、Session 単位のデバッギングフラグを初期化する為に使用されます。 setDebug メソッドに対する後続の呼び出しは、Session 単位のデバッギングフラグを操作し、 mail.debug プロパティに影響を与えません。

パラメータ:
debug - デバッグ設定

getDebug

public boolean getDebug()
この Session のデバッグ設定を取得します。

戻り値:
現在のデバッグ設定

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 system property, will always be sent to System.out.

パラメータ:
out - the PrintStream to use for debugging output
導入されたバージョン:
JavaMail 1.3

getDebugOut

public PrintStream getDebugOut()
Returns the stream to be used for debugging output. If no stream has been set, System.out is returned.

戻り値:
the PrintStream to use for debugging output
導入されたバージョン:
JavaMail 1.3

getProviders

public Provider[] getProviders()
このメソッドは、このアプリケーションで使用可能な ClassLoader によりロード できる javamail.[default.]providers ファイル経由でインストールされた全ての実装の配列を返します。

戻り値:
設定されたプロバイダの配列

getProvider

public Provider getProvider(String protocol)
                     throws NoSuchProviderException
指定されたプロトコルのデフォルトの Provider を返します。 まず mail.<protocol>.class プロパティをチェックし、存在する場合は、 この実装に関連付けられた Provider を返します。 存在しない場合は、設定ファイル中に最初に現れる Provider を返します。 プロトコルの実装が見つからない場合は、NoSuchProviderException をスローします。

パラメータ:
protocol - 設定されたプロトコル (smtp、imap 等)
戻り値:
指定されたプロトコルについて現在設定されている Provider
例外:
NoSuchProviderException - 指定されたプロトコルのプロバイダが見つからない場合

setProvider

public void setProvider(Provider provider)
                 throws NoSuchProviderException
渡された Provider を、以前の全ての値をオーバーライドすることにより、 Provider.protocol 中のプロトコルに対するデフォルトの実装として設定します。

パラメータ:
provider - プロトコルのデフォルトとして設定される現在設定されている Provider
例外:
NoSuchProviderException - 渡されたプロバイダが無効の場合

getStore

public Store getStore()
               throws NoSuchProviderException
このユーザが望む Store プロトコルを実装する Store オブジェクトを取得します。 mail.store.protocol プロパティは希望するプロトコルを指定します。 適切な Store オブジェクトが取得されない場合、NoSuchProviderException がスローされます。

戻り値:
Store オブジェクト
例外:
NoSuchProviderException - 指定されたプロトコルのプロバイダが見つからない場合

getStore

public Store getStore(String protocol)
               throws NoSuchProviderException
指定されたプロトコルを実装する Store オブジェクトを取得します。 適切な Store オブジェクトが取得できない場合、NoSuchProviderException がスローされます。

パラメータ:
protocol -
戻り値:
Store オブジェクト
例外:
NoSuchProviderException - 指定されたプロトコルのプロバイダが見つからない場合

getStore

public Store getStore(URLName url)
               throws NoSuchProviderException
指定された URLName の Store オブジェクトを取得します。 要求された Store オブジェクトが取得できない場合、NoSuchProviderException がスローされます。 Store プロトコルの特定には、URL 文字列の "scheme" 部分 (RFC 1738 を参照) が使用されます。

パラメータ:
url - 希望する Store を表す URLName
戻り値:
閉じた Store オブジェクト
例外:
NoSuchProviderException - 指定された URLName のプロバイダが見つからない場合
関連項目:
getFolder(URLName), URLName

getStore

public Store getStore(Provider provider)
               throws NoSuchProviderException
Provider により指定されたストアのインスタンスを取得します。 ストアをインスタンス化して返します。

パラメータ:
provider - インスタンス化されるストアの Provider
戻り値:
インスタンス化された Store
例外:
NoSuchProviderException - 指定された Provider のプロバイダが見つからない場合

getFolder

public Folder getFolder(URLName url)
                 throws MessagingException
指定された URLName の閉じた Folder オブジェクトを取得します。 要求した Folder オブジェクトが取得できない場合、null が返されます。

Store プロトコルの特定には、URL 文字列の "scheme" 部分 (RFC 1738 を参照) が使用されます。 URL 文字列の残り (つまり、RFC 1738 で規定される "schemepart") は Store により、 プロトコルに依存した方法で、適切な Folder オブジェクトの特定とインスタンス化に使用されます。

RFC 1738 は、IP ベースのプロトコル (IMAP4、POP3 等) の "schemepart" に関する構文も指定しています。 IP ベースのメール Store のプロバイダは、Folder を参照するための構文を実装しなければなりません。

パラメータ:
url - 希望する Folder を表す URLName
戻り値:
Folder
例外:
NoSuchProviderException - 指定された URLName のプロバイダが見つからない場合
MessagingException - Folder を特定又は作成できない場合
関連項目:
getStore(URLName), URLName

getTransport

public Transport getTransport()
                       throws NoSuchProviderException
このユーザが望む Transport プロトコルを実装する Transport オブジェクトを取得します。 mail.transport.protocol プロパティは希望するプロトコルを指定します。 適切な Transport オブジェクトが取得できない場合、MessagingException がスローされます。

戻り値:
Transport オブジェクト
例外:
NoSuchProviderException - プロバイダが見つからない場合

getTransport

public Transport getTransport(String protocol)
                       throws NoSuchProviderException
指定されたプロトコルを実装する Transport オブジェクトを取得します。 適切な Transport オブジェクトが取得できない場合、null が返されます。

戻り値:
Transport オブジェクト
例外:
NoSuchProviderException - 指定されたプロトコルのプロバイダが見つからない場合

getTransport

public Transport getTransport(URLName url)
                       throws NoSuchProviderException
指定された URLName の Transport オブジェクトを取得します。 要求された Transport オブジェクトが取得できない場合、NoSuchProviderException がスローされます。 Transport プロトコルの特定には、URL 文字列の "scheme" 部分 (RFC 1738 を参照) が使用されます。

パラメータ:
url - 希望する Transport を表す URLName
戻り値:
閉じた Transport オブジェクト
例外:
NoSuchProviderException - 指定された URLName のプロバイダが見つからない場合
関連項目:
URLName

getTransport

public Transport getTransport(Provider provider)
                       throws NoSuchProviderException
Provider 中に指定されたトランスポートのインスタンスを取得します。 トランスポートをインスタンス化して返します。

パラメータ:
provider - インスタンス化されるトランスポートの Provider
戻り値:
インスタンス化された Transport
例外:
NoSuchProviderException - 指定されたプロバイダのプロバイダが見つからない場合

getTransport

public Transport getTransport(Address address)
                       throws NoSuchProviderException
Message を指定されたアドレス型にトランスポート可能な Transport オブジェクトを取得します。

パラメータ:
address -
戻り値:
Transport オブジェクト
例外:
NoSuchProviderException - Address 型のプロバイダが見つからない場合
関連項目:
Address

setPasswordAuthentication

public void setPasswordAuthentication(URLName url,
                                      PasswordAuthentication pw)
この (ストア又はトランスポート) URLName の PasswordAuthentication を保存します。 pw が null の場合、URLName に対応するエントリは削除されます。

これは通常、ストア又はトランスポートの実装により、 認証情報が 1 つのセッションで複数回使用できるようにする為だけに使用されます。


getPasswordAuthentication

public PasswordAuthentication getPasswordAuthentication(URLName url)
この (ストア又はトランスポート) URLName の任意の保存された PasswordAuthentication を返します。 通常、ストア又はトランスポートの実装によってのみ使用されます。

戻り値:
URLName に対応する PasswordAuthentication

requestPasswordAuthentication

public PasswordAuthentication requestPasswordAuthentication(InetAddress addr,
                                                            int port,
                                                            String protocol,
                                                            String prompt,
                                                            String defaultUserName)
必要なユーザ名とパスワードを取得する為に、アプリケーションにコールバックします。 アプリケーションは、以下の様なダイアログを表示しなければなりません。

 Connecting to <protocol> mail service on host <addr>, port <port>.
 <prompt>
 
 ユーザ名: <defaultUserName>
 パスワード:
 

パラメータ:
addr - ホストの InetAddress。null の場合があります。
protocol - プロトコル体系 (imap、pop3 等)
prompt - プロンプトの一部として表示する為の任意の追加 String。null の場合があります。
defaultUserName - デフォルトのユーザ名。null の場合があります。
戻り値:
認証者により収集された認証。null の場合があります。

getProperties

public Properties getProperties()
この Session に関連付けられた Properties オブジェクトを返します。

戻り値:
Properties オブジェクト

getProperty

public String getProperty(String name)
指定されたプロパティの値を返します。 このプロパティが存在しない場合は null を返します。

戻り値:
プロパティ値となる文字列

addProvider

public void addProvider(Provider provider)
Add a provider to the session.

パラメータ:
provider - the provider to add
導入されたバージョン:
JavaMail 1.4

setProtocolForAddress

public void setProtocolForAddress(String addresstype,
                                  String protocol)
Set the default transport protocol to use for addresses of the specified type. Normally the default is set by the javamail.default.address.map or javamail.address.map files or resources.

パラメータ:
addresstype - type of address
protocol - name of protocol
導入されたバージョン:
JavaMail 1.4
関連項目:
getTransport(Address)