モジュール java.naming
パッケージ javax.naming.event

インタフェースEventContext

  • すべてのスーパー・インタフェース:
    Context
    既知のすべてのサブインタフェース:
    EventDirContext
    public interface EventContext
extends Context
    コンテキストに指定されたオブジェクトが変更されたときにトリガーされるイベントの通知を受け取る、リスナーの登録/登録解除に関するメソッドを含みます。

    ターゲット

    addNamingListener()メソッドにある名前パラメータは、ターゲットと呼ばれます。 ターゲットはスコープとともに、リスナーが対象とするオブジェクトを特定します。 まだ存在しないターゲットに対して配信登録を行うことはできますが、サービス・プロバイダや使用するプロトコル/サービスによってはサポート内容に制限がある場合があります。

    あるサービスが既存のターゲットに対する配信登録のみをサポートする場合、存在しないターゲットを登録しようとすると、可能な限り早い時点でNameNotFoundExceptionがスローされます。スローされるタイミングはaddNamingListener()を呼び出す時点が理想的ですが、それが可能ではない場合は、リスナーはNamingExceptionEvent経由で例外を受け取ります。

    また、既存のターゲットしか登録しないサービス・プロバイダでは、リスナーが登録したターゲットが名前空間から削除されると、NamingExceptionEvent (NameNotFoundExceptionを含む)からリスナーに通知されます。

    アプリケーションは、targetMustExist()メソッドを使用して、存在しないターゲットの登録がEventContextでサポートされているかどうかを確認できます。

    イベント・ソース

    登録メソッドを起動したEventContextインスタンスは、生成した(見込みも含む)イベントのイベント・ソースです。 イベント・ソースはターゲットで指定したオブジェクトである必要はありません。 ターゲットの名前が空である場合のみ、ターゲットで指定したオブジェクトがソースになります。 つまり、ターゲットをスコープ・パラメータとともに使用し、リスナーが関心を持つオブジェクトを特定します。ただし、イベント・ソースは、リスナーが登録したEventContextインスタンスとなります。

    たとえば、リスナーが次の登録を行なったとします。 

          NamespaceChangeListener listener = ...;
      src.addNamingListener("x", SUBTREE_SCOPE, listener);
    そのあとに「x/y」という名前のオブジェクトが削除された場合、対応するNamingEvent (evt)には次が含まれている必要があります。 
          evt.getEventContext() == src
      evt.getOldBinding().getName().equals("x/y")

    さらに、リスナーの登録/登録解除はEventContext インスタンスを使って行われ、名前空間の対応オブジェクトを用いません。 プログラムの一部でリスナーを削除する場合、addNamingListener()を起動したEventContextインスタンスの参照を保存します(リスナーに対して参照を保存し、あとで削除するために必要になります)。 lookup()を実行し、登録解除を実行するEventContextの別のインスタンスを取得することは想定できません。

    登録の有効期間

    登録したリスナーが登録解除されるのは次の場合です。
    • removeNamingListener()を使って削除された。
    • イベント情報の収集時に例外がスローされた。 つまり、リスナーがNamingExceptionEventを受け取ったとき。
    • Context.close()が登録したEventContextインスタンスで起動された。
    その時点まで、未処理のリスナーを持つEventContextインスタンスは引き続き存在し、サービス・プロバイダによって維持されます。

    リスナーの実装

    登録/登録解除メソッドではNamingListenerのインスタンスを受け取ります。 これには、NamingEventのさまざまなイベント・タイプに対するNamingListenerのサブインタフェースがあります。 たとえば、ObjectChangeListenerインタフェースはNamingEvent.OBJECT_CHANGEDイベント・タイプに対するものです。 複数のイベント・タイプで配信対象を登録するには、リスナーの実装で複数のNamingListenerサブインタフェースを実装し、addNamingListener()の呼出しを1回行う必要があります。 これにより、メソッド呼出しの回数の減少、およびリスナーのコード・サイズの削減に加えて、一部のサービス・プロバイダでは登録を最適化することができます。

    スレッド問題

    一般的なContextインスタンスのように、EventContextのインスタンスはスレッドに対して安全というわけではありません。 複数のスレッドが同時に同じEventContextにアクセスしている場合は注意が必要です。 スレッドの問題の詳細は、「パッケージの説明」を参照してください。
    導入されたバージョン:
    1.3

    • フィールドの詳細

      • OBJECT_SCOPE

        static final int OBJECT_SCOPE
        ターゲットに指定されたオブジェクトに関するイベントを通知するかどうかを指定する定数です。

        この定数の値は0です。

        関連項目:
        定数フィールド値

      • ONELEVEL_SCOPE

        static final int ONELEVEL_SCOPE
        ターゲットに指定されたコンテキストのオブジェクトに関するイベントを通知するかどうかを指定する定数です。ターゲットに指定されたコンテキストは除きます。

        この定数の値は1です。

        関連項目:
        定数フィールド値

      • SUBTREE_SCOPE

        static final int SUBTREE_SCOPE
        ターゲットに指定されたコンテキストのサブツリーにあるオブジェクトに関するイベントを、通知するかどうかを指定する定数です。ターゲットに指定されたオブジェクトも含みます。

        この定数の値は2です。

        関連項目:
        定数フィールド値

    • メソッドの詳細

      • addNamingListener

        void addNamingListener​(Name target,
                       int scope,
                       NamingListener l)
                throws NamingException
        リスナーを追加して、ターゲットおよびスコープで特定オブジェクトの変更時にトリガーされた、名前付きイベントを受け取れるようにします。 これらイベントのイベント・ソースがこのコンテキストになります。 イベント・ソースおよびターゲットについてはクラスの説明を参照してください。 scopeがどのように登録に影響するかについては、定数OBJECT_SCOPE、ONELEVEL_SCOPE、およびSUBTREE_SCOPEの説明を参照してください。

        targetがコンテキストを指定する必要があるのは、scopeがONELEVEL_SCOPEである場合のみです。scopeがOBJECT_SCOPEまたはSUBTREE_SCOPEのいずれかの場合、targetは非コンテキストを指定できます。 たとえば、targetがコンテキストかどうかが事前にわからない場合に、呼出し側がtargetをルートとするサブツリー(存在しない場合もある)を登録するときは、SUBTREE_SCOPEを非コンテキストに使用すると便利な場合があります。

        リスナーがイベントの通知を受け取ると、addNamingListener()が実行されていないスレッドでリスナーが起動されます。 複数のスレッドが同時に同じEventContextにアクセスしている場合は注意が必要です。 スレッドの問題の詳細は、「パッケージの説明」を参照してください。

        パラメータ:
        target - このコンテキストに関連して解釈されるnull以外の名前。
        scope - OBJECT_SCOPE、ONELEVEL_SCOPE、SUBTREE_SCOPEのいずれか。
        l - null以外のリスナー。
        例外:
        NamingException - リスナーの追加中に問題が検出された場合。
        関連項目:
        removeNamingListener(javax.naming.event.NamingListener)

      • addNamingListener

        void addNamingListener​(String target,
                       int scope,
                       NamingListener l)
                throws NamingException
        リスナーを追加して、文字列のターゲット名およびスコープで特定したオブジェクトの変更時に、トリガーされた名前付きイベントを受け取れるようにします。 詳細は、Nameを受け取るオーバーロードを参照してください。
        パラメータ:
        target - このコンテキストを基準にして解決されたオブジェクトのnull以外の文字列名。
        scope - OBJECT_SCOPE、ONELEVEL_SCOPE、SUBTREE_SCOPEのいずれか。
        l - null以外のリスナー。
        例外:
        NamingException - リスナーの追加中に問題が検出された場合。
        関連項目:
        removeNamingListener(javax.naming.event.NamingListener)

      • removeNamingListener

        void removeNamingListener​(NamingListener l)
                   throws NamingException
        リスナーを削除して、このEventContextによってトリガーされたネーミング・イベントを受信できないようにします。 このEventContextを使用し、おそらく別のターゲット/スコープ引数を用いて、1回以上リスナー登録を行なった可能性があります。 このメソッドの起動後は、リスナーはイベント・ソースとして、このEventContextインスタンスでイベントを受け取ることができません(ディスパッチ処理中のイベントは除く)。 リスナーがこのEventContextインスタンスに登録されていない場合、このメソッドは何も実行しません。
        パラメータ:
        l - null以外のリスナー。
        例外:
        NamingException - リスナーの削除中に問題が見つかった場合。
        関連項目:
        addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener)

      • targetMustExist

        boolean targetMustExist()
                 throws NamingException
        存在しないターゲットで、リスナーが配信処理を登録できるかどうか判定します。
        戻り値:
        ターゲットが存在する必要がある場合はtrue。ターゲットが存在する必要がない場合はfalse。
        例外:
        NamingException - このコンテキスト動作が判定できない場合。