javax.naming.ldap
インタフェース LdapContext

すべてのスーパーインタフェース:

Context, DirContext

既知の実装クラスの一覧:

InitialLdapContext

public interface LdapContext

extends DirContext

このインタフェースは、LDAPv3 スタイルのコントロールを持つ操作と LDAPv3 スタイルの拡張操作を実行できるコンテキストを表します。 このようなコントロールまたは拡張操作のどちらも必要としないアプリケーションの場合、最も汎用的な javax.naming.directory.DirContext を代わりに使用する必要があります。

コントロールの使用についての詳細

このインタフェースは、LDAP v3 コントロールをサポートします。高いレベルでこのサポートを使用すると、ユーザプログラムで Context/DirContext メソッドを呼び出しているうちに、実行される LDAP 操作の要求コントロールをユーザプログラムが設定し、LDAP 操作による結果としての応答コントロールの読み込みを可能にします。実装レベルでは、要求コントロールと応答コントロールを正しく使用するために、ユーザプログラムおよびサービスプロバイダ両方の開発者が理解する必要のある詳細事項があります。

要求コントロール

要求コントロールには次の 2 つのタイプがあります。

• 接続の作成方法に影響する要求コントロール
• コンテキストメソッドに影響する要求コントロール

接続の作成方法に影響する要求コントロールは、LDAP サーバとの接続の設定または再設定のどちらの場合でも使用されます。コンテキストメソッドに影響する要求コントロールは、他のすべての LDAP 操作が LDAP サーバに送られるときに使用されます。これら 2 つの要求コントロールに違いが生じるのは、JNDI が高レベル API で接続を直接処理しないためです。必要な接続管理を行うのがサービスプロバイダのジョブです。したがって、単一の接続は複数のコンテキストインスタンスによって共有されることがあります。サービスプロバイダは、自由に自分のアルゴリズムを使用して接続とネットワークの使用を保護します。このように、メソッドがそのコンテキストインスタンス上で呼び出されると、サービスプロバイダは、LDAP の操作への対応を実行するだけでなく、接続管理をしなければならない場合もあります。接続管理の場合、サービスプロバイダは接続要求コントロールを使用します。通常の LDAP 操作のときは、コンテキスト要求コントロールを使用します。

明示的に指定されていない場合、要求コントロールという用語はコンテキスト要求コントロールのことです。

コンテキスト要求コントロール

コンテキストインスタンスが要求コントロールを取得する方法は 2 つあります。

1. ldapContext.newInstance(reqCtls)
2. ldapContext.setRequestControls(reqCtls)

ldapContext は LdapContext のインスタンスのです。reqCtls に null または空の配列を指定すると、要求コントロールがないことを示します。newInstance() は、reqCtls を使って新しいインスタンスを作成します。setRequestControls() は、既存のコンテキストインスタンスの要求コントロールを reqCtls に更新します。

環境プロパティとは異なり、コンテキストインスタンスの要求コントロールは、そのインスタンスから派生したコンテキストインスタンスによって継承されません。派生したコンテキストインスタンスのコンテキスト要求コントロールは null になります。派生したコンテキストインスタンスの要求コントロールを、明示的に setRequestControls() を使って設定する必要があります。

コンテキストインスタンスの要求コントロールは、メソッド getRequestControls() を使って検出されます。

接続要求コントロール

接続要求コントロールを設定する 3 つの方法があります。

1. 新規の InitialLdapContext(env, connCtls)
2. refException.getReferralContext (env, connCtls)
3. ldapContext.reconnect(connCtls) ;

where refException は LdapReferralException のインスタンスです。ldapContext は LdapContext のインスタンスです。connCtls に null または空の配列を指定すると、接続要求コントロールがないことを示します。

環境プロパティと同様に、コンテキストの接続要求コントロールは、そのコンテキストから派生したコンテキストによって継承されます。通常は、InitialLdapContext コンストラクタ、または LdapReferralContext.getReferralContext() を使用して、接続要求コントロールを初期化します。これらの接続要求コントロールは、同じ接続を共有しているコンテキストつまり、初期コンテキストまたは参照コンテキストから派生したコンテキストによって継承されます。

コンテキストの接続要求コントロールを変更するには、reconnect() 使用します。ldapContext.reconnect() を呼び出すと、ldapContext と ldapContext から派生した新しいコンテキストインスタンスで使用されている接続にだけ影響します。ldapContext との接続を以前から共有しているコンテキストは、影響を受けません。つまり、コンテキストの接続要求コントロールは明示的に変更される必要があり、コンテキストの接続要求コントロールを変更しても影響を受けません。

