javax.naming.spi
類別 NamingManager

java.lang.Object
  javax.naming.spi.NamingManager

直接已知子類別：

DirectoryManager

public class NamingManager
extends Object

此類別包含一些方法來創建上下文物件以及通過命名或目錄服務中的資訊參考的物件。

此類別無法被實例化。它只有靜態方法。

用於此類別文檔中的 URL 是指通過 RFC 1738 及其相關的 RFC 定義的 URL 字元串。它是符合其中所述語法的任何字元串，在 java.net.URL 類別或 Web 瀏覽器中未必總能獲得相應的支持。

將 NamingManager 用於多個執行緒的共時存取是安全的。

除非另有說明，否則傳遞給任何方法的 Name 或環境參數都歸調用者所有。該實作不會修改物件或保持對該物件的參考，儘管可能保持對其副本的參考。

從以下版本開始：

1.3

欄位摘要

static String

CPE 保存環境屬性名稱的常數，getContinuationContext() 將其 CannotProceedException 參數的值保存在該環境屬性中。

方法摘要

static Context	getContinuationContext(CannotProceedException cpe) 創建一個將繼續上下文操作的上下文。
static Context	getInitialContext(Hashtable<?,?> env) 使用指定環境屬性創建一個初始上下文處理器。
static Object	getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment) 為指定物件和環境創建一個物件實例。
static Object	getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) 檢索用於綁定的物件的狀態。
static Context	getURLContext(String scheme, Hashtable<?,?> environment) 為給定的 URL 方案 id 創建一個上下文。
static boolean	hasInitialContextFactoryBuilder() 確定是否已經設置了初始上下文處理器產生器。
static void	setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder) 將 InitialContextFactory 產生器設置為產生器。
static void	setObjectFactoryBuilder(ObjectFactoryBuilder builder) ObjectFactoryBuilder 確定嘗試載入物件處理器時使用的策略。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

欄位詳細資訊

CPE

public static final String CPE

保存環境屬性名稱的常數，getContinuationContext() 將其 CannotProceedException 參數的值保存在該環境屬性中。此屬性由連續上下文繼承，並且該上下文的服務提供者可以使用它來檢查異常的欄位。

此常數的值是 "java.naming.spi.CannotProceedException"。

從以下版本開始：

1.3

另請參見：

getContinuationContext(javax.naming.CannotProceedException), 常數欄位值

方法詳細資訊

setObjectFactoryBuilder

public static void setObjectFactoryBuilder(ObjectFactoryBuilder builder)
                                    throws NamingException

ObjectFactoryBuilder 確定嘗試載入物件處理器時使用的策略。有關預設策略的描述，請參見 getObjectInstance() 和類別 ObjectFactory。setObjectFactoryBuilder() 通過安裝 ObjectFactoryBuilder 覆寫此預設策略。後續物件處理器將使用安裝的產生器載入和創建。

產生器只有在允許執行執行緒這樣做（通過安全管理器的 checkSetFactory() 方法）時才能被安裝。一旦安裝了產生器，就不能再替換它。

參數：

builder - 要安裝的處理器產生器。如果為 null，則不安裝任何產生器。

拋出：

SecurityException - 由於安全原因而無法安裝產生器。

NamingException - 由於與安全無關的原因而無法安裝產生器。

IllegalStateException - 如果已經安裝了一個處理器。

另請參見：

getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory, ObjectFactoryBuilder, SecurityManager.checkSetFactory()

getObjectInstance

public static Object getObjectInstance(Object refInfo,
                                       Name name,
                                       Context nameCtx,
                                       Hashtable<?,?> environment)
                                throws Exception

為指定物件和環境創建一個物件實例。

如果已經安裝了一個物件處理器產生器，則使用它來創建用於創建物件的處理器。否則使用以下規則來創建該物件：

1. 如果 refInfo 是一個套件含處理器類別名稱的 Reference 或 Referenceable，則使用指定的處理器來創建該物件。如果無法創建處理器，則返回 refInfo。從 JDK 1.1 開始，如果必須從參考中指定的位置載入處理器類別，則必須已經安裝 SecurityManager，否則處理器創建將失敗。如果在創建處理器時遇到異常，則將該異常傳遞到調用者。
2. 如果 refInfo 是一個不帶處理器類別名稱的 Reference 或 Referenceable，並且該位址或這些位址是位址型別為 "URL" 的 StringRefAddr，則嘗試使用對應於每個 URL 方案 id 的 URL 上下文處理器來創建該物件（參見 getURLContext()）。如果失敗，則繼續下一個步驟。
3. 使用環境的 Context.OBJECT_FACTORIES 屬性和與 nameCtx 關聯的提供者資源檔案的 Context.OBJECT_FACTORIES 屬性中指定的物件處理器，並使用原來的順序。此屬性的值是按順序嘗試的以冒號分隔的處理器類別名稱列表，使用的名稱是第一個成功創建物件的名稱。如果沒有載入任何處理器，則返回 refInfo。如果在創建物件時遇到異常，則將該異常傳遞到調用者。

