パッケージ jakarta.mail

クラス Session

  • public final class Session
extends ObjectSE
    Session クラスはメールセッションを表し、サブクラス化されていません。メール API で使用されるプロパティとデフォルトを収集します。単一のデフォルトセッションは、デスクトップ上の複数のアプリケーションで共有できます。非共有セッションも作成できます。

    Session クラスは、Store、Transport、関連するクラスを実装するプロトコルプロバイダーへのアクセスを提供します。プロトコルプロバイダーは、次のファイルを使用して構成されます。

    • javamail.providers および javamail.default.providers
    • javamail.address.map および javamail.default.address.map

    各 javamail.X リソースファイルは、次の順序で 3 つの方法を使用して検索されます。

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

    (ここでの java.home は "java.home" システムプロパティの値で、conf は、存在する場合は "conf" という名前のディレクトリ、存在しない場合は "lib" という名前のディレクトリです。"conf" ディレクトリは JDK 1.9 で導入されました)

    最初の方法では、java.home プロパティが指す conf ディレクトリにリソースファイルを置くことで、ユーザーが独自のバージョンのリソースファイルを含めることができます。2 番目の方法では、Jakarta Mail API を使用するアプリケーションが独自のリソースファイルをアプリケーションまたは jar ファイルの META-INF ディレクトリに含めることができます。javamail.default.X デフォルトファイルは Jakarta Mail mail.jar ファイルの一部であり、ユーザーが指定することはできません。

    ファイルの場所は、ClassLoader メソッド getResource の実装方法によって異なります。通常、getResource メソッドは、リクエストされたファイルが見つかるまで CLASSPATH を検索して停止します。

    リソースファイル内のエントリの順序は重要です。複数のエントリが存在する場合、最初のエントリが後のエントリより優先されます。例: アプリケーションによって明示的に変更されるまで、最初に見つかった IMAP プロバイダーがデフォルトの IMAP 実装として設定されます。ユーザーまたはシステムが提供するリソースファイルは、Jakarta Mail API に含まれているデフォルトファイルをオーバーライドしません。これは、読み込まれたすべてのファイルのすべてのエントリが利用できることを意味します。

    javamail.providers および javamail.default.providers

    これらのリソースファイルは、システムで利用可能なストアとトランスポートを指定し、アプリケーションが利用可能なストアとトランスポートの実装を「発見」できるようにします。プロトコルの実装は、1 行に 1 つずつリストされています。ファイル形式は、プロトコルの実装を説明する 4 つの属性を定義します。各属性は "=" -separated 名前と値のペアで、名前は小文字です。名前と値の各ペアはセミコロン（";"）で区切られます。以下の名前が定義されています。

    プロバイダーファイルの属性名
    名前 説明
    プロトコル プロトコルに割り当てられた名前。例: 輸送用の smtp。
    型 有効なエントリは store および transport です。
    class このプロトコルを実装するクラス名。
    ベンダー ベンダーを識別するオプションの文字列。
    バージョン バージョンを識別するオプションの文字列。

    META-INF/javamail.default.providers ファイルの内容の例を次に示します。

     protocol=imap; type=store; class=com.sun.mail.imap.IMAPStore; vendor=Oracle;
 protocol=smtp; type=transport; class=com.sun.mail.smtp.SMTPTransport; vendor=Oracle;

    現在の実装では、Java SE ServiceLoaderSE メカニズムを使用したプロバイダーの設定もサポートしています。独自のプロバイダーを作成するときは、Provider サブクラスを作成します。例:

     package com.example;

 import jakarta.mail.Provider;

 public class MyProvider extends Provider {
     public MyProvider() {
         super(Provider.Type.STORE, "myprot", MyStore.class.getName(),
             "Example", null);
     }
 }
    次に、jar ファイルに META-INF/services/jakarta.mail.Provider という名前のファイルを含めます。このファイルには、プロバイダークラスの名前がリストされています。
     com.example.MyProvider

    javamail.address.map および javamail.default.address.map

    これらのリソースファイルは、トランスポートアドレス型をトランスポートプロトコルにマップします。jakarta.mail.Address の getType メソッドはアドレス型を返します。javamail.address.map ファイルは、トランスポート型をプロトコルにマップします。ファイル形式は、一連の名前と値のペアです。各キー名は、現在システムにインストールされているアドレス型に対応している必要があります。また、jakarta.mail.Address を使用する場合は、jakarta.mail.Address 実装ごとにエントリが存在する必要があります。例: jakarta.mail.internet.InternetAddress メソッド getType は "rfc822" を返します。参照されている各プロトコルをシステムにインストールする必要があります。以下の news の場合、クライアントは nntp プロトコルをサポートするトランスポートプロバイダーをインストールする必要があります。

    javamail.address.map ファイルの一般的な内容は次のとおりです。

     rfc822=smtp
 news=nntp
    作成者:
    John Mani, Bill Shannon, Max Spivak

    • メソッドの詳細

      • getStreamProvider

        public StreamProvider getStreamProvider()
        セッションのストリームプロバイダーインスタンスを取得します。
        戻り値:
        ストリームプロバイダー
        導入:
        JavaMail 2.1

      • getInstance

        public static Session getInstance​(PropertiesSE props,
                                  Authenticator authenticator)
        新しい Session オブジェクトを取得します。
        パラメーター:
        props - 関連するプロパティを保持するプロパティオブジェクト。
        デフォルトでは、Jakarta Mail 仕様の付録 A にリストされているプロパティ（特に mail.store.protocol、mail.transport.protocol、mail.host、mail.user、mail.from）の値がクライアントから提供されることが期待されています。すべてのケースで機能する可能性は低いです。
        authenticator - ユーザー名とパスワードが必要なときにアプリケーションにコールバックするために使用される認証システムオブジェクト。
        戻り値:
        新しい Session オブジェクト
        関連事項:
        Authenticator

      • getInstance

        public static Session getInstance​(PropertiesSE props)
        新しい Session オブジェクトを取得します。
        パラメーター:
        props - 関連するプロパティを保持するプロパティオブジェクト。
        デフォルトでは、Jakarta Mail 仕様の付録 A にリストされているプロパティ（特に mail.store.protocol、mail.transport.protocol、mail.host、mail.user、mail.from）の値がクライアントから提供されることが期待されています。すべてのケースで機能する可能性は低いです。
        戻り値:
        新しい Session オブジェクト
        導入:
        JavaMail 1.2

      • getDefaultInstance

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

        デフォルトのセッションは、同じ Java 仮想マシンで実行されるすべてのコードで利用できる可能性があり、セッションにはユーザー名やパスワードなどの機密情報が含まれている可能性があるため、デフォルトのセッションへのアクセスは制限されます。Authenticator オブジェクトは呼び出し側で作成する必要があり、アクセス権限を確認するために間接的に使用されます。セッションの作成時に渡された Authenticator オブジェクトは、デフォルトのセッションを取得するために後続のリクエストに渡された Authenticator オブジェクトと比較されます。両方のオブジェクトが同じ、または同じ ClassLoader からのものである場合、リクエストは許可されます。それ以外の場合は拒否されます。

        セッションの作成に使用される Authenticator オブジェクトが null の場合、null を渡すことで誰でもデフォルトセッションを取得できることに注意してください。

        Properties オブジェクトは、このメソッドが初めて呼び出されたときにのみ、新しい Session オブジェクトが作成されたときに使用されることにも注意してください。以降の呼び出しでは、最初の呼び出しで作成された Session オブジェクトが返され、渡された Properties オブジェクトは無視されます。getInstance メソッドを使用して、メソッドが呼び出されるたびに新しい Session オブジェクトを取得します。

        追加のセキュリティ許可オブジェクトを使用して、デフォルトセッションへのアクセスを制御できます。

        現在の実装では、SecurityManager が設定されている場合、呼び出し元には RuntimePermission("setFactory") 権限が必要です。

        パラメーター:
        props - プロパティオブジェクト。新しい Session オブジェクトが作成された場合にのみ使用されます。
        デフォルトでは、Jakarta Mail 仕様の付録 A にリストされているプロパティ（特に mail.store.protocol、mail.transport.protocol、mail.host、mail.user、mail.from）の値がクライアントから提供されることが期待されています。すべてのケースで機能する可能性は低いです。
        authenticator - Authenticator オブジェクト。新しい Session オブジェクトが作成された場合にのみ使用されます。それ以外の場合は、セッションの作成に使用されたオーセンティケーターと一致する必要があります。
        戻り値:
        デフォルトの Session オブジェクト

      • getDefaultInstance

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

        オーセンティケーターなしで作成されたデフォルトのセッションは、同じ Java 仮想マシンで実行されるすべてのコードで使用でき、セッションにはユーザー名やパスワードなどの機密情報を含めることができます。

        パラメーター:
        props - プロパティオブジェクト。新しい Session オブジェクトが作成された場合にのみ使用されます。
        デフォルトでは、Jakarta Mail 仕様の付録 A にリストされているプロパティ（特に mail.store.protocol、mail.transport.protocol、mail.host、mail.user、mail.from）の値がクライアントから提供されることが期待されています。すべてのケースで機能する可能性は低いです。
        戻り値:
        デフォルトの Session オブジェクト
        導入:
        JavaMail 1.2

      • setDebug

        public void setDebug​(boolean debug)
        このセッションのデバッグ設定を設定します。

        デバッグ設定はセッションが作成された後にのみオンにすることができるため、セッションコンストラクターでデバッグをオンにするには、コンストラクターに渡される Properties オブジェクトのプロパティ mail.debug を true に設定します。mail.debug プロパティの値は、セッションごとのデバッグフラグを初期化するために使用されます。その後の setDebug メソッドの呼び出しは、セッションごとのデバッグフラグを操作し、mail.debug プロパティに影響を与えません。

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

      • getDebug

        public boolean getDebug()
        このセッションのデバッグ設定を取得します。
        戻り値:
        現在のデバッグ設定

      • setDebugOut

        public void setDebugOut​(PrintStreamSE out)
        このセッションのデバッグ出力に使用するストリームを設定します。out が null の場合、System.out が使用されます。mail.debug システムプロパティを設定した結果として、セッションが作成される前に発生するデバッグ出力は、常に System.out に送信されることに注意してください。
        パラメーター:
        out - デバッグ出力に使用する PrintStream
        導入:
        JavaMail 1.3

      • getDebugOut

        public PrintStreamSE getDebugOut()
        デバッグ出力に使用されるストリームを返します。ストリームが設定されていない場合は、System.out が返されます。
        戻り値:
        デバッグ出力に使用する PrintStream
        導入:
        JavaMail 1.3

      • getProviders

        public Provider[] getProviders()
        このメソッドは、このアプリケーションで使用可能な ClassLoader を使用してロードできる javamail。[default。] providers ファイルを介してインストールされたすべての実装の配列を返します。
        戻り値:
        構成されたプロバイダーの配列

      • getProvider

        public Provider getProvider​(StringSE protocol)
                     throws NoSuchProviderException
        指定されたプロトコルのデフォルトのプロバイダーを返します。最初に mail。<protocol> .class プロパティをチェックし、存在する場合は、この実装に関連付けられているプロバイダーを返します。存在しない場合は、構成ファイルで最初に出現したプロバイダーを返します。プロトコルの実装が見つからない場合、NoSuchProviderException をスローします
        パラメーター:
        protocol - 構成済みプロトコル (つまり、smtp、imap など)
        戻り値:
        指定されたプロトコル用に現在構成されているプロバイダー
        例外:
        NoSuchProviderException - 指定されたプロトコルのプロバイダーが見つからない場合。

      • setProvider

        public void setProvider​(Provider provider)
                 throws NoSuchProviderException
        渡されたプロバイダーを Provider.protocol のプロトコルのデフォルト実装に設定し、以前の値を上書きします。
        パラメーター:
        provider - プロトコルのデフォルトとして設定される、現在構成されているプロバイダー
        例外:
        NoSuchProviderException - 渡されたプロバイダーが無効な場合。

      • getStore

        public Store getStore()
               throws NoSuchProviderException
        このユーザーが希望する Store プロトコルを実装する Store オブジェクトを取得します。mail.store.protocol プロパティは、目的のプロトコルを指定します。適切な Store オブジェクトが取得されない場合、NoSuchProviderException がスローされます
        戻り値:
        Store オブジェクト
        例外:
        NoSuchProviderException - 指定されたプロトコルのプロバイダーが見つからない場合。

      • getStore

        public Store getStore​(StringSE protocol)
               throws NoSuchProviderException
        指定されたプロトコルを実装する Store オブジェクトを取得します。適切な Store オブジェクトを取得できない場合、NoSuchProviderException がスローされます。
        パラメーター:
        protocol - ストアプロトコル
        戻り値:
        Store オブジェクト
        例外:
        NoSuchProviderException - 指定されたプロトコルのプロバイダーが見つからない場合。

      • getStore

        public Store getStore​(URLName url)
               throws NoSuchProviderException
        指定された URLName の Store オブジェクトを取得します。リクエストされた Store オブジェクトを取得できない場合、NoSuchProviderException がスローされます。URL 文字列（RFC 1738 を参照）の「スキーム」部分は、ストアプロトコルを見つけるために使用されます。

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

      • getStore

        public Store getStore​(Provider provider)
               throws NoSuchProviderException
        プロバイダーによって指定されたストアのインスタンスを取得します。ストアをインスタンス化して返します。
        パラメーター:
        provider - インスタンス化されるストアプロバイダー
        戻り値:
        インスタンス化されたストア
        例外:
        NoSuchProviderException - 指定されたプロバイダーのプロバイダーが見つからない場合。

      • getFolder

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

        URL 文字列（RFC 1738 を参照）の「スキーム」部分は、ストアプロトコルを見つけるために使用されます。URL 文字列の残りの部分（つまり、RFC 1738 に基づく "schemepart" ）は、適切な Folder オブジェクトを見つけてインスタンス化するために、プロトコルに依存した方法でそのストアによって使用されます。

        RFC 1738 では、IP ベースのプロトコル（IMAP4、POP3 など）の "schemepart" の構文も指定されていることに注意してください。IP ベースのメールストアのプロバイダーは、フォルダーを参照するためにその構文を実装する必要があります。

        パラメーター:
        url - 目的のフォルダーを表す URLName
        戻り値:
        フォルダー
        例外:
        NoSuchProviderException - 指定された URLName のプロバイダーが見つからない場合。
        MessagingException - フォルダーが見つからなかったか、作成できなかった場合。
        関連事項:
        getStore(URLName), URLName

      • getTransport

        public Transport getTransport()
                       throws NoSuchProviderException
        このユーザーが希望するトランスポートプロトコルを実装するトランスポートオブジェクトを取得します。mail.transport.protocol プロパティは、目的のプロトコルを指定します。適切な Transport オブジェクトを取得できない場合、MessagingException がスローされます。
        戻り値:
        Transport オブジェクト
        例外:
        NoSuchProviderException - プロバイダーが見つからない場合。

      • getTransport

        public Transport getTransport​(StringSE protocol)
                       throws NoSuchProviderException
        指定されたプロトコルを実装する Transport オブジェクトを取得します。適切な Transport オブジェクトを取得できない場合は、null が返されます。
        パラメーター:
        protocol - トランスポートプロトコル
        戻り値:
        Transport オブジェクト
        例外:
        NoSuchProviderException - 指定されたプロトコルのプロバイダーが見つからない場合。

      • getTransport

        public Transport getTransport​(URLName url)
                       throws NoSuchProviderException
        指定された URLName の Transport オブジェクトを取得します。リクエストされたトランスポートオブジェクトを取得できない場合、NoSuchProviderException がスローされます。URL 文字列（RFC 1738 を参照）の「スキーム」部分は、トランスポートプロトコルを見つけるために使用されます。

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

      • getTransport

        public Transport getTransport​(Provider provider)
                       throws NoSuchProviderException
        プロバイダーで指定されたトランスポートのインスタンスを取得します。トランスポートをインスタンス化して返します。
        パラメーター:
        provider - インスタンス化されるトランスポートプロバイダー
        戻り値:
        インスタンス化されたトランスポート
        例外:
        NoSuchProviderException - 指定されたプロバイダーのプロバイダーが見つからない場合。

      • getTransport

        public Transport getTransport​(Address address)
                       throws NoSuchProviderException
        指定されたアドレス型のメッセージを転送できる Transport オブジェクトを取得します。
        パラメーター:
        address - トランスポートが必要なアドレス
        戻り値:
        Transport オブジェクト
        例外:
        NoSuchProviderException - アドレス型のプロバイダーが見つからない場合
        関連事項:
        Address

      • setPasswordAuthentication

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

        これは通常、ストアまたはトランスポートの実装でのみ使用され、セッションの複数の使用間で認証情報を共有できるようにします。

        パラメーター:
        url - URLName
        pw - 保存する PasswordAuthentication

      • getPasswordAuthentication

        public PasswordAuthentication getPasswordAuthentication​(URLName url)
        この（ストアまたはトランスポート）URLName の保存済み PasswordAuthentication を返します。通常、ストアまたはトランスポートの実装でのみ使用されます。
        パラメーター:
        url - URLName
        戻り値:
        URLName に対応する PasswordAuthentication

      • requestPasswordAuthentication

        public PasswordAuthentication requestPasswordAuthentication​(InetAddressSE addr,
                                                            int port,
                                                            StringSE protocol,
                                                            StringSE prompt,
                                                            StringSE defaultUserName)
        アプリケーションにコールバックして、必要なユーザー名とパスワードを取得します。アプリケーションは次のようなダイアログを表示する必要があります。
         Connecting to <protocol> mail service on host <addr>, port <port>.
 <prompt>

 User Name: <defaultUserName>
 Password:
        パラメーター:
        addr - ホストの InetAddress。null の可能性があります。
        port - ホストのポート
        protocol - プロトコルスキーム (たとえば imap、pop3 など)
        prompt - プロンプトの一部として表示する追加の文字列。null の可能性があります。
        defaultUserName - デフォルトのユーザー名。null の可能性があります。
        戻り値:
        オーセンティケーターによって収集された認証。null の可能性があります。

      • getProperties

        public PropertiesSE getProperties()
        このセッションに関連付けられた Properties オブジェクトを返します
        戻り値:
        プロパティオブジェクト

      • getProperty

        public StringSE getProperty​(StringSE name)
        指定されたプロパティの値を返します。このプロパティが存在しない場合は null を返します。
        パラメーター:
        name - プロパティ名
        戻り値:
        プロパティ値である文字列

      • addProvider

        public void addProvider​(Provider provider)
        プロバイダーをセッションに追加します。
        パラメーター:
        provider - 追加するプロバイダー
        導入:
        JavaMail 1.4

      • setProtocolForAddress

        public void setProtocolForAddress​(StringSE addresstype,
                                  StringSE protocol)
        指定された型のアドレスに使用するデフォルトのトランスポートプロトコルを設定します。通常、デフォルトは javamail.default.address.map または javamail.address.map ファイルまたはリソースによって設定されます。
        パラメーター:
        addresstype - 住所の型
        protocol - プロトコルの名前
        導入:
        JavaMail 1.4
        関連事項:
        getTransport(Address)