コンテキストインスタンスの接続要求コントロールは、メソッド getConnectControls() を使って検出されます。

サービスプロバイダの要求

サービスプロバイダは、接続およびコンテキストの要求コントロールを次のようにサポートします。コンテキスト要求コントロールはコンテキストインスタンスごとに関連付け、接続要求コントロールは接続インスタンスごとに関連付けます。サービスプロバイダは、環境プロパティ「java.naming.ldap.control.connect」内で接続要求コントロールを検索し、この環境プロパティをプロバイダが作成するコンテキストインスタンスに引き渡さなければなりません。

応答コントロール

LdapContext.getResponseControls() というメソッドは、Context/DirContext の操作を呼び出した結果行われた LDAP 操作で生成された応答コントロールを検出するのに使用されます。この結果は、暗黙的な再接続を含む LDAP 操作のもとで生成されたすべての応答コントロールです。再接続応答コントロールだけを取得するには、reconnect() とそれに続く getResponseControls() を使用します。

パラメータ

すべてのメソッドにパラメータとして渡される Control[] 配列は、呼び出し側が所有します。サービスプロバイダは配列を変更せず、その配列に対する参照も保持しませんが、配列内の個別の Control オブジェクトに対する参照を保持することがあります。すべてのメソッドで返される Control[] 配列は不変で、この配列が返された後も、呼び出し側またはサービスプロバイダのどちらもこの配列を変更することはできません。

導入されたバージョン:

1.3

関連項目:

InitialLdapContext, LdapReferralException.getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])

フィールドの概要

static String

CONTROL_FACTORIES 使用するコントロールファクトリのリストを指定するための、環境プロパティの名前を保持する定数です。

インタフェース javax.naming.directory.DirContext から継承したフィールド

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

インタフェース 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

メソッドの概要

ExtendedResponse	extendedOperation(ExtendedRequest request) 拡張操作を実行します。
Control[]	getConnectControls() このコンテキストに有効な接続要求コントロールを検出します。
Control[]	getRequestControls() このコンテキストに有効な要求コントロールを検出します。
Control[]	getResponseControls() このコンテキストで最後に呼び出されたメソッドの結果として生成された応答コントロールを検出します。
LdapContext	newInstance(Control[] requestControls) このコンテキストの新しいインスタンスを要求コントロールを使って生成します。
void	reconnect(Control[] connCtls) 指定されたコントロールとこのコンテキスト環境を使って LDAP サーバに再接続します。
void	setRequestControls(Control[] requestControls) このコンテキストで引き続き呼び出されるメソッドに要求コントロールを設定します。

インタフェース javax.naming.directory.DirContext から継承したメソッド

bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search

インタフェース 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

フィールドの詳細

CONTROL_FACTORIES

public static final String CONTROL_FACTORIES

使用するコントロールファクトリのリストを指定するための、環境プロパティの名前を保持する定数です。プロパティの値は、指定された別のコントロールからコントロールを作成する、ファクトリクラスの完全修飾クラス名のコロンで区切ったリストにする必要があります。詳細については、ControlFactory.getControlInstance() を参照してください。このプロパティは、環境、アプレットパラメータ、システムプロパティ、または 1 つ以上のリソースファイルで指定されます。

この定数の値は "java.naming.factory.control" です。

関連項目:

ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), 定数フィールド値

メソッドの詳細

extendedOperation

public ExtendedResponse extendedOperation(ExtendedRequest request)
                                   throws NamingException

拡張操作を実行します。このメソッドを使用して、LDAPv3 拡張操作をサポートします。

パラメータ:

request - 実行する null 以外の要求

戻り値:

null の可能性がある操作の応答。null は、操作をしても応答は何も生成されないことを示す

例外:

NamingException - 拡張操作実行中に、エラーが発生した場合

newInstance

public LdapContext newInstance(Control[] requestControls)
                        throws NamingException

このコンテキストの新しいインスタンスを要求コントロールを使って生成します。このメソッドは、マルチスレッドのアクセスのためにこのコンテキストインスタンスを新たに作成する便利な手法です。たとえば、複数のスレッドがそれぞれ異なるコンテキスト要求コントロールを使用したい場合、各スレッドは、他のスレッドと同期する必要なく、このメソッドを使用して、このコンテキストのその独自のコピーを取得して、コンテキスト要求コントロールを設定または取得できます。

新規コンテキストには、このコンテキストと同じ環境プロパティ、接続要求コントロールがあります。詳細については、クラスについての記述を参照してください。このコンテキストと新規コンテキストの間で、同じネットワーク接続またはその他のリソースを共有することもできます。ただし、各コンテキストの間で競合が発生する場合は、共有できません。

