LdapContext (Java Platform SE 8 )

All Superinterfaces:

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一个实例。指定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共享连接的上下文保持不变。也就是说，上下文的连接请求控件必须显式更改，并且不受另一个上下文的连接请求控件的更改的影响。

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

服务提供商要求
服务提供商通过以下方式支持连接和上下文请求控制。上下文请求控件必须在每个上下文实例基础上关联，而连接请求控件必须在每个连接实例的基础上关联。服务提供商必须在环境属性“java.naming.ldap.control.connect”中查找连接请求控件，并将此环境属性传递给它创建的上下文实例。
响应控制
该方法LdapContext.getResponseControls()用于检索由作为调用DirContext分之Context操作的结果执行的LDAP操作生成的响应控制。结果是由底层LDAP操作生成的所有响应控件，包括任何隐式重新连接。要获取重新连接响应控件，请使用reconnect()，后跟getResponseControls() 。
参数
作为参数传递给任何方法的数组Control[]由调用者拥有。服务提供商不会修改数组或保留对它的引用，尽管它可能会保留对数组中单个的Control对象的引用。由任何方法返回的Control[]数组是不可变的，并且随后可能不被调用者或服务提供者修改。
从以下版本开始：

1.3

另请参见：

InitialLdapContext ， LdapReferralException.getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CONTROL_FACTORIES` 用于指定要使用的控制工厂列表的环境属性的名称的常量。

Fields inherited from interface javax.naming.directory.DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`ExtendedResponse`	`extendedOperation(ExtendedRequest request)` 执行扩展操作。
`Control[]`	`getConnectControls()` 检索此上下文的连接请求控件。
`Control[]`	`getRequestControls()` 检索对该上下文有效的请求控件。
`Control[]`	`getResponseControls()` 检索由此上下文调用的最后一个方法生成的响应控件。
`LdapContext`	`newInstance(Control[] requestControls)` 创建使用请求控件初始化的此上下文的新实例。
`void`	`reconnect(Control[] connCtls)` 使用提供的控件和此上下文的环境重新连接到LDAP服务器。
`void`	`setRequestControls(Control[] requestControls)` 设置随后在此上下文中调用的方法的请求控件。

Methods inherited from interface javax.naming.directory.DirContext
bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search

Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

- 字段详细信息
  - CONTROL_FACTORIES
```
static final String CONTROL_FACTORIES
```
    用于指定要使用的控制工厂列表的环境属性的名称的常量。属性的值应该是冒号分隔的工厂类的完全限定类名的列表，它将创建一个给定另一个控件的控件。详见ControlFactory.getControlInstance() 。该属性可以在环境，小应用程序参数，系统属性或一个或多个资源文件中指定。
    该常量的值为“java.naming.factory.control”。
    
    另请参见：
    
    ControlFactory ， Context.addToEnvironment(java.lang.String, java.lang.Object) ， Context.removeFromEnvironment(java.lang.String) ， Constant Field Values
- 方法详细信息
  - extendedOperation
```
ExtendedResponse extendedOperation(ExtendedRequest request)
                            throws NamingException
```
    执行扩展操作。此方法用于支持LDAPv3扩展操作。
    
    参数
    
    request - 要执行的非空请求。
    
    结果
    
    操作可能为空的响应。 null表示操作没有产生任何响应。
    
    异常
    
    NamingException - 执行扩展操作时是否发生错误。
  - newInstance
```
LdapContext newInstance(Control[] requestControls)
                 throws NamingException
```
    创建使用请求控件初始化的此上下文的新实例。此方法是为了多线程访问的目的创建此上下文的新实例的便利方法。例如，如果多个线程想要使用不同的上下文请求控件，则每个线程都可以使用此方法来获取其上下文的自己的副本，并设置/获取上下文请求控件，而不必与其他线程同步。
    新上下文具有与上下文相同的环境属性和连接请求控件。有关详细信息，请参阅课程说明。如果这样做，实现也可能允许这个上下文和新的上下文共享相同的网络连接或其他资源，而不会妨碍任一上下文的独立性。
    
    参数
    
    requestControls - 用于新上下文的可能的空请求控件。如果为空，则无需请求控制即可初始化上下文。
    
    结果
    
    非空值 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空数组来清除控件，如果你不希望他们更多地影响上下文方法。要检查哪些请求控件对此上下文有效，请使用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 - 如果在获取响应控件时发生错误。

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Interface LdapContext

使用细节关于控制

请求控制

上下文请求控制

连接请求控制

服务提供商要求

响应控制

参数

Field Summary

Fields inherited from interface javax.naming.directory.DirContext

Fields inherited from interface javax.naming.Context

方法摘要

Methods inherited from interface javax.naming.directory.DirContext

Methods inherited from interface javax.naming.Context

字段详细信息

CONTROL_FACTORIES

方法详细信息

extendedOperation

newInstance

reconnect

getConnectControls

setRequestControls

getRequestControls

getResponseControls