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 - 要绑定的名称，不可以为空

obj - 要绑定的对象，可能为 null

抛出：

InvalidAttributesException - 如果对象不支持所有强制属性

NamingException - 如果遇到命名异常

另请参见：

rebind(String, Object), bind(Name, Object), DirContext.rebind(Name, Object, javax.naming.directory.Attributes), DirContext

rebind

void rebind(String name,
            Object obj)
            throws NamingException

将名称绑定到对象，重写所有现有绑定。有关详细信息请参见 rebind(Name, Object)。

参数：

name - 要绑定的名称，不可以为空

obj - 要绑定的对象，可能为 null

抛出：

InvalidAttributesException - 如果对象不支持所有强制属性

NamingException - 如果遇到命名异常

unbind

void unbind(Name name)
            throws NamingException

取消对指定对象的绑定。从目标上下文中移除名为 name 的最终原子名称，目标上下文由 name 的最终原子部分以外的所有名称指定。

此方法是幂等的 (idempotent)。即使最终原子名称没有绑定在目标上下文中，该操作也能成功，但如果不存在任何中间上下文，则将抛出 NameNotFoundException。

所有与该名称关联的属性都被移除。不更改中间上下文。

参数：

name - 要取消绑定的名称，不能为空

抛出：

NameNotFoundException - 如果不存在中间上下文

NamingException - 如果遇到命名异常

另请参见：

unbind(String)

unbind

void unbind(String name)
            throws NamingException

取消对指定对象的绑定。有关详细信息请参见 unbind(Name)。

参数：

name - 要取消绑定的名称，不能为空

抛出：

NameNotFoundException - 如果不存在中间上下文

NamingException - 如果遇到命名异常

rename

void rename(Name oldName,
            Name newName)
            throws NamingException

将一个新名称绑定到已经被绑定到某一旧名称的对象上，并取消对旧名称的绑定。两个名称都是相对于此上下文的。所有与旧名称关联的属性都改为与新名称关联。不更改旧名称的中间上下文。

参数：

oldName - 现有绑定的名称，不能为空

newName - 新绑定的名称，不能为空

抛出：

NameAlreadyBoundException - 如果已经绑定了 newName

NamingException - 如果遇到命名异常

另请参见：

rename(String, String), bind(Name, Object), rebind(Name, Object)

rename

void rename(String oldName,
            String newName)
            throws NamingException

将一个新名称绑定到已经被绑定到某一旧名称的对象上，并取消对旧名称的绑定。有关详细信息请参见 rename(Name, Name)。

参数：

oldName - 现有绑定的名称，不能为空

newName - 新绑定的名称，不能为空

抛出：

NameAlreadyBoundException - 如果已经绑定了 newName

NamingException - 如果遇到命名异常

list

NamingEnumeration<NameClassPair> list(Name name)
                                      throws NamingException

枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象的类名称。不包括任何子上下文的内容。

如果将某一绑定添加到此上下文，或者从此上下文中移除某个绑定，则对以前返回的枚举的影响是不确定的。

参数：

name - 要列出的上下文的名称

返回：

名称和此上下文中的绑定的类名称所组成的枚举。每个枚举元素都属于 NameClassPair 类型。

抛出：

NamingException - 如果遇到命名异常

另请参见：

list(String), listBindings(Name), NameClassPair

list

NamingEnumeration<NameClassPair> list(String name)
                                      throws NamingException

枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象的类名称。有关详细信息请参见 list(Name)。

参数：

name - 要列出的上下文的名称

返回：

名称和此上下文中的绑定的类名称所组成的枚举。每个枚举元素都属于 NameClassPair 类型。

抛出：

NamingException - 如果遇到命名异常

listBindings

NamingEnumeration<Binding> listBindings(Name name)
                                        throws NamingException

枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象。不包括任何子上下文的内容。

如果将某一绑定添加到此上下文，或者从此上下文中移除某个绑定，则对以前返回的枚举的影响是不确定的。

参数：

name - 要列出的上下文的名称

返回：

此上下文中的绑定所组成的枚举。每个枚举元素都属于 Binding 类型。

抛出：

NamingException - 如果遇到命名异常

另请参见：

listBindings(String), list(Name), Binding

listBindings

NamingEnumeration<Binding> listBindings(String name)
                                        throws NamingException

枚举绑定在指定上下文中的名称，以及绑定到这些名称的对象。有关详细信息请参见 listBindings(Name)。

