javax.naming.ldap
接口 LdapContext

所有超级接口：

Context, DirContext

所有已知实现类：

InitialLdapContext

public interface LdapContext
extends DirContext

此接口表示一个上下文，在该上下文中可以利用 LDAPv3 样式的控件执行操作，并且可以执行 LDAPv3 样式的扩展操作。 对于不需要这些控件或扩展操作的应用程序，则应该使用更一般的 javax.naming.directory.DirContext 来代替。

关于控件的使用细节

此接口提供对 LDAP v3 控件的支持。在较高级别，这一支持允许用户程序为用户程序调用 Context/DirContext 方法期间执行的 LDAP 操作设置请求控件，并读取从 LDAP 操作得到的响应控件。在实现级别，有些细节用户程序和服务提供程序的开发人员都需要理解才能正确地使用请求控件和响应控件。

请求控件

请求控件有两种类型：

• 影响连接的创建方式的请求控件
• 影响上下文方法的请求控件

在需要利用 LDAP 服务器建立或重新建立连接时使用前者。在将所有其他 LDAP 操作发送到 LDAP 服务器时使用后者。两种类型的请求控件之间必须存在差别的原因是， JNDI 是一种不直接处理连接的高级 API。服务提供程序负责进行所有必需的连接管理。因此，多个上下文实例可能共享单个连接，并且服务提供程序可以自由地使用它自己的算法保存连接和网络使用。对上下文实例调用方法时，服务提供程序除了执行相应的 LDAP 操作，可能还需要进行一些连接管理。对于连接管理，它使用连接请求控件，而对于常规 LDAP 操作，它使用上下文请求控件。

如果没有显式限定，术语“请求控件”就是指上下文请求控件。

上下文请求控件

上下文实例获取其请求控件有两种方式：

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

其中 ldapContext 是 LdapContext 的实例。为 reqCtls 指定 null 或空数组意味着不存在请求控件。newInstance() 使用 reqCtls 创建上下文的新实例，而 setRequestControls() 将现有上下文实例的请求控件更新为 reqCtls。

与环境属性不同，从某个上下文实例派生的上下文实例不能继承 它的请求控件。派生的上下文实例的上下文请求控件为 null。必须使用 setRequestControls() 显式设置派生的上下文实例的请求控件。

上下文实例的请求控件需要使用方法 getRequestControls() 进行检索。

连接请求控件

可以使用三种方式设置连接请求控件：

1. new InitialLdapContext(env, connCtls)
2. refException.getReferralContext(env, connCtls)
3. ldapContext.reconnect(connCtls);

其中 refException 是 LdapReferralException 的实例，ldapContext 是 LdapContext 的实例。为 connCtls 指定 null 或空数组意味着不存在连接请求控件。

与环境属性一样，从上下文派生的上下文可以继承 它的连接请求控件。通常，使用 InitialLdapContext 构造方法或 LdapReferralContext.getReferralContext() 来初始化连接请求控件。这些连接请求控件可以由共享同一连接的上下文继承，即上下文是从初始或反向链接 (referral) 上下文派生的。

使用 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()。此属性可以在环境、applet 参数、系统属性或者一个或多个资源文件中指定。

此常量的值是 "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“绑定”操作设置请求控件，或者显式连接到服务器以获取由 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 供在此上下文上调用的后续方法使用。此方法不影响此上下文的连接请求控件。

注意，在下一次调用 setRequestControls() 之前 requestControls 一直有效。如果不想让这些控件继续影响上下文方法，则需要使用 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 - 如果在获取响应控件时出错。