javax.naming.ldap
介面 LdapContext

所有父級介面：

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 的實例。為 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 共享連接的上下文保持不變。即上下文的連接請求控制元件必須顯式更改，更改另一個上下文的連接請求控制元件對它沒有影響。

上下文實例的連接請求控制元件需要使用方法 getConnectControls() 進行檢索。

服務提供者需求

服務提供者用以下方式支持連接和上下文請求控制元件。上下文請求控制元件必須在每個上下文實例的基礎上相關聯，而連接請求控制元件必須在每個連接實例的基礎上相關聯。服務提供者必須在環境屬性 "java.naming.ldap.control.connect" 中尋找連接請求控制元件，並將此環境屬性傳遞到它創建的上下文實例中。

回應控制元件

方法 LdapContext.getResponseControls() 用於檢索由於調用 Context/DirContext 操作而執行的 LDAP 操作產生的回應控制元件。結果為基礎 LDAP 操作產生的所有回應控制元件，包括所有隱式重接。要僅獲取重接回應控制元件，請使用 reconnect()，然後使用 getResponseControls()。

參數

作為參數傳遞給任何方法的 Control[] 陣列都為調用者所有。服務提供者將不修改陣列，也不保持對它的參考，但它可能保持對陣列中個別 Control 物件的參考。任何方法返回的 Control[] 陣列都是不可變的，並且不能被調用者或服務提供者進行後續修改。

從以下版本開始：

1.3

另請參見：

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

欄位摘要

static String

CONTROL_FACTORIES 該常數保存用來指定要使用的控制元件處理器列表的環境屬性名稱。

從介面 javax.naming.directory.DirContext 繼承的欄位

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

從介面 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

方法摘要

ExtendedResponse	extendedOperation(ExtendedRequest request) 執行擴展操作。
Control[]	getConnectControls() 檢索對此上下文有效的連接請求控制元件。
Control[]	getRequestControls() 檢索對此上下文有效的請求控制元件。
Control[]	getResponseControls() 檢索對此上下文調用的最後一個方法所產生的回應控制元件。
LdapContext	newInstance(Control[] requestControls) 創建此上下文的新實例，使用請求控制元件進行初始化。
void	reconnect(Control[] connCtls) 使用提供的控制元件和此上下文的環境重新連接到 LDAP 伺服器。
void	setRequestControls(Control[] requestControls) 為在此上下文上後續調用的方法設置請求控制元件。

從介面 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

從介面 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()。此屬性可以在環境、applet 參數、系統屬性或者一個或多個資源檔案中指定。

此常數的值是 "java.naming.factory.control"。

另請參見：

ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), 常數欄位值

方法詳細資訊

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）。如果為 null，則不使用任何控制元件。

拋出：

NamingException - 如果重接時出錯。

另請參見：

getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

Control[] getConnectControls()
                             throws NamingException

檢索對此上下文有效的連接請求控制元件。JNDI 實作所擁有的控制元件是不可變的。調用者既不能修改陣列也不能修改控制元件。

返回：

控制元件陣列（可能為 null）。null 表示沒有為此上下文設置任何連接控制元件。

拋出：

NamingException - 如果在獲取請求控制元件時出錯。

setRequestControls

void setRequestControls(Control[] requestControls)
                        throws NamingException

為在此上下文上後續調用的方法設置請求控制元件。JNDI 實作所擁有的請求控制元件是不可變的。調用者既不能修改陣列也不能修改控制元件。

此操作移除所有以前的請求控制元件，並添加 requestControls 供在此上下文上調用的後續方法使用。此方法不影響此上下文的連接請求控制元件。

注意，在下一次調用 setRequestControls() 之前 requestControls 一直有效。如果不想讓這些控制元件繼續影響上下文方法，則需要使用 null 或空陣列作為參數顯式調用 setRequestControls() 來清除它們。要檢查對此上下文有效的請求控制元件，請使用 getRequestControls()。

參數：

requestControls - 要使用的控制元件（可能為 null）。如果為 null，則不使用任何控制元件。

拋出：

NamingException - 如果在設置請求控制元件時出錯。

另請參見：

getRequestControls()

getRequestControls

Control[] getRequestControls()
                             throws NamingException

檢索對此上下文有效的請求控制元件。JNDI 實作所擁有的請求控制元件是不可變的。調用者既不能修改陣列也不能修改控制元件。

返回：

控制元件陣列（可能為 null）。null 表示沒有為此上下文設置任何請求控制元件。

拋出：

NamingException - 如果在獲取請求控制元件時出錯。

另請參見：

setRequestControls(javax.naming.ldap.Control[])

getResponseControls

Control[] getResponseControls()
                              throws NamingException

檢索對此上下文調用的最後一個方法所產生的回應控制元件。JNDI 實作所擁有的回應控制元件是不可變的。調用者既不能修改陣列也不能修改控制元件。

這些回應控制元件可能由成功或失敗的操作產生。

調用可能返迴響應控制元件的上下文方法時，上一個方法調用產生的回應控制元件將被清除。getResponseControls()（按照從 LDAP 伺服器收到回應控制元件的順序） 返回上下文方法使用的 LDAP 操作產生的所有回應控制元件。調用 getResponseControls() 不清除回應控制元件。在調用可能返回控制元件的下一個上下文方法之前，可以多次調用它（並返回相同的控制元件）。

返回：

控制元件陣列（可能為 null）。如果為 null，則對此上下文調用的上一個方法不會產生任何控制元件。

拋出：

NamingException - 如果在獲取回應控制元件時出錯。