模块  java.naming
软件包  javax.naming.ldap

Interface LdapContext

  • All Superinterfaces:
    Context ， DirContext
    所有已知实现类：
    InitialLdapContext 
    public interface LdapContext
extends DirContext
    此接口表示可以使用LDAPv3样式控件执行操作并执行LDAPv3样式扩展操作的上下文。 对于不需要此类控件或扩展操作的应用程序，应使用更通用的javax.naming.directory.DirContext 。

    用法详情关于控件

    此界面提供对LDAP v3控件的支持。 在高层次上，该支持允许用户程序设置请求的控制对于在的用户程序的调用的过程中执行的LDAP操作Context / DirContext方法，和读取从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共享连接的ldapContext保持不变。 也就是说，必须显式更改上下文的连接请求控件，并且不受对其他上下文的连接请求控件的更改的影响。

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

    服务提供商要求

    服务提供者通过以下方式支持连接和上下文请求控制。 上下文请求控件必须基于每个上下文实例关联，而连接请求控件必须基于每个连接实例关联。 服务提供者必须在环境属性“java.naming.ldap.control.connect”中查找连接请求控件，并将此环境属性传递给它创建的上下文实例。

    响应控制

    该方法LdapContext.getResponseControls()用于检索由作为调用的结果来执行的LDAP操作生成的响应控制Context / DirContext操作。 结果是底层LDAP操作生成的所有响应控件，包括任何隐式重新连接。 要仅获取重新连接响应控件，请使用reconnect()然后使用getResponseControls() 。

    参数

    作为参数传递给任何方法的Control[]数组由调用者拥有。 服务提供者不会修改数组或保留对数组的引用，尽管它可能会引用数组中的各个对象Control 。 任何方法返回的Control[]数组都是不可变的，随后可能不会被调用者或服务提供者修改。
    从以下版本开始：
    1.3
    另请参见：
    InitialLdapContext ， LdapReferralException.getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])

    • 方法详细信息

      • 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，则不使用任何控件。
        异常
        NamingException - 如果重新连接时发生错误。
        另请参见：
        getConnectControls() ， newInstance(javax.naming.ldap.Control[])

      • getConnectControls

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

      • setRequestControls

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

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

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

        参数
        requestControls - 要使用的可能为null的控件。 如果为null，则不使用任何控件。
        异常
        NamingException - 如果在设置请求控件时发生错误。
        另请参见：
        getRequestControls()

      • getRequestControls

        Control[] getRequestControls()
                      throws NamingException
        检索对此上下文有效的请求控件。 请求控件由JNDI实现拥有，并且是不可变的。 调用者不能修改数组和控件。
        结果
        一个可能为空的控件数组。 null表示没有为此上下文设置请求控件。
        异常
        NamingException - 如果在获取请求控件时发生错误。
        另请参见：
        setRequestControls(javax.naming.ldap.Control[])

      • getResponseControls

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

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

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

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