当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

DirContext (Java 2 Platform SE 5.0) - JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

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           此常量指定使用指定值替换属性。

 

从接口 javax.naming.Context 继承的字段
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

 

方法摘要
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。

另请参见：

ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), 常量字段值

---

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE

此常量指定使用指定值替换属性。

如果属性已经存在，则使用新的指定值替换所有现有值。如果该属性不存在，则创建它。如果没有指定值，则删除属性的所有值。如果要求属性必须至少有一个值，则移除最后一个值时会将属性一起移除。如果试图将一个以上的值添加到单值属性，则抛出 InvalidAttributeValueException。

此常量的值为 2。

另请参见：

ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), 常量字段值

---

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE

此常量指定从属性中删除指定的属性值。

得到的属性值集合不同于其以前的值集合和指定的值集合。如果没有指定值，则删除整个属性。如果属性不存在，或者指定值集合的某些或全部成员不存在，则可能忽略此情况并操作成功，也可能抛出 NamingException 指示此情况。如果要求属性必须至少有一个值，则移除最后一个值时会将属性一起移除。

此常量的值为 3。

另请参见：

ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), 常量字段值

方法详细信息

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[])

---

modifyAttributes

void modifyAttributes(String name,
                      int mod_op,
                      Attributes attrs)
                      throws NamingException

修改与命名对象关联的属性。有关详细信息，请参阅 modifyAttributes(Name, int, Attributes)。

参数：

name - 属性将被更新的对象的名称

mod_op - 修改操作，为以下操作之一：ADD_ATTRIBUTE、REPLACE_ATTRIBUTE 和 REMOVE_ATTRIBUTE。

attrs - 要用于修改的属性；不能为 null

抛出：

AttributeModificationException - 如果不能成功完成修改

NamingException - 如果遇到命名异常

---

modifyAttributes

void modifyAttributes(Name name,
                      ModificationItem[] mods)
                      throws NamingException

使用有序的修改列表修改与命名对象关联的属性。按指定的顺序执行修改。每个修改指定一个修改操作代码和一个对其执行操作的属性。在可能的情况下，将以原子方式执行修改。

参数：

name - 属性将被更新的对象的名称

mods - 要执行的修改的有序序列；不能为 null

抛出：

AttributeModificationException - 如果不能成功完成修改

NamingException - 如果遇到命名异常

另请参见：

modifyAttributes(Name, int, Attributes), ModificationItem

---

modifyAttributes

void modifyAttributes(String name,
                      ModificationItem[] mods)
                      throws NamingException

使用有序的修改列表修改与命名对象关联的属性。有关详细信息，请参阅 modifyAttributes(Name, ModificationItem[])。

参数：

name - 属性将被更新的对象的名称

mods - 要执行的修改的有序序列；不能为 null

抛出：

AttributeModificationException - 如果不能成功完成修改

NamingException - 如果遇到命名异常

---

bind

void bind(Name name,
          Object obj,
          Attributes attrs)
          throws NamingException

将名称与关联的属性一起绑定到一个对象。如果 attrs 为 null，则 obj 为 DirContext 时所得绑定将具有与 obj 关联的属性，否则不具有属性。如果 attrs 为非 null，则所得绑定的属性将为 attrs；所有与 obj 关联的属性都将被忽略。

参数：

name - 要绑定的名称；不能为空

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

attrs - 要与绑定关联的属性

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

InvalidAttributesException - 如果没有提供绑定的某些“强制”属性

NamingException - 如果遇到命名异常

另请参见：

Context.bind(Name, Object), rebind(Name, Object, Attributes)

---

bind

void bind(String name,
          Object obj,
          Attributes attrs)
          throws NamingException

将名称与关联的属性一起绑定到一个对象。有关详细信息，请参阅 bind(Name, Object, Attributes)。

参数：

name - 要绑定的名称；不能为空

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

attrs - 要与绑定关联的属性

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

InvalidAttributesException - 如果没有提供绑定的某些“强制”属性

NamingException - 如果遇到命名异常

---

rebind

void rebind(Name name,
            Object obj,
            Attributes attrs)
            throws NamingException

