javax.naming

接口
类
异常

javax.naming
接口 Context

所有已知子接口：
DirContext, EventContext, EventDirContext, LdapContext
所有已知实现类：
InitialContext, InitialDirContext, InitialLdapContext 
public interface Context

此接口表示一个命名上下文，它由一组名称到对象的绑定组成。它包含检查和更新这些绑定的一些方法。

名称

每个作为参数传递给 Context 方法的名称都是相对于该上下文的。空名称用于命名上下文本身。名称参数绝对不能为 null。

大多数方法具有重载形式，一种带有 Name 参数，另一种带有 String 参数。这些重载的方法是等效的：如果 Name 和 String 参数只是相同名称的不同表示形式，则相同方法的重载形式的行为也相同。在以下方法描述中，仅完整记录一种形式。第二种形式将链接到第一种：对两者应用相同的文档。

对于支持联合的系统，Context 方法的 String 名称参数是复合名称。是 CompositeName 实例的那些名称参数被视为复合名称，而不是 CompositeName 实例的 Name 参数被视为组合名称（可能是 CompoundName 实例或组合名称的其他实现）。这允许将 NameParser.parse() 的结果用作 Context 方法的参数。在 JNDI 1.2 之前，所有名称参数都被视为复合名称。

此外，对于支持联合的系统，NamingEnumeration 中所有从 list() 和 listBindings() 返回的名称都是表示为字符串的复合名称。有关名称的字符串语法，请参见 CompositeName。

对于不支持联合的系统，名称参数（Name 或 String 形式）和 NamingEnumeration 中返回的名称可能是其自己的名称空间中的名称，而不是复合名称空间中的名称，这由服务提供者决定。

异常

此接口中的所有方法都可以抛出 NamingException 或其任意子类。有关每个异常的详细信息，请参见 NamingException 及其子类。

并发访问

不保证 Context 实例与多个线程的并发访问是同步的。需要并发地访问单个 Context 实例的线程应该在它们之间实现同步并提供必需的锁定。对于每个线程都操作一个不同 Context 实例的多个线程而言，无需实现同步。注意，向 lookup 方法传递空名称将返回一个表示相同命名上下文的新 Context 实例。

为了实现并发控制，返回 NamingEnumeration 的 Context 操作在枚举仍在使用中或者仍在遵从该操作生成的所有引用时被认为尚未完成。

参数

传递给 Context 接口或其子接口之一中任何方法的 Name 参数不会被服务提供者修改。服务提供者可以在执行操作期间保留一个对它的引用，其中包括方法结果的所有枚举和生成的所有引用的处理。调用者在这段时间内不能修改该对象。任何这类方法返回的 Name 都归调用者所有。调用者随后可修改它，而服务提供者则不能。

环境属性

JNDI 应用程序需要一种方式来传达定义访问命名服务和目录服务的环境的各种首选项和属性。例如，为了访问服务，某个上下文可能需要安全证书的规约。另一个上下文可能要求提供服务器的配置信息。这些被称为某一上下文的环境。Context 接口提供一些检索和更新此环境的方法。

该环境在上下文方法从一个上下文到下一个上下文时从父上下文中继承。对某一上下文环境的更改不会直接影响其他上下文的环境。

当将环境属性用于有效性和/或验证有效性时，这些属性与实现有关。例如，一些与安全有关的属性被服务提供者用于“登录”目录。此登录过程可能发生在创建上下文时，或者发生在第一次对该上下文调用方法时。无论这在何时或是否发生，此环境属性都与实现有关。在将环境属性添加到上下文中或从上下文中移除时，验证这些更改的有效性也都与实现有关。例如，验证某些属性可能发生在进行更改时，或者发生在对上下文执行下一个操作时，抑或根本不验证。

拥有对某一上下文的引用的任何对象都可以检查该上下文的环境。敏感信息（比如明文密码）不应该存储在该环境中，除非已知实现能保护这类信息。

资源文件

要简化设置 JNDI 应用程序所需环境的任务，可以将资源文件 与应用程序组件和服务提供者一起发布。JNDI 资源文件是使用属性文件格式的文件（参见 java.util.Properties），包括一个键/值对列表。键是属性的名称（例如 "java.naming.factory.object"），而值是使用为该属性定义的格式的字符串。以下是 JNDI 资源文件的一个示例： 

 java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
