模块 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 操作产生的响应控制。在实现级别，用户程序和服务提供者的开发人员都需要了解一些细节，以便正确使用请求和响应控件。

请求控制

有两种类型的请求控件：

  • 影响连接创建方式的请求控件
  • 影响上下文方法的请求控件
每当需要与 LDAP 服务建立或重新建立连接时，都会使用前者。后者在所有其他 LDAP 操作都发送到 LDAP 服务时使用。之所以有必要区分这两种类型的请求控制，是因为 JNDI 是一种不直接处理连接的高级 API。服务提供商的工作是进行任何必要的连接管理。因此，单个连接可以由多个上下文实例共享，服务提供商可以自由使用自己的算法来节省连接和网络使用。因此，当在上下文实例上调用方法时，服务提供者除了执行相应的 LDAP 操作外，可能还需要进行一些连接管理。对于连接管理，它使用 connection request controls ，而对于正常的 LDAP 操作，它使用 context request controls 。

除非明确限定，否则术语“请求控件”是指上下文请求控件。

上下文请求控件

上下文实例获取其请求控件有两种方式：
  1. ldapContext.newInstance(reqCtls)
  2. ldapContext.setRequestControls(reqCtls)
其中 ldapContext 是 LdapContext 的实例。为 reqCtls 指定 null 或空数组意味着没有请求控制。 newInstance() 使用 reqCtls 创建上下文的新实例，而 setRequestControls() 将现有上下文实例的请求控件更新为 reqCtls 。

与环境属性不同，上下文实例 are not inherited 由派生的上下文实例请求控制。派生上下文实例将 null 作为其上下文请求控件。您必须使用 setRequestControls() 显式设置派生上下文实例的请求控件。

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

连接请求控件

设置连接请求控件的方式有以下三种：
  1. new InitialLdapContext(env, connCtls)
  2. refException.getReferralContext(env, connCtls)
  3. ldapContext.reconnect(connCtls);
其中 refException 是 LdapReferralException 的实例，ldapContext 是 LdapContext 的实例。为 connCtls 指定 null 或空数组意味着没有连接请求控件。

与环境属性一样，连接请求控制上下文 are inherited 由从中派生的上下文控制。通常，您使用 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
参见：

  • 字段详细信息

  • 方法详情

    • extendedOperation

      ExtendedResponse  extendedOperation(ExtendedRequest  request) throws NamingException
      执行扩展操作。此方法用于支持 LDAPv3 扩展操作。
      参数：
      request - 要执行的非空请求。
      返回：
      操作的可能为空的响应。 null 表示操作没有生成任何响应。
      抛出：
      NamingException - 如果在执行扩展操作时发生错误。

    • newInstance

      LdapContext  newInstance(Control [] requestControls) throws NamingException
      创建使用请求控件初始化的此上下文的新实例。此方法是为多线程访问目的创建此上下文的新实例的便捷方法。例如，如果多个线程想要使用不同的上下文请求控件，则每个线程都可以使用此方法获取自己的此上下文副本并设置/获取上下文请求控件，而无需与其他线程同步。

      新上下文与此上下文具有相同的环境属性和连接请求控件。有关详细信息，请参阅类描述。如果这样做不妨碍任一上下文的独立性，则实现也可能允许此上下文和新上下文共享相同的网络连接或其他资源。

      参数：
      requestControls - 用于新上下文的可能为空的请求控件。如果为 null，则在没有请求控件的情况下初始化上下文。
      返回：
      一个非空的 LdapContext 实例。
      抛出：
      NamingException - 如果在创建新实例时发生错误。
      参见：

    • reconnect

      void reconnect(Control [] connCtls) throws NamingException
      使用提供的控件和此上下文的环境重新连接到 LDAP 服务。

      此方法是一种显式启动 LDAP“绑定”操作的方法。例如，您可以使用此方法为 LDAP“绑定”操作设置请求控件，或者显式连接到服务以获取 LDAP“绑定”操作返回的响应控件。

      此方法将此上下文的 connCtls 设置为其新的连接请求控件。此上下文的上下文请求控件不受影响。调用此方法后，任何后续的隐式重新连接都将使用 connCtls 完成。 connCtls 也用作从此上下文派生的新上下文实例的连接请求控件。这些连接请求控件不受 setRequestControls() 的影响。

      服务提供者实现者应阅读类描述中的“服务提供者”部分以了解实现细节。

      参数：
      connCtls - 要使用的可能为空的控件。如果为 null，则不使用任何控件。
      抛出：
      NamingException - 如果重新连接时发生错误。
      参见：

    • getConnectControls

      Control [] getConnectControls() throws NamingException
      检索对此上下文有效的连接请求控件。这些控件由 JNDI 实现拥有并且是不可变的。调用者不能修改数组和控件。
      返回：
      可能为空的控件数组。 null 表示没有为此上下文设置连接控件。
      抛出：
      NamingException - 如果在获取请求控件时发生错误。

    • setRequestControls

      void setRequestControls(Control [] requestControls) throws NamingException
      为随后在此上下文中调用的方法设置请求控件。请求控件由 JNDI 实现拥有并且是不可变的。调用者不能修改数组和控件。

      这将删除任何先前的请求控件并添加 requestControls 以供在此上下文中调用的后续方法使用。此方法不影响此上下文的连接请求控件。

      请注意， requestControls 将在下一次调用 setRequestControls() 之前有效。如果您不希望控件再影响上下文方法，则需要使用 null 或空数组显式调用 setRequestControls() 以清除控件。要检查哪些请求控制对此上下文有效，请使用 getRequestControls() 。

      参数：
      requestControls - 要使用的可能为空的控件。如果为 null，则不使用任何控件。
      抛出：
      NamingException - 如果在设置请求控件时发生错误。
      参见：

    • getRequestControls

      Control [] getRequestControls() throws NamingException
      检索对此上下文有效的请求控件。请求控件由 JNDI 实现拥有并且是不可变的。调用者不能修改数组和控件。
      返回：
      可能为空的控件数组。 null 表示没有为此上下文设置请求控制。
      抛出：
      NamingException - 如果在获取请求控件时发生错误。
      参见：

    • getResponseControls

      Control [] getResponseControls() throws NamingException
      检索作为在此上下文上调用的最后一个方法的结果而生成的响应控件。响应控件由 JNDI 实现拥有并且是不可变的。调用者不能修改数组和控件。

      这些响应控件可能是由成功或失败的操作生成的。

      当调用可能返回响应控件的上下文方法时，清除来自先前方法调用的响应控件。 getResponseControls() 按照从 LDAP 服务接收到的顺序返回上下文方法使用的 LDAP 操作生成的所有响应控件。调用 getResponseControls() 不会清除响应控件。您可以多次调用它（并取回相同的控件），直到调用可能返回控件的下一个上下文方法。

      返回：
      一个可能为 null 的控件数组。如果为 null，则在此上下文中调用的先前方法不会产生任何控件。
      抛出：
      NamingException - 如果在获取响应控件时发生错误。