将名称与关联的属性一起绑定到一个对象，并重写任何现有绑定。如果 attrs 为 null 且 obj 为 DirContext，则使用 obj 中的属性。如果 attrs 为 null 而 obj 不为 DirContext，则与已经在目录中绑定的对象关联的所有现有属性均保持不变。如果 attrs 为非 null，则移除与已经在目录中绑定的对象关联的所有现有属性，并将 attrs 与命名对象关联起来。如果 obj 为 DirContext 且 attrs 为非 null，则忽略 obj 的属性。

参数：

name - 要绑定的名称；不能为空

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

attrs - 要与绑定关联的属性

抛出：

InvalidAttributesException - 如果没有提供绑定的某些“强制”属性

NamingException - 如果遇到命名异常

另请参见：

Context.bind(Name, Object), bind(Name, Object, Attributes)

---

rebind

void rebind(String name,
            Object obj,
            Attributes attrs)
            throws NamingException

将名称与关联的属性一起绑定到一个对象，并重写任何现有绑定。有关详细信息，请参阅 rebind(Name, Object, Attributes)。

参数：

name - 要绑定的名称；不能为空

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

attrs - 要与绑定关联的属性

抛出：

InvalidAttributesException - 如果没有提供绑定的某些“强制”属性

NamingException - 如果遇到命名异常

---

createSubcontext

DirContext createSubcontext(Name name,
                            Attributes attrs)
                            throws NamingException

创建并绑定新的上下文及关联的属性。此方法利用给定名称创建新的子上下文，将其绑定在目标上下文（由名称最终原子组件外的所有组件命名）中，并将提供的属性与新创建的对象关联起来。所有中间和目标上下文都必须已经存在。如果 attrs 为 null，则此方法等效于 Context.createSubcontext()。

参数：

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

attrs - 要与新创建的上下文关联的属性

返回：

新创建的上下文

抛出：

NameAlreadyBoundException - 如果已经绑定了名称

InvalidAttributesException - 如果 attrs 不包含创建所需要的所有强制属性

NamingException - 如果遇到命名异常

另请参见：

Context.createSubcontext(Name)

---

createSubcontext

DirContext createSubcontext(String name,
                            Attributes attrs)
                            throws NamingException

创建并绑定新的上下文及关联的属性。有关详细信息，请参阅 createSubcontext(Name, Attributes)。

参数：

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

attrs - 要与新创建的上下文关联的属性

返回：

新创建的上下文

抛出：

NameAlreadyBoundException - 如果已经绑定了名称

InvalidAttributesException - 如果 attrs 不包含创建所需要的所有强制属性

NamingException - 如果遇到命名异常

---

getSchema

DirContext getSchema(Name name)
                     throws NamingException

检索与命名对象关联的模式。模式描述一些关于名称空间的结构及其中所存储的属性的规则。模式指定可以被添加到目录中的对象类型、添加对象的位置，以及对象可以具有的强制和可选属性。模式的支持范围是特定于目录的。

此方法返回可用于命名对象的模式信息树的根。多个命名对象（或者甚至整个目录）可以共享同一个模式。

诸如模式树的结构和内容、修改模式树内容的权限以及对目录进行这种修改的效果等问题都与基础目录有关。

参数：

name - 模式要被检索的对象的名称

返回：

与上下文关联的模式；永远不为 null

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

---

getSchema

DirContext getSchema(String name)
                     throws NamingException

检索与命名对象关联的模式。有关详细信息，请参阅 getSchema(Name)。

参数：

name - 模式要被检索的对象的名称

返回：

与上下文关联的模式；永远不为 null

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

---

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name)
                                    throws NamingException

检索包含命名对象类定义的模式对象的上下文。

目录模式中存在的一种信息是类定义。“对象类”定义指定对象的类型 和对象必须/可以具有的属性（强制和可选）。注意，这里引用的术语“对象类”是指目录中而不是 Java 中的对象类。例如，如果命名对象是 "Person" 类的目录对象，则 getSchemaClassDefinition() 将返回 DirContext，它表示 "Person" 的（目录）对象类定义。

可以从对象类定义检索的信息与目录有关。

在 JNDI 1.2 之前，此方法返回表示命名对象类定义的单个模式对象。从 JNDI 1.2 开始，此方法返回包含所有命名对象类定义的 DirContext。

参数：

name - 对象类定义要被检索的对象的名称

返回：

包含命名对象的类定义的 DirContext；永远不为 null

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

---

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name)
                                    throws NamingException

检索包含命名对象类定义的模式对象的上下文。有关详细信息，请参阅 getSchemaClassDefinition(Name)。

