模块 java.naming
包 javax.naming.ldap

类 InitialLdapContext

java.lang.Object
javax.naming.InitialContext
javax.naming.directory.InitialDirContext
javax.naming.ldap.InitialLdapContext
所有已实现的接口：
Context , DirContext , LdapContext
public class InitialLdapContext extends InitialDirContext implements LdapContext
此类是执行 LDAPv3 样式扩展操作和控制的起始上下文。

有关同步的详细信息以及有关如何创建初始上下文的策略，请参阅 javax.naming.InitialContext 和 javax.naming.InitialDirContext。

请求控制

当您创建一个初始上下文 (InitialLdapContext) 时，您可以指定一个请求控件列表。这些控件将用作由上下文或从上下文派生的上下文执行的任何隐式 LDAP“绑定”操作的请求控件。这些被称为 connection request controls 。使用 getConnectControls() 获取上下文的连接请求控件。

提供给初始上下文构造函数的请求控件not用作后续上下文操作（例如搜索和查找）的上下文请求控件。使用 setRequestControls() 设置和更新上下文请求控件。

如图所示，可以有两组不同的请求控件与上下文关联：连接请求控件和上下文请求控件。对于那些需要发送可能不适用于上下文操作和任何隐式 LDAP“绑定”操作的关键控制的应用程序来说，这是必需的。典型的用户程序会执行以下操作：

 InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
 lctx.setRequestControls(critModCtls);
 lctx.modifyAttributes(name, mods);
 Controls[] respCtls = lctx.getResponseControls();
它首先指定用于创建初始上下文 (critConnCtls) 的关键控件，然后为上下文操作设置上下文的请求控件 (critModCtls)。如果由于某种原因 lctx 需要重新连接到服务，它将使用 critConnCtls 。有关请求控制的更多讨论，请参阅 LdapContext 接口。

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

自从：
1.3
参见：

  • 构造方法详细信息

    • InitialLdapContext

      public InitialLdapContext() throws NamingException
      构造一个不使用环境属性或连接请求控件的初始上下文。相当于 new InitialLdapContext(null, null) 。
      抛出：
      NamingException - 如果遇到命名异常

    • InitialLdapContext

      public InitialLdapContext(Hashtable <?,?> environment, Control [] connCtls) throws NamingException
      使用环境属性和连接请求控件构造初始上下文。有关环境属性的讨论，请参阅 javax.naming.InitialContext。

      此构造函数不会修改其参数或保存对它们的引用，但可能会保存克隆或副本。 environment 传递给构造函数后，调用者不应修改可变键和值。

      connCtls 用作底层上下文实例的连接请求控件。有关详细信息，请参阅类描述。

      参数：
      environment - 用于创建初始 DirContext 的环境。 Null 表示空环境。
      connCtls - 初始上下文的连接请求控件。如果为空，则不使用连接请求控件。
      抛出：
      NamingException - 如果遇到命名异常
      参见：

  • 方法详情

    • extendedOperation

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

    • newInstance

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

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

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

    • reconnect

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

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

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

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

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

    • getConnectControls

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

    • setRequestControls

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

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

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

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

    • getRequestControls

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

    • getResponseControls

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

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

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

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