實作 DirContext 介面的服務提供者應該使用 DirectoryManager.getObjectInstance() 而不是此方法。只實作 Context 介面的服務提供者應該使用此方法。

注意，物件處理器（實作 ObjectFactory 介面的物件）必須是公共的，並且必須有一個不接受任何參數的公共建構子。

可以有選擇地使用 name 和 nameCtx 參數來指定將創建的物件的名稱。name 是該物件相對於上下文 nameCtx 的名稱。此資訊對於物件處理器或物件實作可能很有用。如果有幾個可以從中指定物件的可能上下文（通常會是這種情況），則由調用者決定選擇哪一個。根據經驗，應選擇“最深的”可用上下文。如果 nameCtx 為 null，則 name 相對於預設初始上下文。如果沒有名稱將被指定，則 name 參數應該為 null。

參數：

refInfo - 將為之創建物件的物件（可能為 null）。

name - 此物件的相對於 nameCtx 的名稱。指定名稱是可選操作；如果忽略名稱，則 name 應該為 null。

nameCtx - 一個上下文，name 參數是相對於該上下文指定的。如果為 null，則 name 相對於預設初始上下文。

environment - 將在創建物件和物件處理器時使用的環境（可能為 null）。

返回：

使用 refInfo 創建的物件；如果無法使用上述演算法創建物件，則返回 refInfo。

拋出：

NamingException - 如果在試圖獲得 URL 上下文時遇到命名異常，或者受存取的處理器之一拋出 NamingException。

Exception - 如果受存取的處理器之一拋出異常，或者載入和實例化處理器和物件類別時遇到錯誤。處理器只有在不希望試圖使用其他處理器創建物件時才拋出異常。請參見 ObjectFactory.getObjectInstance()。

另請參見：

getURLContext(java.lang.String, java.util.Hashtable), ObjectFactory, ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

getURLContext

public static Context getURLContext(String scheme,
                                    Hashtable<?,?> environment)
                             throws NamingException

為給定的 URL 方案 id 創建一個上下文。

得到的上下文用於解析 scheme 方案的 URL。得到的上下文沒有綁定到特定 URL。它能夠使用指定方案處理任意 URL。

創建所得上下文的處理器的類別名稱包含命名約定方案 id URLContextFactory（例如，用於 "ftp" 方案 id 的 "ftpURLContextFactory"），所在的套件指定如下。Context.URL_PKG_PREFIXES 環境屬性（可能包含從 applet 參數、系統屬性或應用程序資源檔案中獲得的值）包含以冒號分隔的套件前綴列表。按指定的順序嘗試該屬性中的每個包前綴來載入處理器類別。預設包前綴是 "com.sun.jndi.url"（如果指定的套件前綴都無效，則嘗試使用此預設前綴）。完整的套件名稱是使用包前綴建構的，並與方案 id 連接在一起。

例如，如果方案 id 為 "ldap"，而 Context.URL_PKG_PREFIXES 屬性包含 "com.widget:com.wiz.jndi"，則命名管理器將嘗試載入以下類別，直到成功實例化其中的一個：

• com.widget.ldap.ldapURLContextFactory
• com.wiz.jndi.ldap.ldapURLContextFactory
• com.sun.jndi.url.ldap.ldapURLContextFactory

如果沒有包前綴有效，則返回 null。

如果某一處理器被實例化，則使用以下參數調用該處理器來產生結果上下文。

factory.getObjectInstance(null, environment);

例如，按上述方式對 LDAP URL 上下文處理器調用 getObjectInstance() 將返回一個可以解析 LDAP url（例如 "ldap://ldap.wiz.com/o=wiz,c=us"、"ldap://ldap.umich.edu/o=umich,c=us" 等等）的上下文。

注意，物件處理器（實作 ObjectFactory 介面的物件）必須是公共的，並且必須有一個不接受任何參數的公共建構子。

參數：

scheme - 上下文支持的 URL 的非 null 方案 id。

environment - 將在創建物件和物件處理器時使用的環境屬性（可能為 null）。

返回：

使用方案 id scheme 解析 URL 的上下文；如果沒有找到用於創建該上下文的處理器，則返回 null。

拋出：

NamingException - 如果在創建上下文時發生命名異常。

另請參見：

getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

getInitialContext

public static Context getInitialContext(Hashtable<?,?> env)
                                 throws NamingException

使用指定環境屬性創建一個初始上下文處理器。

如果已經安裝 InitialContextFactoryBuilder，則使用它來創建用於創建該初始上下文的處理器。否則使用 Context.INITIAL_CONTEXT_FACTORY 環境屬性中指定的類別。注意，初始上下文處理器（實作 InitialContextFactory 介面的物件）必須是公共的，並且必須有一個不接受任何參數的公共建構子。

