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环境产权”连接请求的控制。命名。LDAP。控制。连接”，通过这个环境特性对上下文实例创建。
响应控制
方法 LdapContext.getResponseControls()用来检索响应控件通过LDAP操作执行调用 Context / DirContext操作结果产生。结果是所有的反应控制下的LDAP操作产生的，包括任何隐式连接。只有重新连接响应控件，使用 reconnect()随后 getResponseControls()。
参数
一 Control[]数组作为参数的任何方法的调用方拥有过。服务提供商不会修改数组或保持一个参考吧，尽管它可能保持引用数组中的单个 Control对象。一个 Control[]数组返回的任何方法是不可变的，不可能被通过来电者或服务提供者修改。
从以下版本开始：

一点三

另请参见：

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

- Field Detail
  - CONTROL_FACTORIES
```
static final String CONTROL_FACTORIES
```
    保持用于指定控件工厂列表的环境属性的名称的常量。属性的值应该是工厂类的完全限定的类名称的“结”列表，将创建另一个控件的控件。看到 ControlFactory.getControlInstance()详情。此属性可以在环境中指定，一个小程序参数，一个系统属性，或一个或多个资源文件。
    该常数的值是“java。命名。工厂。”。
    
    另请参见：
    
    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 -非空的请求被执行。
    
    结果
    
    操作的可能无效响应。“零”意味着操作没有产生任何响应。
    
    异常
    
    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实现国有的和永恒不变的。无论是数组，也不是控件可以由调用方进行修改。
    
    结果
    
    一个可能的控件的空数组。空意味着没有连接控件已被设置为这种情况下。
    
    异常
    
    如果出现了一个错误，而 NamingException获取请求控制。
  - setRequestControls
```
void setRequestControls(Control[] requestControls)
                 throws NamingException
```
    设置随后在此上下文中调用的方法的请求控件。请求的控制是通过JNDI实现国有的和永恒不变的。无论是数组，也不是控件可以由调用方进行修改。
    这将删除任何以前的要求控制和增加requestControls用于后续调用的方法在这方面。此方法不影响此上下文的连接请求控制。
    
    注意，requestControls将生效，直到下一个调用setRequestControls()。你需要显式调用setRequestControls()与null或清除控制空数组如果你不想让他们影响到上下文的方法更多。检查此语境效果要求什么是控制，使用getRequestControls()。
    
    参数
    
    requestControls -使用可能的空控制。如果为空，则没有使用控件。
    
    异常
    
    NamingException -如果出错而设置的要求控制。
    
    另请参见：
    
    getRequestControls()
  - getRequestControls
```
Control[] getRequestControls()
                      throws NamingException
```
    检索此上下文的效果的请求控件。请求的控制是通过JNDI实现国有的和永恒不变的。无论是数组，也不是控件可以由调用方进行修改。
    
    结果
    
    一个可能的控件的空数组。空意味着没有请求控制已被设置为这种情况下。
    
    异常
    
    如果出现了一个错误，而 NamingException获取请求控制。
    
    另请参见：
    
    setRequestControls(javax.naming.ldap.Control[])
  - getResponseControls
```
Control[] getResponseControls()
                       throws NamingException
```
    检索在此上下文中调用的最后一个方法的结果所产生的响应控件。反应控制是通过JNDI实现国有的和永恒不变的。无论是数组，也不是控件可以由调用方进行修改。
    这些响应控件可能是由一个成功的或失败的操作产生的。
    
    当调用可能返回响应控件的上下文方法时，清除以前的方法调用的响应控件。getResponseControls()返回所有响应控件从LDAP服务器接收LDAP操作的顺序的方法产生的背景。调用getResponseControls()不明确响应控制。您可以调用它多次（并返回相同的控件），直到调用可能返回控件的下一个上下文方法为止。
    
    结果
    
    一个可能的控件的空数组。如果为空，在此上下文中调用的以前的方法没有产生任何控件。
    
    异常
    
    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

Field Detail

CONTROL_FACTORIES

方法详细信息

extendedOperation

newInstance

reconnect

getConnectControls

setRequestControls

getRequestControls

getResponseControls