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

インタフェースLdapContext

すべてのスーパー・インタフェース:
Context, DirContext
既知のすべての実装クラス:
InitialLdapContext
public interface LdapContext extends DirContext
このインタフェースは、LDAPv3スタイルのコントロールを持つ操作とLDAPv3スタイルの拡張操作を実行できるコンテキストを表します。 このような制御や拡張操作を必要としないアプリケーションでは、より汎用的なjavax.naming.directory.DirContextをかわりに使用する必要があります。

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

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

RequestControls

要求コントロールには次の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. new InitialLdapContext(env, connCtls)
  2. refException.getReferralContext(env, connCtls)
  3. 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()を指定します。

パラメータ

任意のメソッドにパラメータとして渡されたControl[]配列は、コール元が所有します。 サービス・プロバイダは、配列を変更したり、配列への参照を保持したりしませんが、配列内の個々のControlオブジェクトへの参照を保持する場合があります。 どのメソッドからも返されたControl[]配列は不変であり、その後、コール元またはサービス・プロバイダによって変更されることはありません。
導入されたバージョン:
1.3
関連項目:

  • フィールド詳細

    • CONTROL_FACTORIES

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

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

      関連項目:

  • メソッドの詳細

    • extendedOperation

      ExtendedResponse extendedOperation(ExtendedRequest request) throws NamingException
      拡張操作を実行します。 このメソッドを使用して、LDAPv3拡張操作をサポートします。
      パラメータ:
      request - 実行されるnull以外の要求。
      戻り値:
      操作のnullの可能性がある応答。nullは操作によって応答が生成されなかったを示す。
      例外:
      NamingException - 拡張操作の実行中にエラーが発生した場合。

    • newInstance

      LdapContext newInstance(Control[] requestControls) throws NamingException
      このコンテキストの新しいインスタンスを要求コントロールを使って生成します。 このメソッドは、マルチ・スレッドのアクセスのためにこのコンテキスト・インスタンスを新たに作成する便利な手法です。 たとえば、複数のスレッドで個別のコンテキスト要求コントロールを使用する場合は、スレッドごとにこのメソッドを使用して、コンテキストの独自のコピーの取得、およびコンテキスト要求コントロールの設定と取得を行うことができます。このとき、他のスレッドと同期化する必要はありません。

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

      パラメータ:
      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 - 応答コントロールの取得中にエラーが発生した場合。