Module  java.naming
软件包  javax.naming.ldap

Class InitialLdapContext

  • All Implemented Interfaces:
    Context ， DirContext ， LdapContext 

    public class InitialLdapContext
extends InitialDirContext
implements LdapContext
    此类是执行LDAPv3风格的扩展操作和控件的起始上下文。

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

    请求控制

    创建初始上下文（ InitialLdapContext ）时，可以指定请求控件列表。 这些控件将被用作由上下文导出的上下文或上下文执行的任何隐式LDAP“绑定”操作的请求控件。 这些称为连接请求控件 。 使用getConnectControls()获取上下文的连接请求控件。

    提供给初始上下文构造函数的请求控件不会用作后续上下文操作（如搜索和查找）的上下文请求控件。 上下文请求控制通过使用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
    另请参见：
    LdapContext ， InitialContext ， InitialDirContext ， NamingManager.setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder)

    • 构造方法详细信息

      • 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的环境。 空指示空的环境。
        connCtls - 初始上下文的连接请求控制。 如果为空，则不使用连接请求控件。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        reconnect(javax.naming.ldap.Control[]) ， LdapContext.reconnect(javax.naming.ldap.Control[])

    • 方法详细信息

      • newInstance

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

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

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

      • reconnect

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

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

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

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

        Specified by:
        reconnect在接口 LdapContext
        参数
        connCtls - 可能使用的空控件。 如果为空，则不使用控件。
        异常
        NamingException - 如果重新连接时发生错误。
        另请参见：
        LdapContext.getConnectControls() ， LdapContext.newInstance(javax.naming.ldap.Control[])

      • getConnectControls

        public Control[] getConnectControls​()
                             throws NamingException
        说明从接口LdapContext复制
        检索此上下文的连接请求控件。 控制由JNDI实现所有，并且是不可变的。 调用者都不能修改数组和控件。
        Specified by:
        getConnectControls接口 LdapContext
        结果
        一个可能为空的控件数组。 null表示没有为此上下文设置连接控件。
        异常
        NamingException - 如果在获取请求控件时发生错误。

      • setRequestControls

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

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

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

        Specified by:
        setRequestControls在接口 LdapContext
        参数
        requestControls - 可能使用的空控件。 如果为空，则不使用控件。
        异常
        NamingException - 如果在设置请求控件时发生错误。
        另请参见：
        LdapContext.getRequestControls()

      • getResponseControls

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

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

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

        Specified by:
        getResponseControls在接口 LdapContext
        结果
        一个可能为null的控件数组。 如果为null，则在此上下文中调用的上一个方法没有产生任何控件。
        异常
        NamingException - If an error occurred while getting the response controls.