Module  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 。 指定null或空数组reqCtls意味着没有请求控件。 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 。 指定null或空数组connCtls表示无连接请求控件。

    与环境属性一样，上下文的连接请求控制由从其导出的上下文继承 。 通常，您使用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表示操作没有产生任何响应。
        异常
        NamingException - 执行扩展操作时是否发生错误。

      • newInstance

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

        新上下文具有与上下文相同的环境属性和连接请求控件。 详见课程说明。 如果这样做，实现也可能允许这个上下文和新的上下文共享相同的网络连接或其他资源，而不会妨碍任一上下文的独立性。

        参数
        requestControls - 用于新上下文的可能为null的请求控件。 如果为空，则无需请求控制即可初始化上下文。
        结果
        非空 LdapContext实例。
        异常
        NamingException - 创建新实例时是否发生错误。
        另请参见：
        InitialLdapContext

      • reconnect

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

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

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

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

        参数
        connCtls - 可能使用的空控件。 如果为空，则不使用控件。
        异常
        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 - 可能使用的空控件。 如果为空，则不使用控件。
        异常
        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 - 如果在获取响应控件时发生错误。