|
|||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
javax.naming.directory
接口 DirContext
- 所有超级接口:
- Context
- 所有已知子接口:
- EventDirContext, LdapContext
- 所有已知实现类:
- InitialDirContext, InitialLdapContext
-
public interface DirContext
- extends Context
目录服务接口,包含一些用于检查和更新与对象关联的属性以及搜索目录的方法。
名称
作为参数传递给 DirContext 方法的每个名称都相对于该上下文。空名称用于命名上下文本身。名称参数永远不能为 null。大多数方法具有重载形式,一种使用 Name
参数,另一种使用 String
参数。这些重载的方法是等效的,因为如果 Name
和 String
参数只是同一名称的不同表示形式,则相同方法的重载形式以相同的方式运行。在以下的方法描述中,只记录一种形式。第二种形式链接到第一种:对两者应用相同的文档。
有关 Context 方法的名称参数解释的讨论,请参阅 Context。这些相同的规则也适用于 DirContext 方法的名称参数。
属性模型
有两个属性应该与之关联的基本模型。第一,属性可以直接与 DirContext 对象关联。在此模型中,对命名对象进行的属性操作大致等效于先对名称进行查找(返回 DirContext 对象),然后对 DirContext 对象(调用方在其中提供空名称)调用该属性操作。这些属性可视为与对象存储在一起(注意,这并不意味着实现必须进行此操作)。第二个模型是属性与 DirContext 中的名称(通常是原子名称)相关联。在此模型中,对命名对象进行的属性操作大致等效于先对命名对象父 DirContext 的名称进行查找,然后对父 DirContext 对象(调用方在其中提供最终原子名称)调用该属性操作。这些属性可视为存储在父 DirContext 中(注意,这并不意味着实现必须进行此操作)。不是 DirContext 的对象只要其父级是 DirContext 就可以有属性。
JNDI 同时支持这两种模型。由各个服务提供程序决定将属性“存储”在何处。JNDI 客户端在没有对对象属性是作为对象的一部分存储,还是存储在父对象中并与对象名称关联作出假设时,是最安全的。
属性类型名称
在 getAttributes() 和 search() 方法中,可以通过提供一个属性名称(字符串)列表来提供要返回的属性。得到的属性可能与指定的属性名称不相同。这是因为有些目录支持使其返回其他属性的功能。这些功能包括属性子类化、属性名同义词和属性语言码。在属性子类化中,属性在类层次中定义。例如,在某些目录中,"name" 属性可能是所有与名称相关的属性(包括 "commonName" 和 "surName")的超类。请求 "name" 属性可能同时返回 "commonName" 和 "surName" 属性。
使用属性类型同义词,目录可以将多个名称分配给同一属性。例如,"cn" 和 "commonName" 可能指的是同一属性。请求 "cn" 可能返回 "commonName" 属性。
有些目录支持属性的语言码。例如,向这种目录请求 "description" 属性可能返回以下全部属性:
- description
- description;lang-en
- description;lang-de
- description;lang-fr
操作属性
有些目录具有“操作属性”的概念,操作属性指为了管理而与目录对象关联的属性。一个操作属性的示例是对象的访问控制列表。
在 getAttributes() 和 search() 方法中,可以通过提供 null 作为要返回的属性列表来指定所有与请求的对象关联的属性。返回的属性不 包括操作属性。要检索操作属性,必须显式指定它们。
命名上下文
在某些方法中,必须将名称解析为上下文(例如,在搜索单个级别的上下文时)。这些方法的文档使用术语命名上下文 来描述其名称参数。对于这些方法,如果命名对象不是 DirContext,则抛出 NotContextException
。除了这些方法之外,其他方法均不要求命名对象 为 DirContext。
参数
作为参数传递给任何方法的 Attributes、SearchControls 或数组对象不能被服务提供程序修改。服务提供程序可以在操作期间持有对它的引用,包括方法结果的所有枚举和对生成的所有反向链接的处理。调用方在此期间不应修改对象。任何方法返回的 Attributes 对象都归调用方所有。调用方可以在以后修改它,而服务提供程序则不能。
异常
此接口中的所有方法都可以抛出 NamingException 或其任一子类。有关每个异常的详细信息,请参阅 NamingException 及其子类。
- 从以下版本开始:
- 1.3
- 另请参见:
-
Context
字段摘要 | |
---|---|
static int |
ADD_ATTRIBUTE 此常量指定使用指定值添加属性。 |
static int |
REMOVE_ATTRIBUTE 此常量指定从属性中删除指定的属性值。 |
static int |
REPLACE_ATTRIBUTE 此常量指定使用指定值替换属性。 |
方法摘要 | |
---|---|
void |
bind(Name name, Object obj, Attributes attrs) 将名称与关联的属性一起绑定到一个对象。 |
void |
bind(String name, Object obj, Attributes attrs) 将名称与关联的属性一起绑定到一个对象。 |
DirContext |
createSubcontext(Name name, Attributes attrs) 创建并绑定新的上下文及关联的属性。 |
DirContext |
createSubcontext(String name, Attributes attrs) 创建并绑定新的上下文及关联的属性。 |
Attributes |
getAttributes(Name name) 检索与命名对象关联的所有属性。 |
Attributes |
getAttributes(Name name, String[] attrIds) 检索与命名对象关联的选定属性。 |
Attributes |
getAttributes(String name) 检索所有与命名对象关联的属性。 |
Attributes |
getAttributes(String name, String[] attrIds) 检索与命名对象关联的选定属性。 |
DirContext |
getSchema(Name name) 检索与命名对象关联的模式。 |
DirContext |
getSchema(String name) 检索与命名对象关联的模式。 |
DirContext |
getSchemaClassDefinition(Name name) 检索包含命名对象类定义的模式对象的上下文。 |
DirContext |
getSchemaClassDefinition(String name) 检索包含命名对象类定义的模式对象的上下文。 |
void |
modifyAttributes(Name name, int mod_op, Attributes attrs) 修改与命名对象关联的属性。 |
void |
modifyAttributes(Name name, ModificationItem[] mods) 使用有序的修改列表修改与命名对象关联的属性。 |
void |
modifyAttributes(String name, int mod_op, Attributes attrs) 修改与命名对象关联的属性。 |
void |
modifyAttributes(String name, ModificationItem[] mods) 使用有序的修改列表修改与命名对象关联的属性。 |
void |
rebind(Name name, Object obj, Attributes attrs) 将名称与关联的属性一起绑定到一个对象,并重写任何现有绑定。 |
void |
rebind(String name, Object obj, Attributes attrs) 将名称与关联的属性一起绑定到一个对象,并重写任何现有绑定。 |
NamingEnumeration<SearchResult> |
search(Name name, Attributes matchingAttributes) 在单个上下文中搜索包含指定属性集的对象。 |
NamingEnumeration<SearchResult> |
search(Name name, Attributes matchingAttributes, String[] attributesToReturn) 在单个上下文中搜索包含指定属性集的对象,并检索选定的属性。 |
NamingEnumeration<SearchResult> |
search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) 在命名上下文或对象中搜索符合给定搜索过滤器的项。 |
NamingEnumeration<SearchResult> |
search(Name name, String filter, SearchControls cons) 在命名上下文或对象中搜索符合给定搜索过滤器的项。 |
NamingEnumeration<SearchResult> |
search(String name, Attributes matchingAttributes) 在单个上下文中搜索包含指定属性集的对象。 |
NamingEnumeration<SearchResult> |
search(String name, Attributes matchingAttributes, String[] attributesToReturn) 在单个上下文中搜索包含指定属性集的对象,并检索选定的属性。 |
NamingEnumeration<SearchResult> |
search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) 在命名上下文或对象中搜索符合给定搜索过滤器的项。 |
NamingEnumeration<SearchResult> |
search(String name, String filter, SearchControls cons) 在命名上下文或对象中搜索符合给定搜索过滤器的项。 |
从接口 javax.naming.Context 继承的方法 |
---|
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind |
字段详细信息 |
---|
ADD_ATTRIBUTE
static final int ADD_ATTRIBUTE
-
此常量指定使用指定值添加属性。
如果属性不存在,则创建属性。得到的属性会将指定的值集合与以前的值集合并起来。如果属性必须至少有一个值,则添加不带值的属性将抛出
InvalidAttributeValueException
。对于属性已经存在的单值属性,抛出AttributeInUseException
。如果试图将一个以上的值添加到单值属性,则抛出InvalidAttributeValueException
。此常量的值为 1。
REPLACE_ATTRIBUTE
static final int REPLACE_ATTRIBUTE
-
此常量指定使用指定值替换属性。
如果属性已经存在,则使用新的指定值替换所有现有值。如果该属性不存在,则创建它。如果没有指定值,则删除属性的所有值。如果要求属性必须至少有一个值,则移除最后一个值时会将属性一起移除。如果试图将一个以上的值添加到单值属性,则抛出
InvalidAttributeValueException
。此常量的值为 2。
REMOVE_ATTRIBUTE
static final int REMOVE_ATTRIBUTE
-
此常量指定从属性中删除指定的属性值。
得到的属性值集合不同于其以前的值集合和指定的值集合。如果没有指定值,则删除整个属性。如果属性不存在,或者指定值集合的某些或全部成员不存在,则可能忽略此情况并操作成功,也可能抛出 NamingException 指示此情况。如果要求属性必须至少有一个值,则移除最后一个值时会将属性一起移除。
此常量的值为 3。
方法详细信息 |
---|
getAttributes
Attributes getAttributes(Name name) throws NamingException
- 检索与命名对象关联的所有属性。请参阅关于属性模型、属性类型名称和操作属性的类描述。
-
-
- 参数:
-
name
- 对象名,通过该对象名检索属性 - 返回:
-
与
name
关联的属性集。如果名称没有属性,则返回空属性集;永远不为 null。 - 抛出:
-
NamingException
- 如果遇到命名异常 - 另请参见:
-
getAttributes(String)
,getAttributes(Name, String[])
getAttributes
Attributes getAttributes(String name) throws NamingException
-
检索所有与命名对象关联的属性。有关详细信息,请参阅
getAttributes(Name)
。 -
-
- 参数:
-
name
- 对象名,通过该对象名检索属性 - 返回:
-
与
name
关联的属性集 - 抛出:
-
NamingException
- 如果遇到命名异常
getAttributes
Attributes getAttributes(Name name, String[] attrIds) throws NamingException
-
检索与命名对象关联的选定属性。请参阅关于属性模型、属性类型名称和操作属性的类描述。
如果对象没有指定的属性,则目录将忽略不存在的属性,并返回那些对象所具有的请求属性。
目录返回的属性可能多于请求(请参阅类描述中的属性类型名称),但不允许返回任意的、无关的属性。
另请参阅类描述中的操作属性。
-
-
- 参数:
-
name
- 对象名,通过该对象名检索属性 -
attrIds
- 要检索的属性的标识符。null 指示应该检索所有属性;空数组指示不应检索任何属性。 - 返回:
- 请求的属性;永远不为 null
- 抛出:
-
NamingException
- 如果遇到命名异常
getAttributes
Attributes getAttributes(String name, String[] attrIds) throws NamingException
-
检索与命名对象关联的选定属性。有关详细信息,请参阅
getAttributes(Name, String[])
。 -
-
- 参数:
-
name
- 对象名,通过该对象名检索属性 -
attrIds
- 要检索的属性的标识符。null 指示应该检索所有属性;空数组指示不应检索任何属性。 - 返回:
- 请求的属性;永远不为 null
- 抛出:
-
NamingException
- 如果遇到命名异常
modifyAttributes
void modifyAttributes(Name name, int mod_op, Attributes attrs) throws NamingException
- 修改与命名对象关联的属性。没有指定修改的顺序。在可能的情况下,将以原子方式执行修改。
-
-
- 参数:
-
name
- 属性将被更新的对象的名称 -
mod_op
- 修改操作,为以下操作之一:ADD_ATTRIBUTE
、REPLACE_ATTRIBUTE
和REMOVE_ATTRIBUTE
。 -
attrs
- 要用于修改的属性;不能为 null - 抛出:
-
AttributeModificationException
- 如果不能成功完成修改 -
NamingException
- 如果遇到命名异常 - 另请参见:
-
modifyAttributes(Name, ModificationItem[])