LdapContext (Java Platform SE 8)

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

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. 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()メソッドを使って取得されます。
サービス・プロバイダの要求
サービス・プロバイダは、接続およびコンテキストの要求コントロールを次のようにサポートします。コンテキスト要求コントロールはコンテキスト・インスタンスごとに関連付け、接続要求コントロールは接続インスタンスごとに関連付ける必要があります。サービス・プロバイダは、環境プロパティ「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
```
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 - 応答コントロールの取得中にエラーが発生した場合。

バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。

インタフェースLdapContext

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

要求コントロール

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

接続要求コントロール

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

応答コントロール

パラメータ

フィールドのサマリー

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

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

メソッドのサマリー

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

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

フィールドの詳細

CONTROL_FACTORIES

メソッドの詳細

extendedOperation

newInstance

reconnect

getConnectControls

setRequestControls

getRequestControls

getResponseControls