JNDI 类库读取资源文件，并使属性值随意可用。因此应该认为 JNDI 资源文件是“所有人可读的”，敏感信息（比如明文密码）不应该存储在那里。

有两种 JNDI 资源文件：提供者 和应用程序。

提供者资源文件
每个服务提供者都有一个可选的资源，该资源列出了特定于该提供者的属性。此资源的名称是：
[ prefix/] jndiprovider.properties
其中 prefix 是提供者的上下文实现的包名称，其每个句点 (".") 都被转换成一个斜杠 ("/")。 例如，假设服务提供者定义了一个带有类名称 com.sun.jndi.ldap.LdapCtx 的上下文实现。此提供者的提供者资源被命名为 com/sun/jndi/ldap/jndiprovider.properties。如果该类不在一个包中，则资源的名称就是 jndiprovider.properties。

JNDI 类库中的某些方法使用指定 JNDI 工厂列表的标准 JNDI 属性：

  • java.naming.factory.object
  • java.naming.factory.state
  • java.naming.factory.control
  • java.naming.factory.url.pkgs
在确定这些属性的值时，JNDI 库将参考提供者资源文件。这以外的属性可由服务提供者在提供者资源文件中设置。服务提供者的文档应该明确声明哪些属性是被允许的；文件中的其他属性将被忽略。
应用程序资源文件
在部署应用程序时，该应用程序通常将在其类路径中生成若干代码基目录和 JAR。类似地，在部署 applet 时，它将有一个指定 applet 类所处地址的代码基和档案文件。JNDI 查找（使用 ClassLoader.getResources()）类路径中所有名为 jndi.properties 的 应用程序资源文件。此外，如果文件 java.home /lib/jndi.properties 存在并且是可读的，则 JNDI 会将其视为一个额外的应用程序资源文件。（ java.home 指示由 java.home 系统属性命名的目录。）包含在这些文件中的所有属性都被放置在初始上下文环境中。然后此环境由其他上下文继承。

对于同时出现在多个应用程序资源文件中的每个属性，JNDI 使用最先找到的值，或者在少数有意义的情况下串联所有这些值（细节在下文给出）。例如，如果在三个 jndi.properties 资源文件中存在 "java.naming.factory.object" 属性，则对象工厂列表是所有三个文件中的属性值的串联。使用此方案，每个可部署组件都要负责列出它导出的工厂。JNDI 在搜索工厂类时自动收集和使用所有这些导出列表。

从 Java 2 Platform 开始可使用应用程序资源文件，java.home/lib 中的文件除外，它在较早的 Java 平台上也可以使用。

属性的搜索算法
当 JNDI 构造一个初始上下文时，该上下文的环境是使用传递给构造方法的环境参数中定义的属性、系统属性、applet 参数和应用程序资源文件进行初始化的。有关细节请参见 InitialContext。然后此初始环境由其他上下文实例继承。

如果 JNDI 类库需要确定某一属性的值，它将通过按顺序合并取自以下两个源的值来实现这一点：

  1. 将在其上执行操作的上下文的环境。
  2. 将在其上执行操作的上下文的提供者资源文件 (jndiprovider.properties)。
对于每个同时存在于这两个源中的属性，JNDI 用以下方式确定属性的值。如果该属性是指定 JNDI 工厂列表的标准 JNDI 属性之一（如 上文所列），则这些值被串联成一个以冒号分隔的列表。对于其他属性，只使用最先找到的值。

当服务提供者需要确定某一属性的值时，它通常将直接从环境中获取该值。服务提供者可以定义将置于其本身提供者资源文件中的特定于提供者的属性。在这种情况下，它应该根据上文所述合并这些值。

这样，每个服务提供者开发人员便可以指定与该服务提供者一起使用的工厂列表。这可以由应用程序或 applet 的部署者指定的应用程序资源修改，而这些资源又可以由用户修改。

从以下版本开始：
1.3

字段摘要
static String APPLET
          该常量保存用来指定搜索其他属性时将使用的初始上下文构造方法的 applet 的环境属性名称。
static String AUTHORITATIVE
          该常量保存用来指定所请求服务的权威性的环境属性名称。
static String BATCHSIZE
          该常量保存用来指定通过服务协议返回数据时要使用的批处理量 (batch size) 的环境属性名称。