參數：

env - 創建上下文時要使用的環境屬性（可能為 null）。

返回：

非 null 的初始上下文。

拋出：

NoInitialContextException - 如果沒有找到 Context.INITIAL_CONTEXT_FACTORY 屬性，或者指定了一個不存在的類別或無法實例化的類別，抑或因為其他一些原因而無法創建初始上下文。

NamingException - 如果遇到其他命名異常。

另請參見：

InitialContext, InitialDirContext

setInitialContextFactoryBuilder

public static void setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder)
                                            throws NamingException

將 InitialContextFactory 產生器設置為產生器。

產生器只有在安全管理器允許執行執行緒這樣做時才能被安裝。一旦安裝了產生器，就不能再替換它。

參數：

builder - 要安裝的初始上下文處理器產生器。如果為 null，則不設置任何產生器。

拋出：

SecurityException - 由於安全原因而無法安裝產生器。

NamingException - 由於與安全無關的原因而無法安裝產生器。

IllegalStateException - 如果以前已經安裝了產生器。

另請參見：

hasInitialContextFactoryBuilder(), SecurityManager.checkSetFactory()

hasInitialContextFactoryBuilder

public static boolean hasInitialContextFactoryBuilder()

確定是否已經設置了初始上下文處理器產生器。

返回：

如果已經設置了初始上下文處理器產生器，則返回 true；否則返回 false。

另請參見：

setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder)

getContinuationContext

public static Context getContinuationContext(CannotProceedException cpe)
                                      throws NamingException

創建一個將繼續上下文操作的上下文。

當對跨多個名稱空間的名稱執行某一操作時，取自某個命名系統的上下文可能需要將該操作傳遞給下一個命名系統。為做到這一點，上下文實作首先建構一個套件含指出該操作已進行程度的資訊的 CannotProceedException。然後通過調用 getContinuationContext 從 JNDI 中獲取連續上下文。然後，該上下文實作應該通過對連續上下文調用相同的操作，使用尚未解析的剩餘名稱重新開始該上下文操作。

在使用 cpe 參數前，此方法通過將 CPE 屬性的值設置為 cpe 來更新與該物件關聯的環境。此屬性將由連續上下文繼承，並且該上下文的服務提供者可以使用它來檢查此異常的欄位。

參數：

cpe - 觸發此連續的非 null 異常。

返回：

用於繼續該操作的非 null Context 物件。

拋出：

NamingException - 如果發生命名異常。

getStateToBind

public static Object getStateToBind(Object obj,
                                    Name name,
                                    Context nameCtx,
                                    Hashtable<?,?> environment)
                             throws NamingException

檢索用於綁定的物件的狀態。

實作 DirContext 介面的服務提供者應該使用 DirectoryManager.getStateToBind() 而不是此方法。只實作 Context 介面的服務提供者應該使用此方法。

此方法使用取自環境屬性的 Context.STATE_FACTORIES 屬性和與 nameCtx 有關的提供者資源檔案的 Context.STATE_FACTORIES 屬性中的指定狀態處理器，並使用原來的順序。此屬性的值是按順序嘗試的以冒號分隔的處理器類別名稱列表，使用的名稱是第一個成功返回物件狀態的名稱。如果以這種方式沒有檢索到物件狀態，則返回該物件本身。如果在檢索狀態時遇到異常，則將該異常傳遞到調用者。

注意，狀態處理器（實作 StateFactory 介面的物件）必須是公共的，並且必須有一個不接受任何參數的公共建構子。

可以有選擇地使用 name 和 nameCtx 參數來指定要創建的物件的名稱。有關詳細資訊，請參閱 ObjectFactory.getObjectInstance() 中“名稱和上下文參數”的描述。

此方法可以返回一個 Referenceable 物件。獲得此物件的服務提供者可以選擇直接存儲該物件，或者提取（使用 Referenceable.getReference()）並存儲其參考。

參數：

obj - 將為其獲得要綁定的狀態的非 null 物件。

name - 此物件相對於 nameCtx 的名稱，如果沒有指定名稱，則該參數為 null。

nameCtx - 一個上下文，name 參數是相對於該上下文指定的，如果 name 相對於預設初始上下文，則該參數為 null。

environment - 將在創建狀態處理器和物件狀態時使用的環境（可能為 null）。

返回：

表示用於綁定的 obj 狀態的非 null 物件。它可以是該物件 (obj) 本身。

拋出：

NamingException - 如果受存取的處理器之一拋出異常，或者載入和實例化處理器和物件類別時遇到錯誤。處理器只有在不希望試圖使用其他處理器創建物件時才拋出異常。請參見 StateFactory.getStateToBind()。

從以下版本開始：

1.3

另請參見：

StateFactory, StateFactory.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes)