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

フィールドの概要

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

インタフェース javax.naming.Context から継承されたフィールド

APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

メソッドの概要

void	addNamingListener(Name target, int scope, NamingListener l) リスナーを追加して、ターゲットおよびスコープで特定オブジェクトの変更時にトリガされた、名前付きイベントを受け取れるようにします。
void	addNamingListener(String target, int scope, NamingListener l) リスナーを追加して、文字列のターゲット名およびスコープで特定したオブジェクトの変更時に、トリガされた名前付きイベントを受け取れるようにします。
void	removeNamingListener(NamingListener l) リスナーを削除して、この EventContext でトリガされたネーミングイベントを受け取れないようにします。
boolean	targetMustExist() 存在しないターゲットで、リスナーが配信処理を登録できるかどうか判定します。

インタフェース javax.naming.Context から継承されたメソッド

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

フィールドの詳細

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

リスナーを追加して、ターゲットおよびスコープで特定オブジェクトの変更時にトリガされた、名前付きイベントを受け取れるようにします。 これらイベントのイベントソースがこのコンテキストになります。イベントソースおよびターゲットについてはクラスの説明を参照してください。スコープがどのように登録に影響するかについては、定数 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 のいずれか 1 つ

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 のいずれか 1 つ

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 - このコンテキスト動作が判定できない場合