static String DNS_URL
          该常量保存用来指定用于 JNDI URL 上下文的 DNS 主机名和域名（例如 "dns://somehost/wiz.com"）的环境属性名称。
static String INITIAL_CONTEXT_FACTORY
          该常量保存用来指定要使用的初始上下文工厂的环境属性名称。
static String LANGUAGE
          该常量保存用来指定用于服务的首选语言的环境属性名称。
static String OBJECT_FACTORIES
          该常量保存用来指定要使用的对象工厂列表的环境属性名称。
static String PROVIDER_URL
          该常量保存用来指定要使用的服务提供者配置信息的环境属性名称。
static String REFERRAL
          该常量保存用来指定将如何处理服务提供者遇到的引用的环境属性名称。
static String SECURITY_AUTHENTICATION
          该常量保存用来指定将使用的安全级别的环境属性名称。
static String SECURITY_CREDENTIALS
          该常量保存用来指定用于验证服务调用者主体证书的环境属性名称。
static String SECURITY_PRINCIPAL
          该常量保存用来指定用于验证服务调用者主体身份的环境属性名称。
static String SECURITY_PROTOCOL
          该常量保存用来指定将使用的安全协议的环境属性名称。
static String STATE_FACTORIES
          该常量保存用来指定要使用的状态工厂列表的环境属性名称。
static String URL_PKG_PREFIXES
          该常量保存用来指定加载 URL 上下文工厂时要使用的包前缀列表的环境属性名称。
 
方法摘要
 Object addToEnvironment(String propName, Object propVal)
          将一个新环境属性添加到此上下文的环境中。
 void bind(Name name, Object obj)
          将名称绑定到对象。
 void bind(String name, Object obj)
          将名称绑定到对象。
 void close()
          关闭此上下文。
 Name composeName(Name name, Name prefix)
          将此上下文的名称与相对于此上下文的名称组合。
 String composeName(String name, String prefix)
          将此上下文的名称与相对于此上下文的名称组合。
 Context createSubcontext(Name name)
          创建并绑定一个新上下文。
 Context createSubcontext(String name)
          创建并绑定一个新上下文。
 void destroySubcontext(Name name)
          销毁指定上下文，并将它从名称空间中移除。
 void destroySubcontext(String name)
          销毁指定上下文，并将它从名称空间中移除。
 Hashtable<?,?> getEnvironment()
          检索对此上下文有效的环境。
 String getNameInNamespace()
          在此上下文自己的名称空间中检索其完全名称。
 NameParser getNameParser(Name name)
          检索与指定上下文关联的解析器。
 NameParser getNameParser(String name)
          检索与指定上下文关联的解析器。
 NamingEnumeration<NameClassPair> list(Name name)
          枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象的类名称。
 NamingEnumeration<NameClassPair> list(String name)
          枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象的类名称。
 NamingEnumeration<Binding> listBindings(Name name)
          枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象。
 NamingEnumeration<Binding> listBindings(String name)
          枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象。
 Object lookup(Name name)
          检索指定的对象。
 Object lookup(String name)
          检索指定的对象。
 Object lookupLink(Name name)
          按照除名称的最终原子组件以外的链接检索指定对象。
 Object lookupLink(String name)
          按照除名称的最终原子组件以外的链接检索指定对象。
 void rebind(Name name, Object obj)
          将名称绑定到对象，重写任何现有绑定。
 void rebind(String name, Object obj)
          将名称绑定到对象，重写所有现有绑定。
 Object removeFromEnvironment(String propName)
          从此上下文的环境中移除一个环境属性。
 void rename(Name oldName, Name newName)
          将一个新名称绑定到已经被绑定到某一旧名称的对象上，并取消对旧名称的绑定。
 void rename(String oldName, String newName)
          将一个新名称绑定到已经被绑定到某一旧名称的对象上，并取消对旧名称的绑定。
 void unbind(Name name)
          取消对指定对象的绑定。
 void unbind(String name)
          取消对指定对象的绑定。
 

字段详细信息

INITIAL_CONTEXT_FACTORY

static final String INITIAL_CONTEXT_FACTORY
该常量保存用来指定要使用的初始上下文工厂的环境属性名称。该属性的值应该是将创建初始上下文的工厂类的完全限定类名称。此属性可以在传递给初始上下文构造方法的环境参数、applet 参数、系统属性或应用程序资源文件中指定。如果没有在任何这些源中指定该属性，则在需要初始上下文完成某项操作时将抛出 NoInitialContextException。

