javax.naming.spi

接口
类

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)