モジュール 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操作の場合はコンテキスト要求コントロールを使用します。

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

    Context Request Controls

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

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

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

    Connection Request Controls

    接続要求コントロールを設定する3つの方法があります。
    1. new InitialLdapContext(env, connCtls)
    2. refException.getReferralContext(env, connCtls)
    3. ldapContext.reconnect(connCtls);
    ここで、refExceptionはLdapReferralExceptionのインスタンス、ldapContextはLdapContextのインスタンスです。 connCtlsにnullまたは空の配列を指定すると、接続要求コントロールがないことを示します。

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

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

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

    Service Provider Requirements

    サービス・プロバイダは、接続およびコンテキストの要求コントロールを次のようにサポートします。 コンテキスト要求コントロールはコンテキスト・インスタンスごとに関連付け、接続要求コントロールは接続インスタンスごとに関連付ける必要があります。 サービス・プロバイダは、環境プロパティ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[])

    • フィールドの詳細

      • CONTROL_FACTORIES

        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

        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 - 新しいインスタンスの作成中にエラーが発生した場合。
        関連項目:
        InitialLdapContext

      • reconnect

        void reconnect​(Control[] connCtls)
        throws NamingException
        指定されたコントロールとこのコンテキスト環境を使ってLDAPサーバーに再接続します。

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

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

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

        パラメータ:
        connCtls - 使用するnullの可能性があるコントロール。 nullの場合、コントロールが使用されない。
        例外:
        NamingException - 再接続中にエラーが発生した場合。
        関連項目:
        getConnectControls(), newInstance(javax.naming.ldap.Control[])

      • 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()

      • getRequestControls

        Control[] getRequestControls()
                      throws NamingException
        このコンテキストに有効な要求コントロールを取得します。 この要求コントロールは、JNDI実装が所有していて、不変です。 配列、コントロールのどちらも、呼出し側は変更できません。
        戻り値:
        コントロールのnullの可能性がある配列。nullは、このコンテキストに対して要求コントロールが設定されていないことを示す。
        例外:
        NamingException - 要求コントロールの取得中にエラーが発生した場合。
        関連項目:
        setRequestControls(javax.naming.ldap.Control[])

      • getResponseControls

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

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

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

        戻り値:
        nullの可能性があるコントロールの配列。 nullの場合、このコンテキストで呼び出された以前のメソッドはコントロールを生成していない。
        例外:
        NamingException - 応答コントロールの取得中にエラーが発生した場合。