此常量的值是 "java.naming.factory.initial"。

另请参见：
InitialContext, InitialDirContext, NamingManager.getInitialContext(java.util.Hashtable ), InitialContextFactory, NoInitialContextException, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, 常量字段值

OBJECT_FACTORIES

static final String OBJECT_FACTORIES
该常量保存用来指定要使用的对象工厂列表的环境属性名称。该属性的值应该是工厂类以冒号分隔的完全限定类名称列表，这些类将在给定关于对象信息的情况下创建该对象。此属性可以在环境、applet 参数、系统属性或者一个或多个资源文件中指定。

此常量的值是 "java.naming.factory.object"。

另请参见：
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable ), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, 常量字段值

STATE_FACTORIES

static final String STATE_FACTORIES
该常量保存用来指定要使用的状态工厂列表的环境属性名称。该属性的值应该是状态工厂类以冒号分隔的完全限定类名称列表，这些类将被用来在给定对象本身的情况下获得该对象的状态。此属性可以在环境、applet 参数、系统属性或者一个或多个资源文件中指定。

此常量的值是 "java.naming.factory.state"。

从以下版本开始：
1.3
另请参见：
NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable ), StateFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, 常量字段值

URL_PKG_PREFIXES

static final String URL_PKG_PREFIXES
该常量保存用来指定加载 URL 上下文工厂时要使用的包前缀列表的环境属性名称。该属性的值应该是工厂类名称以冒号分隔的包前缀列表，该工厂类将创建一个 URL 上下文工厂。此属性可以在环境、applet 参数、系统属性或者一个或多个资源文件中指定。前缀 com.sun.jndi.url 总是被追加到可能为空的包前缀列表中。

此常量的值是 "java.naming.factory.url.pkgs"。

另请参见：
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable ), NamingManager.getURLContext(java.lang.String, java.util.Hashtable ), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, 常量字段值

PROVIDER_URL

static final String PROVIDER_URL
该常量保存用来指定要使用的服务提供者配置信息的环境属性名称。该属性的值应该包含一个 URL 字符串（例如 "ldap://somehost:389"）。此属性可以在环境、applet 参数、系统属性或资源文件中指定。如果没有在任何这些源中指定该属性，则由服务提供者确定默认配置。

此常量的值是 "java.naming.provider.url"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, 常量字段值

DNS_URL

static final String DNS_URL
该常量保存用来指定用于 JNDI URL 上下文的 DNS 主机名和域名（例如 "dns://somehost/wiz.com"）的环境属性名称。此属性可以在环境、applet 参数、系统属性或资源文件中指定。如果没有在任何这些源中指定该属性并且程序试图使用包含 DNS 名称的 JNDI URL，则将抛出 ConfigurationException。

此常量的值是 "java.naming.dns.url"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

AUTHORITATIVE

static final String AUTHORITATIVE
该常量保存用来指定所请求服务的权威性的环境属性名称。如果该属性的值是字符串 "true"，则意味着访问的是最具权威的源（即无需任何缓冲或副本）。如果该值是其他任何值，则该源不必（但可能）是权威性的。如果该值未指定，则默认为 "false"。

此常量的值是 "java.naming.authoritative"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

BATCHSIZE

static final String BATCHSIZE
该常量保存用来指定通过服务协议返回数据时要使用的批处理量 (batch size) 的环境属性名称。这是一个提示，提示提供者按指定的批处理量返回操作的结果，以便提供者可以优化其性能和对资源的使用。该属性的值是某一整数的字符串表示形式。如果该值未指定，则由服务提供者确定批处理量。

此常量的值是 "java.naming.batchsize"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

REFERRAL

static final String REFERRAL
该常量保存用来指定将如何处理服务提供者遇到的引用的环境属性名称。该属性的值是以下字符串之一：
"follow"
自动服从引用
"ignore"
忽略引用
"throw"
在遇到引用时抛出 ReferralException。
如果未指定此属性，则由提供者确定默认值。

此常量的值是 "java.naming.referral"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

SECURITY_PROTOCOL

static final String SECURITY_PROTOCOL
该常量保存用来指定将使用的安全协议的环境属性名称。该属性的值是一个由服务提供者确定的字符串（例如 "ssl"）。如果未指定此属性，则由服务提供者确定如何运行。

此常量的值是 "java.naming.security.protocol"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

SECURITY_AUTHENTICATION

static final String SECURITY_AUTHENTICATION
该常量保存用来指定将使用的安全级别的环境属性名称。该属性的值是下列字符串之一："none"、"simple" 和 "strong"。如果未指定此属性，则由服务提供者确定如何运行。

此常量的值是 "java.naming.security.authentication"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

SECURITY_PRINCIPAL

static final String SECURITY_PRINCIPAL
该常量保存用来指定用于验证服务调用者主体身份的环境属性名称。主体格式取决于验证方案。如果未指定此属性，则由服务提供者确定如何运行。

此常量的值是 "java.naming.security.principal"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

SECURITY_CREDENTIALS

static final String SECURITY_CREDENTIALS
该常量保存用来指定用于验证服务调用者主体证书的环境属性名称。该属性值取决于验证方案。例如，它可以是一个散列式密码、明文密码、密钥、证书，等等。如果未指定此属性，则由服务提供者确定如何运行。

此常量的值是 "java.naming.security.credentials"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

LANGUAGE

static final String LANGUAGE
该常量保存用来指定用于服务的首选语言的环境属性名称。该属性的值是一个以冒号分隔的语言标记列表，RFC 1766 中定义了这些标记。如果未指定此属性，则由服务提供者确定语言优先级。

此常量的值是 "java.naming.language"。

另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), 常量字段值

APPLET

static final String APPLET
该常量保存用来指定搜索其他属性时将使用的初始上下文构造方法的 applet 的环境属性名称。此属性的值是将被执行的 java.applet.Applet 实例。可以在传递给初始上下文构造方法的环境参数中指定此属性。在设置此属性时，初始上下文构造方法在系统属性中查找的每个属性都是在 applet 的参数列表中最先查找到的属性。如果未指定此属性，则初始上下文构造方法将仅在传递给它的环境参数、系统属性和应用程序资源文件中搜索属性。

此常量的值是 "java.naming.applet"。

从以下版本开始：
1.3
另请参见：
addToEnvironment(String, Object), removeFromEnvironment(String), InitialContext, 常量字段值
方法详细信息

lookup

Object lookup(Name name)
              throws NamingException
检索指定的对象。如果 name 为空，则返回此上下文的一个新实例（该实例表示与此上下文相同的命名上下文，但其环境可以独立地进行修改，而且可以并发访问）。

参数：
name - 要查询的对象的名称
返回：
绑定到 name 的对象
抛出：
NamingException - 如果遇到命名异常
另请参见：
lookup(String), lookupLink(Name)

lookup

Object lookup(String name)
              throws NamingException
检索指定的对象。有关详细信息请参见 lookup(Name)。

参数：
name - 要查询的对象的名称
返回：
绑定到 name 的对象
抛出：
NamingException - 如果遇到命名异常

bind

void bind(Name name,
          Object obj)
          throws NamingException
将名称绑定到对象。所有中间上下文和目标上下文（由该名称最终原子组件以外的其他所有组件指定）都必须已经存在。

参数：
name - 要绑定的名称，不可以为空
obj - 要绑定的对象，可能为 null
抛出：
NameAlreadyBoundException - 如果已经绑定了 name
InvalidAttributesException - 如果对象不支持所有强制属性
NamingException - 如果遇到命名异常
另请参见：
bind(String, Object), rebind(Name, Object), DirContext.bind(Name, Object, javax.naming.directory.Attributes)

bind

void bind(String name,
          Object obj)
          throws NamingException
将名称绑定到对象。有关详细信息请参见 bind(Name, Object)。

参数：
name - 要绑定的名称，不可以为空
obj - 要绑定的对象，可能为 null
抛出：
NameAlreadyBoundException - 如果已经绑定了 name
InvalidAttributesException - 如果对象不支持所有强制属性
NamingException - 如果遇到命名异常

rebind

void rebind(Name name,
            Object obj)
            throws NamingException
将名称绑定到对象，重写任何现有绑定。所有中间上下文和目标上下文（由该名称最终原子组件以外的其他所有组件指定）都必须已经存在。

如果该对象是一个 DirContext，则使用该对象的属性替换与该名称关联的所有现有属性。否则，与该名称关联的所有现有属性保持不变。

参数：
name - 要绑定的名称，不可以为空 <