参数：

name - 对象类定义要被检索的对象的名称

返回：

包含命名对象的类定义的 DirContext；永远不为 null

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

---

search

NamingEnumeration<SearchResult> search(Name name,
                                       Attributes matchingAttributes,
                                       String[] attributesToReturn)
                                       throws NamingException

在单个上下文中搜索包含指定属性集的对象，并检索选定的属性。使用默认的 SearchControls 设置进行搜索。

对于要选择的对象，matchingAttributes 中的每个属性都必须与对象的某个属性匹配。如果 matchingAttributes 为空或 null，则返回目标上下文中的所有对象。

如果 matchingAttributes 中的属性 A₁ 和对象的属性 A₂ 具有相同的标识符并且 A₁ 中的每个值都与 A₂ 的某个值相等，则认为 A₁ 与 A₂ 匹配。这意味着值的顺序无关紧要，并且 A₂ 可以包含 A₁ 没有的“额外”值，这些值对比较没有影响。它还意味着如果 A₁ 没有值，则测试是否匹配等效于测试是否存在具有相同标识符的属性 A₂。

在比较属性值时使用的“相等性”的精确定义由基础目录服务定义。例如，它可能使用 Object.equals 方法或某种模式来指定不同的相等性操作。对于基于操作而非相等性的匹配（如子字符串比较），需要使用带有过滤器参数的 search 方法。

当对此 DirContext 作出更改时，对以前调用此方法返回的枚举的影响是不确定的。

如果对象没有指定的属性，则目录将忽略不存在的属性，并返回那些对象所具有的请求属性。

目录返回的属性可能多于请求（请参阅类描述中的属性类型名称），但不允许返回任意的、无关的属性。

另请参阅类描述中的操作属性。

参数：

name - 要搜索的上下文的名称

matchingAttributes - 要搜索的属性。如果为空或 null，则返回目标上下文中的所有对象。

attributesToReturn - 要返回的属性。null 指示要返回所有属性；空数组指示不返回任何属性。

返回：

SearchResult 对象的非 null 枚举。每个 SearchResult 都包含 attributesToReturn 所标识的属性和相应对象的名称，该名称相对于 name 指定的上下文命名。

抛出：

NamingException - 如果遇到命名异常

另请参见：

SearchControls, SearchResult, search(Name, String, Object[], SearchControls)

---

search

NamingEnumeration<SearchResult> search(String name,
                                       Attributes matchingAttributes,
                                       String[] attributesToReturn)
                                       throws NamingException

在单个上下文中搜索包含指定属性集的对象，并检索选定的属性。有关详细信息，请参阅 search(Name, Attributes, String[])。

参数：

name - 要搜索的上下文的名称

matchingAttributes - 要搜索的属性

attributesToReturn - 要返回的属性

返回：

SearchResult 对象的非 null 枚举

抛出：

NamingException - 如果遇到命名异常

---

search

NamingEnumeration<SearchResult> search(Name name,
                                       Attributes matchingAttributes)
                                       throws NamingException

在单个上下文中搜索包含指定属性集的对象。此方法返回这些对象的所有属性。这等效于向方法 search(Name, Attributes, String[]) 提供 null 作为 atributesToReturn 参数。
有关详细信息，请参阅 search(Name, Attributes, String[])。

参数：

name - 要搜索的上下文的名称

matchingAttributes - 要搜索的属性

返回：

SearchResult 对象的枚举

抛出：

NamingException - 如果遇到命名异常

另请参见：

search(Name, Attributes, String[])

---

search

NamingEnumeration<SearchResult> search(String name,
                                       Attributes matchingAttributes)
                                       throws NamingException

在单个上下文中搜索包含指定属性集的对象。有关详细信息，请参阅 search(Name, Attributes)。

参数：

name - 要搜索的上下文的名称

matchingAttributes - 要搜索的属性

返回：

SearchResult 对象的枚举

抛出：

NamingException - 如果遇到命名异常

---

search

NamingEnumeration<SearchResult> search(Name name,
                                       String filter,
                                       SearchControls cons)
                                       throws NamingException

在命名上下文或对象中搜索符合给定搜索过滤器的项。按照搜索控件的指定执行搜索。

filter 的格式和解释遵从 RFC 2254，其中对 RFC 中提及的 attr 和 value 解释如下。

attr 为属性的标识符。

value 为属性值的字符串表示形式。如何将此字符串表示形式转换为属性值是特定于目录的。

例如，对于声明 "someCount=127"，attr 为 "someCount"，value 为 "127"。提供程序根据属性 ID ("someCount")（可能还有其模式）确定属性值是否为整数。然后它适当地解析字符串 "127"。

应该使用适当的 Java (Unicode) 字符表示过滤器字符串中的所有非 ASCII 字符，不能将其编码为 UTF-8 八位组。或者，也可以使用 RFC 2254 中描述的“十六进制编码的反斜杠（backslash-hexcode）”符号。

如果目录不支持部分或全部其属性的字符串表示形式，则可以使用过滤器参数的形式为 Object 的 search 方法。然后，这种目录的服务提供程序会将过滤器参数转换为其特定于服务的表示形式，以供过滤器计算使用。请参阅 search(Name, String, Object[], SearchControls)。

RFC 2254 为过滤器定义了某些操作符，包括子字符串匹配、相等性、近似匹配、大于、小于。这些操作符被映射到基础目录中具有相应语义的操作符。例如，对于相等操作符，假定目录具有匹配的规则来定义过滤器中属性的“相等性”。则此规则将用于检查滤器中指定的属性与目录中的对象属性的相等性。类似地，如果目录具有用于排序的匹配规则，则此规则将用于进行“大于”和“小于”比较。

并不是 RFC 2254 中定义的所有操作符都可用于所有属性。当操作符不可用时，抛出异常 InvalidSearchFilterException。

结果返回在 SearchResult 的枚举中。每个 SearchResult 都包含对象名和关于该对象的其他信息（请参阅 SearchResult）。名称或者相对于搜索的目标上下文（由 name 参数命名），或者为 URL 字符串。如果目标上下文包括在枚举（这可能发生在 cons 指定 SearchControls.OBJECT_SCOPE 或 SearchControls.SUBSTREE_SCOPE 的搜索范围时）中，则其名称为空字符串。SearchResult 还可能包含匹配对象的属性，如果 cons 参数指定返回该属性的话。

如果对象不具有请求的属性，则忽略不存在的属性。仅返回那些对象具有的请求的属性。

目录返回的属性可能多于请求（请参阅类描述中的属性类型名称），但是不允许返回任意的、无关的属性。

另请参阅类描述中的操作属性。

参数：

name - 要搜索的上下文或对象的名称

filter - 要用于搜索的过滤器表达式；不能为 null

cons - 控制搜索的搜索控件。如果为 null，则使用默认的搜索控件（等效于 (new SearchControls())）。

返回：

符合过滤器的对象的 SearchResult 所组成的枚举；永远不为 null

抛出：

InvalidSearchFilterException - 如果基础目录不支持或者不理解指定的搜索过滤器

InvalidSearchControlsException - 如果搜索控件包含无效的设置

NamingException - 如果遇到命名异常

另请参见：

search(Name, String, Object[], SearchControls), SearchControls, SearchResult

---

search

NamingEnumeration<SearchResult> search(String name,
                                       String filter,
                                       SearchControls cons)
                                       throws NamingException

在命名上下文或对象中搜索符合给定搜索过滤器的项。按照搜索控件的指定执行搜索。有关详细信息，请参见 search(Name, String, SearchControls)。

参数：

name - 要搜索的上下文或对象的名称

filter - 要用于搜索的过滤器表达式；不能为 null

cons - 控制搜索的搜索控件。如果为 null，则使用默认的搜索控件（等效于 (new SearchControls())）。

返回：

符合过滤器的对象的 SearchResult 所组成的枚举。

抛出：

InvalidSearchFilterException - 如果基础目录不支持或者不理解指定的搜索过滤器

InvalidSearchControlsException - 如果搜索控件包含无效的设置

NamingException - 如果遇到命名异常

---

search

NamingEnumeration<SearchResult> search(Name name,
                                       String filterExpr,
                                       Object[] filterArgs,
                                       SearchControls cons)
                                       throws NamingException

在命名上下文或对象中搜索符合给定搜索过滤器的项。按照搜索控件的指定执行搜索。

filterExpr 的解释基于 RFC 2254。它可能还包含形式为 {i}（其中 i 为整数）的变量，这些变量引用 filterArgs 数组中的对象。否则，filterExpr 的解释等同于对方法 search(Name, String, SearchControls) 的 filter 参数的解释。

当变量 {i} 出现在搜索过滤器中时，它指示要在该位置使用过滤器参数 filterArgs[i]。只要生成的 attr、value 或 matchingrule 在 RFC 2254 第 4 节的过滤器语法中出现，这些变量就可以使用。当使用字符串值的过滤器参数替换变量时，过滤器被解释为好像给定了取代变量的字符串，同时根据 RFC 2254 的规则转义了过滤器中具有特殊意义的所有字符（如 '*'）。

对于部分或全部属性不使用的字符串表示形式的目录，对应于属性值的过滤器参数可能是 String 以外的类型。例如，支持非结构化二进制值属性的目录应该接受字节数组作为过滤器参数。任何其他类型的过滤器参数的解释（如果有）由该目录的服务提供程序确定，该服务提供程序将过滤器操作映射到基础目录中具有相应语义的操作上。

此方法返回结果的枚举。每个枚举元素都包含对象名和关于该对象的其他信息（请参阅 SearchResult）。名称或者相对于搜索的目标上下文（由 name 参数命名），或者为 URL 字符串。如果目标上下文包括在枚举（这可能发生在 cons 指定 SearchControls.OBJECT_SCOPE 或 SearchControls.SUBSTREE_SCOPE 的搜索范围时）中，则其名称为空字符串。

SearchResult 还可能包含匹配对象的属性，如果 cons 参数指定返回该属性的话。

如果对象不具有请求的属性，则忽略不存在的属性。仅返回那些对象具有的请求的属性。

目录返回的属性可能多于请求（请参阅类描述中的属性类型名称），但是不允许返回任意的、无关的属性。

如果为此方法提供带有无效变量替换项的搜索过滤器，则结果是不确定的。当对此 DirContext 作出更改时，对以前调用此方法返回的枚举的影响是不确定的。

另请参阅类描述中的操作属性。

参数：

name - 要搜索的上下文或对象的名称

filterExpr - 要用于搜索的过滤器表达式。表达式可能包含形式为 "{i}"（其中 i 为非负整数）的变量。不能为 null。

filterArgs - 要替换 filterExpr 中的变量的参数所组成的数组。filterArgs[i] 的值将取代每个出现的 "{i}"。如果为 null，则等效于空数组。

cons - 控制搜索的搜索控件。如果为 null，则使用默认的搜索控件（等效于 (new SearchControls())）。

返回：

符合过滤器的对象的 SearchResult 所组成的枚举；永远不为 null

抛出：

ArrayIndexOutOfBoundsException - 如果 filterExpr 包含 {i} 表达式，其中 i 在数组 filterArgs 的界限之外

InvalidSearchControlsException - 如果 cons 包含无效设置

InvalidSearchFilterException - 如果带有 filterArgs 的 filterExpr 表示无效的搜索过滤器

NamingException - 如果遇到命名异常

另请参见：

search(Name, Attributes, String[]), MessageFormat

---

search

NamingEnumeration<SearchResult> search(String name,
                                       String filterExpr,
                                       Object[] filterArgs,
                                       SearchControls cons)
                                       throws NamingException

在命名上下文或对象中搜索符合给定搜索过滤器的项。按照搜索控件的指定执行搜索。有关详细信息，请参见 search(Name, String, Object[], SearchControls)。

参数：

name - 要搜索的上下文或对象的名称

filterExpr - 要用于搜索的过滤器表达式。表达式可能包含形式为 "{i}"（其中 i 为非负整数）的变量。不能为 null。

filterArgs - 要替换 filterExpr 中的变量的参数所组成的数组。filterArgs[i] 的值将取代每个出现的 "{i}"。如果为 null，则等效于空数组。

cons - 控制搜索的搜索控件。如果为 null，则使用默认的搜索控件（等效于 (new SearchControls())）。

返回：

符合过滤器的对象的 SearchResult 所组成的枚举；永远不为 null

抛出：

ArrayIndexOutOfBoundsException - 如果 filterExpr 包含 {i} 表达式，其中 i 在数组 filterArgs 的界限之外

InvalidSearchControlsException - 如果 cons 包含无效设置

InvalidSearchFilterException - 如果带有 filterArgs 的 filterExpr 表示无效的搜索过滤器

NamingException - 如果遇到命名异常

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。