参数：

name - 要列出的上下文的名称

返回：

此上下文中的绑定所组成的枚举。每个枚举元素都属于 Binding 类型。

抛出：

NamingException - 如果遇到命名异常

destroySubcontext

void destroySubcontext(Name name)
                       throws NamingException

销毁指定上下文，并将它从名称空间中移除。所有与该名称关联的属性也被移除。不销毁中间上下文。

此方法是幂等的。即使最终原子名称没有绑定在目标上下文中，该操作也能成功，但如果不存在任何中间上下文，则将抛出 NameNotFoundException。

在联合命名系统中，取自某一命名系统的上下文可以绑定到另一个命名系统中的名称上。随后可以使用复合名称在外部上下文 (foreign context) 中查询和执行操作。不过，试图使用此复合名称销毁上下文将失败并抛出 NotContextException，因为外部上下文不是绑定该复合名称的上下文的子上下文。改为使用 unbind() 移除外部上下文的绑定。销毁外部上下文需要对取自该外部上下文的“本机”命名系统的上下文执行 destroySubcontext()。

参数：

name - 要销毁的上下文的名称，不能为空

抛出：

NameNotFoundException - 如果不存在中间上下文

NotContextException - 如果该名称被绑定，但它没有指定一个上下文，或者它没有指定适当类型的上下文

ContextNotEmptyException - 如果指定的上下文不为空

NamingException - 如果遇到命名异常

另请参见：

destroySubcontext(String)

destroySubcontext

void destroySubcontext(String name)
                       throws NamingException

销毁指定上下文，并将它从名称空间中移除。有关详细信息请参见 destroySubcontext(Name)。

参数：

name - 要销毁的上下文的名称，不能为空

抛出：

NameNotFoundException - 如果不存在中间上下文

NotContextException - 如果该名称被绑定，但它没有指定一个上下文，或者它没有指定适当类型的上下文

ContextNotEmptyException - 如果指定的上下文不为空

NamingException - 如果遇到命名异常

createSubcontext

Context createSubcontext(Name name)
                         throws NamingException

创建并绑定一个新上下文。使用给定名称创建一个新上下文，并将它绑定在目标上下文中（由该名称最终原子组件以外的所有名称指定）。所有中间上下文和目标上下文都必须已经存在。

参数：

name - 要创建的上下文的名称，不能为空

返回：

新创建的上下文。

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

InvalidAttributesException - 如果创建子上下文需要指定强制属性

NamingException - 如果遇到命名异常

另请参见：

createSubcontext(String), DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes)

createSubcontext

Context createSubcontext(String name)
                         throws NamingException

创建并绑定一个新上下文。有关详细信息请参见 createSubcontext(Name)。

参数：

name - 要创建的上下文的名称，不能为空

返回：

新创建的上下文。

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

InvalidAttributesException - 如果创建子上下文需要指定强制属性

NamingException - 如果遇到命名异常

lookupLink

Object lookupLink(Name name)
                  throws NamingException

按照除名称的最终原子组件以外的链接检索指定对象。如果绑定到 name 的对象不是一个链接，则返回该对象本身。

参数：

name - 要查询的对象的名称

返回：

绑定到 name 的对象不遵从最终链接（如果有）。

抛出：

NamingException - 如果遇到命名异常

另请参见：

lookupLink(String)

lookupLink

Object lookupLink(String name)
                  throws NamingException

按照除名称的最终原子组件以外的链接检索指定对象。有关详细信息请参见 lookupLink(Name)。

参数：

name - 要查询的对象的名称

返回：

绑定到 name 的对象不遵从最终链接（如果有）

抛出：

NamingException - 如果遇到命名异常

getNameParser

NameParser getNameParser(Name name)
                         throws NamingException

检索与指定上下文关联的解析器。在联合名称空间中，不同的命名系统将以不同的方式解析名称。此方法允许应用程序使用特定命名系统的命名约定获得用来将名称解析成其原子组件的解析器。在任意一个命名系统中，由此方法返回的 NameParser 对象必须相等（可使用 equals() 进行测试）。

参数：

name - 从中获得解析器的上下文的名称

返回：

可以将组合名称解析成其原子组件的名称解析器

抛出：

NamingException - 如果遇到命名异常

另请参见：

getNameParser(String), CompoundName

getNameParser

NameParser getNameParser(String name)
                         throws NamingException

