Module java.naming
Package javax.naming.ldap

Interface 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()初始化连接请求控件。这些连接请求控件将被共享相同连接的上下文继承--即从初始或引荐上下文派生的上下文。

使用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
参见:

  • Field Details

  • Method Details

    • extendedOperation

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

    • newInstance

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

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

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

    • reconnect

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

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

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

      服务提供程序实现者应阅读类描述中的“服务提供程序”部分以获取实现详细信息。

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

    • 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

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

    • getResponseControls

      Control[] getResponseControls() throws NamingException
      检索由此上下文上最后调用的方法产生的响应控件。响应控件由JNDI实现拥有并且是不可变的。调用者不能修改数组或控件。

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

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

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