パラメータ:

requestControls - 新しいコンテキストに使用する null の可能性がある要求コントロール。null の場合は、要求コントロールを使用しないで初期化される

戻り値:

null 以外の LdapContext インスタンス

例外:

NamingException - 新規インスタンスの作成中に、エラーが発生した場合

関連項目:

InitialLdapContext

reconnect

public void reconnect(Control[] connCtls)
               throws NamingException

指定されたコントロールとこのコンテキスト環境を使って LDAP サーバに再接続します。

このメソッドは、LDAP のバインド操作を明示的に初期化する方法です。このメソッドを使って、LDAP バインド操作に要求コントロールを設定したり、またはその操作によって返される応答コントロールを取得するために明示的にサーバに接続できます。

このメソッドでは、このコンテキストの connCtls を新規接続要求コントロールとなるように設定します。このコンテキストのコンテキスト要求コントロールは影響を受けません。このメソッドが呼び出されると、その後に続く暗黙的な再接続が connCtls を使用して実行されます。connCtls はまた、接続要求コントロールとして、このコンテキストから派生した新規コンテキストインスタンスにも使用されます。これらの接続要求コントロールは、setRequestControls() の影響を受けません。

実装の詳細については、実装側であるサービスプロバイダは、クラスの「サービスプロバイダ」セクションをよく読んでください。

パラメータ:

connCtls - null の可能性がある使用するためのコントロール。null の場合、コントロールは使用されない

例外:

NamingException - 再接続中にエラーが発生した場合

関連項目:

getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

public Control[] getConnectControls()
                             throws NamingException

このコンテキストに有効な接続要求コントロールを検出します。コントロールは、JNDI 実装が所有していて、不変です。配列、コントロールのどちらも呼び出し側は変更できません。

戻り値:

null の可能性があるコントロールの配列。null は、このコンテキストに対してコントロールが設定されていないことを示す

例外:

NamingException - 要求コントロールの取得中に、エラーが発生した場合

setRequestControls

public void setRequestControls(Control[] requestControls)
                        throws NamingException

このコンテキストで引き続き呼び出されるメソッドに要求コントロールを設定します。この要求コントロールは、JNDI 実装が所有していて、不変です。配列、コントロールのどちらも呼び出し側は変更できません。

以前の要求コントロールをすべて削除し、引き続きこのコンテキストで呼び出されるメソッドが使用するために requestControls を追加します。

requestControls は、次に setRequestControls() を呼び出すまで有効です。これ以上コンテキストメソッドに影響を与えたくない場合は、コントロールを解除するために、null または空の配列を持つ setRequestControls() を明示的に呼び出す必要があります。このコンテキストにはどの要求コントロールが効果的なのか確認するには、getRequestControls() を使用します。

パラメータ:

requestControls - null の可能性がある使用するためのコントロール。null の場合、コントロールは使用されない

例外:

NamingException - 要求コントロールの設定中に、エラーが発生した場合

関連項目:

getRequestControls()

getRequestControls

public Control[] getRequestControls()
                             throws NamingException

このコンテキストに有効な要求コントロールを検出します。この要求コントロールは、JNDI 実装が所有していて、不変です。配列、コントロールのどちらも呼び出し側は変更できません。

戻り値:

null の可能性があるコントロールの配列。null は、このコンテキストに対して要求コントロールが設定されていないことを示す

例外:

NamingException - 要求コントロールの取得中に、エラーが発生した場合

関連項目:

setRequestControls(javax.naming.ldap.Control[])

getResponseControls

public Control[] getResponseControls()
                              throws NamingException

このコンテキストで最後に呼び出されたメソッドの結果として生成された応答コントロールを検出します。この応答コントロールは、JNDI 実装が所有していて、不変です。配列、コントロールのどちらも呼び出し側は変更できません。

これらの応答コントロールには、正常に終了した操作または失敗した操作によって生成されたものがあります。

応答コントロールを返すことができるコンテキストメソッドが呼び出されると、以前のメソッド呼び出しからの応答コントロールはすべて解除されます。getResponseControls() は、LDAP サーバから受け取った順序で、コンテキストメソッドが操作した LDAP によって生成される応答コントロールのすべてを返します。getResponseControls() を呼び出すと、以前の応答コントロールは解除されません。コントロールを返すことができる次のコンテキストメソッドが呼び出されるまで何度でも呼び出したり、同じコントロールを戻すことが可能です。

戻り値:

null の可能性があるコントロールの配置。null の場合、このコンテキストで呼び出された以前のメソッドはコントロールを生成しない

例外:

NamingException - 応答コントロールの取得中に、エラーが発生した場合