パッケージ jakarta.jms

インターフェース MessageConsumer

  • すべてのスーパーインターフェース:
    AutoCloseableSE
    すべての既知のサブインターフェース:
    QueueReceiver, TopicSubscriber
    public interface MessageConsumer
extends AutoCloseableSE
    クライアントは MessageConsumer オブジェクトを使用して、宛先からメッセージを受信します。MessageConsumer オブジェクトは、Destination オブジェクトをセッションによって提供されるメッセージコンシューマー作成メソッドに渡すことによって作成されます。

    MessageConsumer は、すべてのメッセージコンシューマーの親インターフェースです。

    MessageConsumer は、メッセージセレクターを使用して作成できます。メッセージセレクターを使用すると、クライアントは、メッセージコンシューマーに配信されるメッセージを、セレクターに一致するメッセージに制限できます。

    クライアントは、MessageConsumer のメッセージを同期的に受信するか、MessageConsumer にメッセージの到着時に非同期で配信させることができます。

    同期受信の場合、クライアントは、receive メソッドの 1 つを使用して、MessageConsumer から次のメッセージをリクエストできます。クライアントがポーリングしたり、次のメッセージを待機したりできるようにする receive にはいくつかのバリエーションがあります。

    非同期配信の場合、クライアントは MessageListener オブジェクトを MessageConsumer に登録できます。メッセージが MessageConsumer に到着すると、MessageListener の onMessage メソッドを呼び出してメッセージを配信します。

    MessageListener が例外をスローするのはクライアントプログラミングエラーです。

    導入:
    JMS 1.0
    バージョン:
    Jakarta Messaging 2.0
    関連事項:
    QueueReceiver, TopicSubscriber, Session

    • メソッドの詳細

      • getMessageSelector

        StringSE getMessageSelector()
                   throws JMSException
        このメッセージコンシューマーのメッセージセレクタ式を取得します。
        戻り値:
        このメッセージコンシューマーのメッセージセレクター、またはメッセージコンシューマーのメッセージセレクターが存在しない場合は null (つまり、メッセージセレクターが設定されていないか、null または空の文字列に設定されている場合)
        例外:
        JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーがメッセージセレクターの取得に失敗した場合。

      • getMessageListener

        MessageListener getMessageListener()
                            throws JMSException
        MessageConsumer の MessageListener を取得します。

        このメソッドは、Jakarta EE Web または EJB アプリケーションでは使用しないでください。保証されていませんが、JMSException がスローされる可能性があります。

        戻り値:
        MessageConsumer の MessageListener、または設定されていない場合は null
        例外:
        JMSException - 次のいずれかの理由で Jakarta Messaging プロバイダーが MessageListener の取得に失敗した場合:
        • 内部エラーが発生した、または
        • このメソッドは Jakarta EE Web または EJB アプリケーションで呼び出されました (この場合、例外がスローされることは保証されていませんが)
        関連事項:
        setMessageListener(jakarta.jms.MessageListener)

      • setMessageListener

        void setMessageListener​(MessageListener listener)
                 throws JMSException
        MessageConsumer の MessageListener を設定します。

        MessageListener を null に設定することは、MessageConsumer の MessageListener を設定解除することと同じです。

        メッセージが既存のリスナーによって消費されている間、または MessageConsumer がメッセージを同期的に消費するために使用されているときに、このメソッドを呼び出す効果は定義されていません。

        このメソッドは、Jakarta EE Web または EJB アプリケーションでは使用しないでください。保証されていませんが、JMSException がスローされる可能性があります。

        パラメーター:
        listener - メッセージの配信先のリスナー
        例外:
        JMSException - Jakarta Messaging プロバイダーが次のいずれかの理由で MessageConsumer の MessageListener の設定に失敗した場合:
        • 内部エラーが発生した、または
        • このメソッドは Jakarta EE Web または EJB アプリケーションで呼び出されました (この場合、例外がスローされることは保証されていませんが)
        関連事項:
        getMessageListener()

      • receive

        Message receive()
         throws JMSException
        このメッセージコンシューマー用に作成された次のメッセージを受信します。

        この呼び出しは、メッセージが生成されるまで、またはこのメッセージコンシューマーが閉じられるまで、無期限にブロックされます。

        この receive がトランザクション内で実行される場合、コンシューマーはトランザクションがコミットされるまでメッセージを保持します。

        戻り値:
        このメッセージコンシューマーに対して生成される次のメッセージ、またはこのメッセージコンシューマーが同時に閉じられている場合は null
        例外:
        JMSException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • receive

        Message receive​(long timeout)
         throws JMSException
        指定されたタイムアウト間隔内に到着する次のメッセージを受信します。

        この呼び出しは、メッセージが到着するか、タイムアウトが期限切れになるか、このメッセージコンシューマーが閉じられるまでブロックされます。ゼロの timeout が期限切れになることはなく、呼び出しは無期限にブロックされます。

        パラメーター:
        timeout - タイムアウト値 (ミリ秒単位)
        戻り値:
        このメッセージコンシューマーに対して生成される次のメッセージ、またはタイムアウトが期限切れになるか、このメッセージコンシューマーが同時に閉じられる場合は null
        例外:
        JMSException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • receiveNoWait

        Message receiveNoWait()
               throws JMSException
        次のメッセージがすぐに利用可能な場合、受信します。
        戻り値:
        このメッセージコンシューマー用に生成された次のメッセージ、または使用できない場合は null
        例外:
        JMSException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • close

        void close()
    throws JMSException
        メッセージコンシューマーを閉じます。

        プロバイダーは、Java 仮想マシンの外部で MessageConsumer に代わって一部のリソースを割り当てる可能性があるため、クライアントは、必要のないときに閉じる必要があります。最終的にこれらのリソースを再利用するためにガベージコレクションに依存することは、十分なタイムリーではない可能性があります。

        この呼び出しは、このコンシューマーで進行中の receive 呼び出しが完了するまでブロックされます。このメッセージコンシューマーが閉じられると、ブロックされた receive 呼び出しは null を返します。

        メッセージリスナーが別のスレッドで進行しているときにこのメソッドが呼び出されると、メッセージリスナーが完了するまでブロックされます。

        このメソッドは、それ自体のコンシューマー上のメッセージリスナーの onMessage メソッドから呼び出すことができます。このメソッドが戻った後、onMessage メソッドは正常に完了することができます。

        このメソッドは、同時に呼び出すことができる唯一の MessageConsumer メソッドです。

        次で指定:
        インターフェース AutoCloseableSE の close 
        例外:
        JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーがコンシューマーを閉じることができない場合。