パッケージ jakarta.jms

インターフェース ConnectionFactory

  • すべての既知のサブインターフェース:
    QueueConnectionFactory、TopicConnectionFactory、XAQueueConnectionFactory、XATopicConnectionFactory
    public interface ConnectionFactory
    ConnectionFactory オブジェクトは、管理者が定義した一連の接続構成パラメーターをカプセル化します。クライアントはこれを使用して、Jakarta Messaging プロバイダーとの接続を作成します。

    ConnectionFactory オブジェクトは Jakarta Messaging 管理対象オブジェクトであり、同時使用をサポートしています。

    Jakarta Messaging 管理対象オブジェクトは、管理者が作成し、後で Jakarta Messaging クライアントが使用する構成情報を含むオブジェクトです。企業内で Jakarta Messaging API を管理するのが現実的です。

    管理対象オブジェクトのインターフェースは、Java Naming and Directory Interface（JNDI）API に明示的に依存していませんが、Jakarta Messaging API は、Jakarta Messaging クライアントが JNDI 名前空間でルックアップすることにより、管理対象オブジェクトを見つけるという規則を確立します。

    管理者は、名前空間の任意の場所に管理対象オブジェクトを配置できます。Jakarta Messaging API は命名ポリシーを定義していません。

    Jakarta Messaging プロバイダーは、管理者が JNDI 名前空間で管理対象オブジェクトを作成および構成するために必要なツールを提供することが期待されています。管理対象オブジェクトの Jakarta Messaging プロバイダー実装は、すべての JNDI ネーミングコンテキストに格納できるように、javax.jndi.Referenceable と java.io.Serializable の両方にする必要があります。さらに、これらの実装は JavaBeans TM 設計パターンに従うことが推奨されます。

    この戦略にはいくつかの利点があります。

    • Jakarta Messaging クライアントからプロバイダー固有の詳細を隠します。
    • これは、管理情報を Java プログラミング言語のオブジェクト（「Java オブジェクト」）に抽象化し、共通の管理コンソールから簡単に編成および管理できるようにします。
    • すべてのポピュラーなネーミングサービス用の JNDI プロバイダーがあるため、これは、Jakarta Messaging プロバイダーがどこでも実行される管理対象オブジェクトの 1 つの実装を提供できることを意味します。

    管理対象オブジェクトは、リモートリソースを保持しないでください。そのルックアップでは、JNDI API 自体で使用されるもの以外のリモートリソースを使用しないでください。

    クライアントは、管理対象オブジェクトをローカル Java オブジェクトと考える必要があります。調べると、隠れた副作用が発生したり、意外な量のローカルリソースを使用したりすることはできません。

    導入:
    JMS 1.0
    バージョン:
    Jakarta Messaging 2.0
    関連事項:
    Connection, QueueConnectionFactory, TopicConnectionFactory

    • メソッドの詳細

      • createConnection

        Connection createConnection()
                     throws JMSException
        デフォルトのユーザー ID で接続を作成します。接続は停止モードで作成されます。Connection.start メソッドが明示的に呼び出されるまで、メッセージは配信されません。
        戻り値:
        新しく作成された接続
        例外:
        JMSException - 内部エラーのために Jakarta Messaging プロバイダーが接続の作成に失敗した場合。
        JMSSecurityException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 1.1

      • createConnection

        Connection createConnection​(StringSE userName,
                            StringSE password)
                     throws JMSException
        指定されたユーザー ID で接続を作成します。接続は停止モードで作成されます。Connection.start メソッドが明示的に呼び出されるまで、メッセージは配信されません。
        パラメーター:
        userName - 呼び出し元のユーザー名
        password - 発信者のパスワード
        戻り値:
        新しく作成された接続
        例外:
        JMSException - 内部エラーのために Jakarta Messaging プロバイダーが接続の作成に失敗した場合。
        JMSSecurityException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 1.1

      • createContext

        JMSContext createContext()
        デフォルトのユーザー ID と未指定の sessionMode を使用して JMSContext を作成します。

        新しい JMSContext が使用する接続とセッションが作成されます。接続は停止モードで作成されますが、JMSConsumer が作成されると自動的に開始されます。

        作成されるセッションの動作は、このメソッドが Java SE 環境で呼び出されるか、Jakarta EE アプリケーションクライアントコンテナーで呼び出されるか、Jakarta EE Web または EJB コンテナーで呼び出されるかによって異なります。このメソッドが Jakarta EE Web または EJB コンテナーで呼び出される場合、セッションの動作は、進行中のアクティブな JTA トランザクションがあるかどうかによっても異なります。

        Java SE 環境または Jakarta EE アプリケーションクライアントコンテナー :

        • セッションは処理されず、受信メッセージは JMSContext.AUTO_ACKNOWLEDGE の確認モードを使用して自動的に確認されます。この確認モードの意味の定義については、以下のリンクを参照してください。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがある場合 :

        • セッションは JTA トランザクションに参加し、そのトランザクションがコミットまたはロールバックされるときに、JMSContext の commit または rollback メソッドを呼び出すことではなく、コミットまたはロールバックされます。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがない場合 :

        • セッションは処理されず、受信メッセージは JMSContext.AUTO_ACKNOWLEDGE の確認モードを使用して自動的に確認されます。この確認モードの意味の定義については、以下のリンクを参照してください。
        戻り値:
        新しく作成された JMSContext
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが JMSContext の作成に失敗した場合
        JMSSecurityRuntimeException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 2.0
        関連事項:
        JMSContext.AUTO_ACKNOWLEDGE, createContext(int), createContext(java.lang.String, java.lang.String), createContext(java.lang.String, java.lang.String, int), JMSContext.createContext(int)

      • createContext

        JMSContext createContext​(StringSE userName,
                         StringSE password)
        指定されたユーザー ID と指定されていない sessionMode を使用して JMSContext を作成します。

        新しい JMSContext が使用する接続とセッションが作成されます。接続は停止モードで作成されますが、JMSConsumer が起動すると自動的に開始されます。

        作成されるセッションの動作は、このメソッドが Java SE 環境で呼び出されるか、Jakarta EE アプリケーションクライアントコンテナーで呼び出されるか、Jakarta EE Web または EJB コンテナーで呼び出されるかによって異なります。このメソッドが Jakarta EE Web または EJB コンテナーで呼び出される場合、セッションの動作は、進行中のアクティブな JTA トランザクションがあるかどうかによっても異なります。

        Java SE 環境または Jakarta EE アプリケーションクライアントコンテナー :

        • セッションは処理されず、受信メッセージは JMSContext.AUTO_ACKNOWLEDGE の確認モードを使用して自動的に確認されます。この確認モードの意味の定義については、以下のリンクを参照してください。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがある場合 :

        • セッションは JTA トランザクションに参加し、そのトランザクションがコミットまたはロールバックされるときに、JMSContext の commit または rollback メソッドを呼び出すことではなく、コミットまたはロールバックされます。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがない場合 :

        • セッションは処理されず、受信メッセージは JMSContext.AUTO_ACKNOWLEDGE の確認モードを使用して自動的に確認されます。この確認モードの意味の定義については、以下のリンクを参照してください。
        パラメーター:
        userName - 呼び出し元のユーザー名
        password - 発信者のパスワード
        戻り値:
        新しく作成された JMSContext
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが JMSContext の作成に失敗した場合
        JMSSecurityRuntimeException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 2.0
        関連事項:
        JMSContext.AUTO_ACKNOWLEDGE, createContext(), createContext(int), createContext(java.lang.String, java.lang.String, int), JMSContext.createContext(int)

      • createContext

        JMSContext createContext​(StringSE userName,
                         StringSE password,
                         int sessionMode)
        指定されたユーザー ID と指定されたセッションモードで JMSContext を作成します。

        新しい JMSContext が使用する接続とセッションが作成されます。JMSContext は停止モードで作成されますが、JMSConsumer が作成されると自動的に開始されます。

        sessionMode 引数を設定する効果は、このメソッドが Java SE 環境で呼び出されるか、Jakarta EE アプリケーションクライアントコンテナーで呼び出されるか、Jakarta EE Web または EJB コンテナーで呼び出されるかによって異なります。このメソッドが Jakarta EE Web または EJB コンテナーで呼び出された場合、sessionMode 引数を設定する効果は、アクティブな JTA トランザクションが進行中かどうかによっても異なります。

        Java SE 環境または Jakarta EE アプリケーションクライアントコンテナー :

        • sessionMode が JMSContext.SESSION_TRANSACTED に設定されている場合、セッションはローカルトランザクションを使用します。ローカルトランザクションは、JMSContext の commit または rollback メソッドを呼び出すことにより、後でコミットまたはロールバックできます。
        • sessionMode が JMSContext.CLIENT_ACKNOWLEDGE、JMSContext.AUTO_ACKNOWLEDGE、JMSContext.DUPS_OK_ACKNOWLEDGE のいずれかに設定されている場合。その後、セッションは非トランザクションになり、このセッションで受信されたメッセージは sessionMode の値に従って確認されます。これらの確認応答モードの意味の定義については、以下のリンクを参照してください。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがある場合 :

        • 引数 sessionMode は無視されます。セッションは JTA トランザクションに参加し、JMSContext の commit または rollback メソッドを呼び出すことではなく、そのトランザクションがコミットまたはロールバックされるときにコミットまたはロールバックされます。引数は無視されるため、開発者はこのメソッドの代わりに createContext(String userName, String password) を使用することをお勧めします。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがない場合 :

        • 引数 acknowledgeMode は、JMSContext.AUTO_ACKNOWLEDGE または JMSContext.DUPS_OK_ACKNOWLEDGE のいずれかに設定する必要があります。セッションは非トランザクションであり、このセッションで受信されたメッセージは acknowledgeMode の値に従って自動的に確認されます。これらの確認応答モードの意味の定義については、以下のリンクを参照してください。JMSContext.SESSION_TRANSACTED および JMSContext.CLIENT_ACKNOWLEDGE の値は使用できません。
        パラメーター:
        userName - 呼び出し元のユーザー名
        password - 発信者のパスワード
        sessionMode - 4 つの可能なセッションモードのどれが使用されるかを示します。
        • このメソッドが JavaSE 環境または Jakarta EE アプリケーションクライアントコンテナーで呼び出された場合、許可される値は JMSContext.SESSION_TRANSACTED、JMSContext.CLIENT_ACKNOWLEDGE、JMSContext.AUTO_ACKNOWLEDGE、JMSContext.DUPS_OK_ACKNOWLEDGE です。
        • 進行中のアクティブな JTA トランザクションがあるときに、このメソッドが Jakarta EE Web または EJB コンテナーで呼び出された場合、この引数は無視されます。
        • 進行中のアクティブな JTA トランザクションがないときに Jakarta EE Web または EJB コンテナーでこのメソッドが呼び出される場合、許可される値は JMSContext.AUTO_ACKNOWLEDGE および JMSContext.DUPS_OK_ACKNOWLEDGE です。この場合、値 JMSContext.TRANSACTED および JMSContext.CLIENT_ACKNOWLEDGE は許可されません。
        戻り値:
        新しく作成された JMSContext
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが JMSContext の作成に失敗した場合
        JMSSecurityRuntimeException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 2.0
        関連事項:
        JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE, JMSContext.AUTO_ACKNOWLEDGE, JMSContext.DUPS_OK_ACKNOWLEDGE, createContext(), createContext(int), createContext(java.lang.String, java.lang.String), JMSContext.createContext(int)

      • createContext

        JMSContext createContext​(int sessionMode)
        デフォルトのユーザー ID と指定されたセッションモードで JMSContext を作成します。

        新しい JMSContext が使用する接続とセッションが作成されます。JMSContext は停止モードで作成されますが、JMSConsumer が作成されると自動的に開始されます。

        sessionMode 引数を設定する効果は、このメソッドが Java SE 環境で呼び出されるか、Jakarta EE アプリケーションクライアントコンテナーで呼び出されるか、Jakarta EE Web または EJB コンテナーで呼び出されるかによって異なります。このメソッドが Jakarta EE Web または EJB コンテナーで呼び出された場合、sessionMode 引数を設定する効果は、アクティブな JTA トランザクションが進行中かどうかによっても異なります。

        Java SE 環境または Jakarta EE アプリケーションクライアントコンテナー :

        • sessionMode が JMSContext.SESSION_TRANSACTED に設定されている場合、セッションはローカルトランザクションを使用します。ローカルトランザクションは、JMSContext の commit または rollback メソッドを呼び出すことにより、後でコミットまたはロールバックできます。
        • sessionMode が JMSContext.CLIENT_ACKNOWLEDGE、JMSContext.AUTO_ACKNOWLEDGE、JMSContext.DUPS_OK_ACKNOWLEDGE のいずれかに設定されている場合。その後、セッションは非トランザクションになり、このセッションで受信されたメッセージは sessionMode の値に従って確認されます。これらの確認応答モードの意味の定義については、以下のリンクを参照してください。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがある場合 :

        • 引数 sessionMode は無視されます。セッションは JTA トランザクションに参加し、JMSContext の commit または rollback メソッドを呼び出すことではなく、そのトランザクションがコミットまたはロールバックされるときにコミットまたはロールバックされます。引数は無視されるため、開発者はこのメソッドの代わりに createContext() を使用することをお勧めします。

        Jakarta EE Web または EJB コンテナーで、進行中のアクティブな JTA トランザクションがない場合 :

        • 引数 acknowledgeMode は、JMSContext.AUTO_ACKNOWLEDGE または JMSContext.DUPS_OK_ACKNOWLEDGE のいずれかに設定する必要があります。セッションは非トランザクションであり、このセッションで受信されたメッセージは acknowledgeMode の値に従って自動的に確認されます。これらの確認応答モードの意味の定義については、以下のリンクを参照してください。JMSContext.SESSION_TRANSACTED および JMSContext.CLIENT_ACKNOWLEDGE の値は使用できません。
        パラメーター:
        sessionMode - 4 つの可能なセッションモードのどれが使用されるかを示します。
        • このメソッドが JavaSE 環境または Jakarta EE アプリケーションクライアントコンテナーで呼び出された場合、許可される値は JMSContext.SESSION_TRANSACTED、JMSContext.CLIENT_ACKNOWLEDGE、JMSContext.AUTO_ACKNOWLEDGE、JMSContext.DUPS_OK_ACKNOWLEDGE です。
        • 進行中のアクティブな JTA トランザクションがあるときに、このメソッドが Jakarta EE Web または EJB コンテナーで呼び出された場合、この引数は無視されます。
        • 進行中のアクティブな JTA トランザクションがないときに Jakarta EE Web または EJB コンテナーでこのメソッドが呼び出される場合、許可される値は JMSContext.AUTO_ACKNOWLEDGE および JMSContext.DUPS_OK_ACKNOWLEDGE です。この場合、値 JMSContext.TRANSACTED および JMSContext.CLIENT_ACKNOWLEDGE は許可されません。
        戻り値:
        新しく作成された JMSContext
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが JMSContext の作成に失敗した場合
        JMSSecurityRuntimeException - 無効なユーザー名またはパスワードが原因でクライアント認証が失敗した場合。
        導入:
        JMS 2.0
        関連事項:
        JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE, JMSContext.AUTO_ACKNOWLEDGE, JMSContext.DUPS_OK_ACKNOWLEDGE, createContext(), createContext(java.lang.String, java.lang.String), createContext(java.lang.String, java.lang.String, int), JMSContext.createContext(int)