检索与指定上下文关联的解析器。有关详细信息请参见 getNameParser(Name)。

参数：

name - 从中获得解析器的上下文的名称

返回：

可以将组合名称解析成其原子组件的名称解析器

抛出：

NamingException - 如果遇到命名异常

composeName

Name composeName(Name name,
                 Name prefix)
                 throws NamingException

将此上下文的名称与相对于此上下文的名称组合。在给定相对于此上下文的名称(name)以及此上下文相对于其一个祖先的名称(prefix)的情况下，此方法使用适合所涉及命名系统的语法返回这两个名称的组合。也就是说，如果 name 指定一个相对于此上下文的对象，则结果是同一个对象的名称，但该名称相对于祖先上下文。所有名称都不能为 null。

例如，如果此上下文被命名为 "wiz.com"，该名称相对于初始上下文，则

        composeName("east", "wiz.com")      

可能返回 "east.wiz.com"。如果将此上下文命名为 "org/research"，则

        composeName("user/jane", "org/research")    

可能返回 "org/research/user/jane"，而

        composeName("user/jane", "research")        

返回 "research/user/jane"。

参数：

name - 相对于此上下文的名称

prefix - 此上下文相对于其一个祖先的名称

返回：

prefix 和 name 的组合

抛出：

NamingException - 如果遇到命名异常

另请参见：

composeName(String, String)

composeName

String composeName(String name,
                   String prefix)
                   throws NamingException

将此上下文的名称与相对于此上下文的名称组合。有关详细信息请参见 composeName(Name, Name)。

参数：

name - 相对于此上下文的名称

prefix - 此上下文相对于其一个祖先的名称

返回：

prefix 和 name 的组合

抛出：

NamingException - 如果遇到命名异常

addToEnvironment

Object addToEnvironment(String propName,
                        Object propVal)
                        throws NamingException

将一个新环境属性添加到此上下文的环境中。如果该属性已经存在，则重写该属性的值。有关环境属性的更多详细信息，请参阅类描述。

参数：

propName - 要添加的环境属性的名称，不能为 null

propVal - 要添加的属性的值，不能为 null

返回：

该属性以前的值，如果该属性以前不在此环境中，则返回 null

抛出：

NamingException - 如果遇到命名异常

另请参见：

getEnvironment(), removeFromEnvironment(String)

removeFromEnvironment

Object removeFromEnvironment(String propName)
                             throws NamingException

从此上下文的环境中移除一个环境属性。有关环境属性的更多详细信息，请参阅类描述。

参数：

propName - 要移除的环境属性的名称，不能为 null

返回：

该属性以前的值，如果该属性以前不在此环境中，则返回 null

抛出：

NamingException - 如果遇到命名异常

另请参见：

getEnvironment(), addToEnvironment(String, Object)

getEnvironment

Hashtable<?,?> getEnvironment()
                              throws NamingException

检索对此上下文有效的环境。有关环境属性的更多详细信息，请参阅类描述。

调用者不应对返回的对象进行任何更改：因为这些更改对于上下文的影响是不确定的。可以使用 addToEnvironment() 和 removeFromEnvironment() 更改此上下文的环境。

返回：

此上下文的环境，决不能为 null

抛出：

NamingException - 如果遇到命名异常

另请参见：

addToEnvironment(String, Object), removeFromEnvironment(String)

close

void close()
           throws NamingException

关闭此上下文。此方法立即释放此上下文的资源，而不是等待垃圾回收器自动释放它们。

此方法是幂等的：对已经关闭的上下文调用此方法无效。对已关闭的上下文调用其他任何方法都是不允许的，这会导致不确定的行为。

抛出：

NamingException - 如果遇到命名异常

getNameInNamespace

String getNameInNamespace()
                          throws NamingException

在此上下文自己的名称空间中检索其完全名称。

许多命名服务都有一个“完全名称”的概念，用于其各自的名称空间中的对象。例如，LDAP 项有一个独特的名称，而 DNS 记录有一个完全限定名。此方法允许客户端应用程序检索此名称。此方法返回的字符串不是一个 JNDI 复合名称，不应将它直接传递给上下文方法。在没有完全名称概念的命名系统中，将抛出 OperationNotSupportedException。

返回：

此上下文在其自己的名称空间中的名称，决不能为 null

抛出：

OperationNotSupportedException - 如果命名系统没有完全名称的概念

NamingException - 如果遇到命名异常

从以下版本开始：

1.3