- すべてのスーパー・インタフェース:
Context
,DirContext
- 既知のすべての実装クラス:
InitialLdapContext
javax.naming.directory.DirContext
をかわりに使用する必要があります。
コントロールの使用についての詳細
このインタフェースは、LDAP v3コントロールをサポートします。 このサポートでは、ユーザー・プログラムが、ユーザー・プログラムのContext
/DirContext
メソッドの呼び出し中に実行されるLDAP操作のリクエスト制御を設定し、LDAP操作によって発生するレスポンス制御を読み取ることができます。 実装レベルでは、要求コントロールと応答コントロールを正しく使用するために、ユーザー・プログラムおよびサービス・プロバイダ両方の開発者が理解する必要のある詳細事項があります。
RequestControls
要求コントロールには次の2つのタイプがあります。
- 接続の作成方法に影響する要求コントロール
- コンテキスト・メソッドに影響する要求コントロール
明示的に指定されていない場合、要求コントロールという用語はコンテキスト要求コントロールのことです。
コンテキスト要求コントロール
コンテキスト・インスタンスが要求コントロールを取得する方法は2つあります。ldapContext.newInstance(reqCtls)
ldapContext.setRequestControls(reqCtls)
ldapContext
はLdapContext
のインスタンスです。 reqCtls
にnull
または空の配列を指定すると、リクエスト制御は行われません。newInstance()
は、reqCtls
を使用してコンテキストの新規インスタンスを作成しますが、setRequestControls()
は、既存のコンテキスト・インスタンスのリクエスト制御をreqCtls
に更新します。
環境プロパティとは異なり、コンテキスト・インスタンスの要求コントロールは、そのインスタンスから派生したコンテキスト・インスタンスによって継承されません。 導出されたコンテキスト・インスタンスには、コンテキスト・リクエスト制御としてnull
があります。 setRequestControls()
を使用して、導出コンテキスト・インスタンスのリクエスト制御を明示的に設定する必要があります。
コンテキスト・インスタンスのリクエスト制御は、メソッドgetRequestControls()
を使用して取得されます。
接続要求コントロール
接続要求コントロールを設定する3つの方法があります。new InitialLdapContext(env, connCtls)
refException.getReferralContext(env, connCtls)
ldapContext.reconnect(connCtls);
refException
はLdapReferralException
のインスタンスで、ldapContext
はLdapContext
のインスタンスです。 null
またはconnCtls
に空の配列を指定すると、接続リクエスト制御が行われません。
環境プロパティと同様に、コンテキストの接続要求コントロールは、そのコンテキストから派生したコンテキストによって継承されます。 通常は、InitialLdapContext
コンストラクタまたはLdapReferralContext.getReferralContext()
を使用して、接続リクエスト制御を初期化します。 これらの接続要求コントロールは、同じ接続を共有しているコンテキストつまり、初期コンテキストまたは参照コンテキストから派生したコンテキストによって継承されます。
reconnect()
を使用して、コンテキストの接続リクエスト制御を変更します。 ldapContext.reconnect()
の起動は、ldapContext
によって使用される接続と、ldapContext
から導出された新しいコンテキスト・インスタンスにのみ影響します。 以前にldapContext
で接続を共有していたコンテキストは変更されません。 つまり、コンテキストの接続要求コントロールは明示的に変更される必要があり、別のコンテキストの接続要求コントロールが変更されても影響を受けません。
コンテキスト・インスタンスの接続リクエスト制御は、メソッドgetConnectControls()
を使用して取得されます。
サービス・プロバイダの要求
サービス・プロバイダは、接続およびコンテキストの要求コントロールを次のようにサポートします。 コンテキスト要求コントロールはコンテキスト・インスタンスごとに関連付け、接続要求コントロールは接続インスタンスごとに関連付ける必要があります。 サービス・プロバイダは、環境プロパティ「java.naming.ldap.control.connect」内で接続要求コントロールを検索し、この環境プロパティをプロバイダが作成するコンテキスト・インスタンスに引き渡さなければいけません。応答コントロール
メソッドLdapContext.getResponseControls()
は、Context
/DirContext
操作の呼出しの結果として実行されたLDAP操作によって生成されたレスポンス制御を取得するために使用されます。 この結果は、暗黙的な再接続を含むLDAP操作のもとで生成されたすべての応答コントロールです。 再接続レスポンス制御のみを取得するには、reconnect()
に続けてgetResponseControls()
を指定します。
Parameters
任意のメソッドにパラメータとして渡されたControl[]
配列は、コール元が所有します。 サービス・プロバイダは、配列を変更したり、配列への参照を保持したりしませんが、配列内の個々のControl
オブジェクトへの参照を保持する場合があります。 どのメソッドからも返されたControl[]
配列は不変であり、その後、コール元またはサービス・プロバイダによって変更されることはありません。 - 導入されたバージョン:
- 1.3
- 関連項目:
-
フィールドのサマリー
フィールドインタフェース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
インタフェースjavax.naming.directory.DirContextで宣言されているフィールド
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
-
メソッドのサマリー
修飾子と型メソッド説明extendedOperation
(ExtendedRequest request) 拡張操作を実行します。Control[]
このコンテキストに有効な接続要求コントロールを取得します。Control[]
このコンテキストに有効な要求コントロールを取得します。Control[]
このコンテキストで最後に呼び出されたメソッドの結果として生成された応答コントロールを取得します。newInstance
(Control[] requestControls) このコンテキストの新しいインスタンスを要求コントロールを使って生成します。void
指定されたコントロールとこのコンテキスト環境を使ってLDAPサーバーに再接続します。void
setRequestControls
(Control[] requestControls) このコンテキストで引き続き呼び出されるメソッドに要求コントロールを設定します。インタフェース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
インタフェース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
-
フィールド詳細
-
CONTROL_FACTORIES
static final String CONTROL_FACTORIES使用するコントロール・ファクトリのリストを指定するための、環境プロパティの名前を保持する定数です。 プロパティの値は、指定された別のコントロールからコントロールを作成する、ファクトリ・クラスの完全指定クラス名のコロンで区切ったリストにする必要があります。 詳細は、ControlFactory.getControlInstance()
を参照してください。 このプロパティは、環境、システム・プロパティ、または1つ以上のリソース・ファイルで指定できます。この定数の値は"java.naming.factory.control"です。
- 関連項目:
-
-
メソッドの詳細
-
extendedOperation
拡張操作を実行します。 このメソッドを使用して、LDAPv3拡張操作をサポートします。- パラメータ:
request
- 実行されるnull以外の要求。- 戻り値:
- 操作のnullの可能性がある応答。nullは操作によって応答が生成されなかったを示す。
- 例外:
NamingException
- 拡張操作の実行中にエラーが発生した場合。
-
newInstance
このコンテキストの新しいインスタンスを要求コントロールを使って生成します。 このメソッドは、マルチ・スレッドのアクセスのためにこのコンテキスト・インスタンスを新たに作成する便利な手法です。 たとえば、複数のスレッドで個別のコンテキスト要求コントロールを使用する場合は、スレッドごとにこのメソッドを使用して、コンテキストの独自のコピーの取得、およびコンテキスト要求コントロールの設定と取得を行うことができます。このとき、他のスレッドと同期化する必要はありません。新規コンテキストには、このコンテキストと同じ環境プロパティ、接続要求コントロールがあります。 詳細については、クラスの説明を参照してください。 このコンテキストと新規コンテキストの間で、同じネットワーク接続またはその他のリソースを共有することもできます。ただし、各コンテキストの間で競合が発生する場合は、共有できません。
- パラメータ:
requestControls
- 新しいコンテキストに使用するnullの可能性がある要求コントロール。 nullの場合は、要求コントロールを使用しないで初期化される。- 戻り値:
- null以外の
LdapContext
インスタンス。 - 例外:
NamingException
- 新しいインスタンスの作成中にエラーが発生した場合。- 関連項目:
-
reconnect
void reconnect(Control[] connCtls) throws NamingException 指定されたコントロールとこのコンテキスト環境を使ってLDAPサーバーに再接続します。このメソッドは、LDAPのバインド操作を明示的に初期化する方法です。 このメソッドを使って、LDAPバインド操作に要求コントロールを設定したり、またはその操作によって返される応答コントロールを取得するために明示的にサーバーに接続できます。
このメソッドは、このコンテキストの
connCtls
を新しい接続リクエスト制御に設定します。 このコンテキストのコンテキスト要求コントロールは影響を受けません。 このメソッドの起動後、connCtls
を使用して後続の暗黙的な再接続が実行されます。connCtls
は、このコンテキストから導出された新しいコンテキスト・インスタンスの接続リクエスト制御としても使用されます。 これらの接続リクエスト制御は、setRequestControls()
の影響を受けません。実装の詳細については、実装側であるサービス・プロバイダは、クラスの「サービス・プロバイダ」セクションをよく読んでください。
- パラメータ:
connCtls
- 使用するnullの可能性があるコントロール。 nullの場合、コントロールが使用されない。- 例外:
NamingException
- 再接続中にエラーが発生した場合。- 関連項目:
-
getConnectControls
Control[] getConnectControls() throws NamingExceptionこのコンテキストに有効な接続要求コントロールを取得します。 コントロールは、JNDI実装が所有していて、不変です。 配列、コントロールのどちらも、呼出し側は変更できません。- 戻り値:
- コントロールのnullの可能性がある配列。nullは、このコンテキストに対して接続コントロールが設定されていないことを示す。
- 例外:
NamingException
- 要求コントロールの取得中にエラーが発生した場合。
-
setRequestControls
void setRequestControls(Control[] requestControls) throws NamingException このコンテキストで引き続き呼び出されるメソッドに要求コントロールを設定します。 この要求コントロールは、JNDI実装が所有していて、不変です。 配列、コントロールのどちらも、呼出し側は変更できません。これにより、以前のリクエスト制御がすべて削除され、このコンテキストで起動された後続のメソッドで使用するための
requestControls
が追加されます。 このメソッドは、このコンテキストの接続要求コントロールには影響を与えません。requestControls
は、setRequestControls()
の次の呼出しまで有効になります。null
または空の配列を指定してsetRequestControls()
を明示的に起動し、コンテキスト・メソッドに影響を与えないようにコントロールをクリアする必要があります。 このコンテキストで有効なリクエスト・コントロールを確認するには、getRequestControls()
を使用します。- パラメータ:
requestControls
- 使用するnullの可能性があるコントロール。 nullの場合、コントロールが使用されない。- 例外:
NamingException
- 要求コントロールの設定中にエラーが発生した場合。- 関連項目:
-
getRequestControls
Control[] getRequestControls() throws NamingExceptionこのコンテキストに有効な要求コントロールを取得します。 この要求コントロールは、JNDI実装が所有していて、不変です。 配列、コントロールのどちらも、呼出し側は変更できません。- 戻り値:
- コントロールのnullの可能性がある配列。nullは、このコンテキストに対して要求コントロールが設定されていないことを示す。
- 例外:
NamingException
- 要求コントロールの取得中にエラーが発生した場合。- 関連項目:
-
getResponseControls
Control[] getResponseControls() throws NamingExceptionこのコンテキストで最後に呼び出されたメソッドの結果として生成された応答コントロールを取得します。 この応答コントロールは、JNDI実装が所有していて、不変です。 配列、コントロールのどちらも、呼出し側は変更できません。これらの応答コントロールには、正常に終了した操作または失敗した操作によって生成されたものがあります。
レスポンス制御を返すコンテキスト・メソッドが呼び出されると、前のメソッド呼出しからのレスポンス制御がクリアされます。
getResponseControls()
は、LDAPサーバーから受信された順序でコンテキスト・メソッドによって使用されるLDAP操作によって生成されたすべてのレスポンス制御を返します。getResponseControls()
を起動しても、レスポンス制御はクリアされません。 コントロールを返すことができる次のコンテキスト・メソッドが呼び出されるまで何度でも呼び出したり、同じコントロールを戻したりすることが可能です。- 戻り値:
- nullの可能性があるコントロールの配列。 nullの場合、このコンテキストで呼び出された以前のメソッドはコントロールを生成していない。
- 例外:
NamingException
- 応答コントロールの取得中にエラーが発生した場合。
-