|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
public interface Context
此接口表示一个命名上下文,它由一组名称到对象的绑定组成。它包含检查和更新这些绑定的一些方法。
大多数方法具有重载形式,一种带有 Name
参数,另一种带有 String
参数。这些重载的方法是等效的:如果 Name
和 String
参数只是相同名称的不同表示形式,则相同方法的重载形式的行为也相同。在以下方法描述中,仅完整记录一种形式。第二种形式将链接到第一种:对两者应用相同的文档。
对于支持联合的系统,Context 方法的 String 名称参数是复合名称。是 CompositeName 实例的那些名称参数被视为复合名称,而不是 CompositeName 实例的 Name 参数被视为组合名称(可能是 CompoundName 实例或组合名称的其他实现)。这允许将 NameParser.parse() 的结果用作 Context 方法的参数。在 JNDI 1.2 之前,所有名称参数都被视为复合名称。
此外,对于支持联合的系统,NamingEnumeration 中所有从 list() 和 listBindings() 返回的名称都是表示为字符串的复合名称。有关名称的字符串语法,请参见 CompositeName。
对于不支持联合的系统,名称参数(Name 或 String 形式)和 NamingEnumeration 中返回的名称可能是其自己的名称空间中的名称,而不是复合名称空间中的名称,这由服务提供者决定。
lookup
方法传递空名称将返回一个表示相同命名上下文的新 Context 实例。
为了实现并发控制,返回 NamingEnumeration 的 Context 操作在枚举仍在使用中或者仍在遵从该操作生成的所有引用时被认为尚未完成。
JNDI 应用程序需要一种方式来传达定义访问命名服务和目录服务的环境的各种首选项和属性。例如,为了访问服务,某个上下文可能需要安全证书的规约。另一个上下文可能要求提供服务器的配置信息。这些被称为某一上下文的环境。Context 接口提供一些检索和更新此环境的方法。
该环境在上下文方法从一个上下文到下一个上下文时从父上下文中继承。对某一上下文环境的更改不会直接影响其他上下文的环境。
当将环境属性用于有效性和/或验证有效性时,这些属性与实现有关。例如,一些与安全有关的属性被服务提供者用于“登录”目录。此登录过程可能发生在创建上下文时,或者发生在第一次对该上下文调用方法时。无论这在何时或是否发生,此环境属性都与实现有关。在将环境属性添加到上下文中或从上下文中移除时,验证这些更改的有效性也都与实现有关。例如,验证某些属性可能发生在进行更改时,或者发生在对上下文执行下一个操作时,抑或根本不验证。
拥有对某一上下文的引用的任何对象都可以检查该上下文的环境。敏感信息(比如明文密码)不应该存储在该环境中,除非已知实现能保护这类信息。
要简化设置 JNDI 应用程序所需环境的任务,可以将资源文件 与应用程序组件和服务提供者一起发布。JNDI 资源文件是使用属性文件格式的文件(参见 java.util.Properties
),包括一个键/值对列表。键是属性的名称(例如 "java.naming.factory.object"),而值是使用为该属性定义的格式的字符串。以下是 JNDI 资源文件的一个示例:
JNDI 类库读取资源文件,并使属性值随意可用。因此应该认为 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 资源文件:提供者 和应用程序。
[ prefix/] jndiprovider.properties其中 prefix 是提供者的上下文实现的包名称,其每个句点 (".") 都被转换成一个斜杠 ("/")。 例如,假设服务提供者定义了一个带有类名称 com.sun.jndi.ldap.LdapCtx 的上下文实现。此提供者的提供者资源被命名为 com/sun/jndi/ldap/jndiprovider.properties。如果该类不在一个包中,则资源的名称就是 jndiprovider.properties。
JNDI 类库中的某些方法使用指定 JNDI 工厂列表的标准 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 的部署者指定的应用程序资源修改,而这些资源又可以由用户修改。
字段摘要 | |
---|---|
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) 取消对指定对象的绑定。 |
字段详细信息 |
---|
static final String INITIAL_CONTEXT_FACTORY
此常量的值是 "java.naming.factory.initial"。
InitialContext
,
InitialDirContext
,
NamingManager.getInitialContext(java.util.Hashtable
)
,
InitialContextFactory
,
NoInitialContextException
,
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
APPLET
,
常量字段值
static final String OBJECT_FACTORIES
此常量的值是 "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
,
常量字段值
static final String STATE_FACTORIES
此常量的值是 "java.naming.factory.state"。
NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable
)
,
StateFactory
,
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
APPLET
,
常量字段值
static final String URL_PKG_PREFIXES
此常量的值是 "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
,
常量字段值
static final String PROVIDER_URL
此常量的值是 "java.naming.provider.url"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
APPLET
,
常量字段值
static final String DNS_URL
此常量的值是 "java.naming.dns.url"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String AUTHORITATIVE
此常量的值是 "java.naming.authoritative"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String BATCHSIZE
此常量的值是 "java.naming.batchsize"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String REFERRAL
此常量的值是 "java.naming.referral"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String SECURITY_PROTOCOL
此常量的值是 "java.naming.security.protocol"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String SECURITY_AUTHENTICATION
此常量的值是 "java.naming.security.authentication"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String SECURITY_PRINCIPAL
此常量的值是 "java.naming.security.principal"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String SECURITY_CREDENTIALS
此常量的值是 "java.naming.security.credentials"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String LANGUAGE
此常量的值是 "java.naming.language"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
常量字段值
static final String APPLET
此常量的值是 "java.naming.applet"。
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
,
InitialContext
,
常量字段值
方法详细信息 |
---|
Object lookup(Name name) throws NamingException
name
- 要查询的对象的名称
NamingException
- 如果遇到命名异常
lookup(String)
,
lookupLink(Name)
Object lookup(String name) throws NamingException
lookup(Name)
。
name
- 要查询的对象的名称
NamingException
- 如果遇到命名异常
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)
void bind(String name, Object obj) throws NamingException
bind(Name, Object)
。
name
- 要绑定的名称,不可以为空
obj
- 要绑定的对象,可能为 null
NameAlreadyBoundException
- 如果已经绑定了 name
InvalidAttributesException
- 如果对象不支持所有强制属性
NamingException
- 如果遇到命名异常
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
void rebind(String name, Object obj) throws NamingException
rebind(Name, Object)
。
name
- 要绑定的名称,不可以为空
obj
- 要绑定的对象,可能为 null
InvalidAttributesException
- 如果对象不支持所有强制属性
NamingException
- 如果遇到命名异常
void unbind(Name name) throws NamingException
name
的最终原子名称,目标上下文由
name
的最终原子部分以外的所有名称指定。
此方法是幂等的 (idempotent)。即使最终原子名称没有绑定在目标上下文中,该操作也能成功,但如果不存在任何中间上下文,则将抛出 NameNotFoundException。
所有与该名称关联的属性都被移除。不更改中间上下文。
name
- 要取消绑定的名称,不能为空
NameNotFoundException
- 如果不存在中间上下文
NamingException
- 如果遇到命名异常
unbind(String)
void unbind(String name) throws NamingException
unbind(Name)
。
name
- 要取消绑定的名称,不能为空
NameNotFoundException
- 如果不存在中间上下文
NamingException
- 如果遇到命名异常
void rename(Name oldName, Name newName) throws NamingException
oldName
- 现有绑定的名称,不能为空
newName
- 新绑定的名称,不能为空
NameAlreadyBoundException
- 如果已经绑定了
newName
NamingException
- 如果遇到命名异常
rename(String, String)
,
bind(Name, Object)
,
rebind(Name, Object)
void rename(String oldName, String newName) throws NamingException
rename(Name, Name)
。
oldName
- 现有绑定的名称,不能为空
newName
- 新绑定的名称,不能为空
NameAlreadyBoundException
- 如果已经绑定了
newName
NamingException
- 如果遇到命名异常
NamingEnumeration<NameClassPair> list(Name name) throws NamingException
如果将某一绑定添加到此上下文,或者从此上下文中移除某个绑定,则对以前返回的枚举的影响是不确定的。
name
- 要列出的上下文的名称
NamingException
- 如果遇到命名异常
list(String)
,
listBindings(Name)
,
NameClassPair
NamingEnumeration<NameClassPair> list(String name) throws NamingException
list(Name)
。
name
- 要列出的上下文的名称
NamingException
- 如果遇到命名异常
NamingEnumeration<Binding> listBindings(Name name) throws NamingException
如果将某一绑定添加到此上下文,或者从此上下文中移除某个绑定,则对以前返回的枚举的影响是不确定的。
name
- 要列出的上下文的名称
NamingException
- 如果遇到命名异常
listBindings(String)
,
list(Name)
,
Binding
NamingEnumeration<Binding> listBindings(String name) throws NamingException
listBindings(Name)
。
name
- 要列出的上下文的名称
NamingException
- 如果遇到命名异常
void destroySubcontext(Name name) throws NamingException
此方法是幂等的。即使最终原子名称没有绑定在目标上下文中,该操作也能成功,但如果不存在任何中间上下文,则将抛出 NameNotFoundException。
在联合命名系统中,取自某一命名系统的上下文可以绑定到另一个命名系统中的名称上。随后可以使用复合名称在外部上下文 (foreign context) 中查询和执行操作。不过,试图使用此复合名称销毁上下文将失败并抛出 NotContextException,因为外部上下文不是绑定该复合名称的上下文的子上下文。改为使用 unbind() 移除外部上下文的绑定。销毁外部上下文需要对取自该外部上下文的“本机”命名系统的上下文执行 destroySubcontext()。
name
- 要销毁的上下文的名称,不能为空
NameNotFoundException
- 如果不存在中间上下文
NotContextException
- 如果该名称被绑定,但它没有指定一个上下文,或者它没有指定适当类型的上下文
ContextNotEmptyException
- 如果指定的上下文不为空
NamingException
- 如果遇到命名异常
destroySubcontext(String)
void destroySubcontext(String name) throws NamingException
destroySubcontext(Name)
。
name
- 要销毁的上下文的名称,不能为空
NameNotFoundException
- 如果不存在中间上下文
NotContextException
- 如果该名称被绑定,但它没有指定一个上下文,或者它没有指定适当类型的上下文
ContextNotEmptyException
- 如果指定的上下文不为空
NamingException
- 如果遇到命名异常
Context createSubcontext(Name name) throws NamingException
name
- 要创建的上下文的名称,不能为空
NameAlreadyBoundException
- 如果已经绑定了 name
InvalidAttributesException
- 如果创建子上下文需要指定强制属性
NamingException
- 如果遇到命名异常
createSubcontext(String)
,
DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes)
Context createSubcontext(String name) throws NamingException
createSubcontext(Name)
。
name
- 要创建的上下文的名称,不能为空
NameAlreadyBoundException
- 如果已经绑定了 name
InvalidAttributesException
- 如果创建子上下文需要指定强制属性
NamingException
- 如果遇到命名异常
Object lookupLink(Name name) throws NamingException
name
- 要查询的对象的名称
NamingException
- 如果遇到命名异常
lookupLink(String)
Object lookupLink(String name) throws NamingException
lookupLink(Name)
。
name
- 要查询的对象的名称
NamingException
- 如果遇到命名异常
NameParser getNameParser(Name name) throws NamingException
name
- 从中获得解析器的上下文的名称
NamingException
- 如果遇到命名异常
getNameParser(String)
,
CompoundName
NameParser getNameParser(String name) throws NamingException
getNameParser(Name)
。
name
- 从中获得解析器的上下文的名称
NamingException
- 如果遇到命名异常
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)
String composeName(String name, String prefix) throws NamingException
composeName(Name, Name)
。
name
- 相对于此上下文的名称
prefix
- 此上下文相对于其一个祖先的名称
prefix
和
name
的组合
NamingException
- 如果遇到命名异常
Object addToEnvironment(String propName, Object propVal) throws NamingException
propName
- 要添加的环境属性的名称,不能为 null
propVal
- 要添加的属性的值,不能为 null
NamingException
- 如果遇到命名异常
getEnvironment()
,
removeFromEnvironment(String)
Object removeFromEnvironment(String propName) throws NamingException
propName
- 要移除的环境属性的名称,不能为 null
NamingException
- 如果遇到命名异常
getEnvironment()
,
addToEnvironment(String, Object)
Hashtable<?,?> getEnvironment() throws NamingException
调用者不应对返回的对象进行任何更改:因为这些更改对于上下文的影响是不确定的。可以使用 addToEnvironment() 和 removeFromEnvironment() 更改此上下文的环境。
NamingException
- 如果遇到命名异常
addToEnvironment(String, Object)
,
removeFromEnvironment(String)
void close() throws NamingException
此方法是幂等的:对已经关闭的上下文调用此方法无效。对已关闭的上下文调用其他任何方法都是不允许的,这会导致不确定的行为。
NamingException
- 如果遇到命名异常
String getNameInNamespace() throws NamingException
许多命名服务都有一个“完全名称”的概念,用于其各自的名称空间中的对象。例如,LDAP 项有一个独特的名称,而 DNS 记录有一个完全限定名。此方法允许客户端应用程序检索此名称。此方法返回的字符串不是一个 JNDI 复合名称,不应将它直接传递给上下文方法。在没有完全名称概念的命名系统中,将抛出 OperationNotSupportedException。
OperationNotSupportedException
- 如果命名系统没有完全名称的概念
NamingException
- 如果遇到命名异常
|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。