compact3

javax.naming.directory

Interface DirContext

All Superinterfaces:

Context

All Known Subinterfaces:

EventDirContext ， LdapContext

所有已知实现类：

InitialDirContext ， InitialLdapContext

public interface DirContext
extends Context

目录服务界面，包含检查和更新与对象关联的属性以及搜索目录的方法。

名字

传递给DirContext方法的参数的每个名称都是相对于该上下文。 空的名称用于命名上下文本身。 name参数可能永远不为null。

大多数方法都有超载版本，一个使用Name参数，一个采用String 。 这些重载版本是等效的，因为如果Name和String参数只是相同名称的不同表示，那么相同方法的重载版本的行为相同。 在下面的方法描述中，仅记录一个版本。 第二个版本代替了第一个链接：相同的文档适用于两者。

有关对Context方法的名称参数的解释的讨论，请参阅Context 。 这些相同的规则适用于DirContext方法的name参数。

属性模型

有两个基本模型应该与什么属性相关联。 首先，属性可以直接与DirContext对象相关联。 在这个模型中，命名对象的属性操作大致等同于对名称（返回DirContext对象）的查找，后跟在调用者提供空名称的DirContext对象上调用的属性操作。 可以将属性视为与对象一起存储（请注意，这并不意味着实现必须这样做）。

第二个模型是属性与DirContext中的名称（通常是原子名称）相关联。 在该模型中，命名对象的属性操作大致等同于对命名对象的父DirContext的名称进行查找，后跟在调用者提供终端原子名称的父级上调用的属性操作。 属性可以被视为存储在父DirContext中（同样，这并不意味着实现必须这样做）。 不是DirContexts的对象可以具有属性，只要他们的父母是DirContexts。

JNDI支持这两种模式。 各个服务提供商决定在哪里“存储”属性。 如果对象的属性被存储为对象的一部分，或存储在父对象中并与对象的名称相关联，那么JNDI客户端是最安全的。

属性类型名称

在getAttributes()和search()方法中，您可以通过提供属性名称（字符串）列表来提供要返回的属性。 您返回的属性可能不具有与您指定的属性名称相同的名称。 这是因为某些目录支持使其返回其他属性的功能。 这些功能包括属性子类，属性名称同义词和属性语言代码。

在属性子类化中，属性在类层次结构中定义。 在某些目录中，例如，“name”属性可能是所有名称相关属性的超类，包括“commonName”和“surName”。 要求“name”属性可能会返回“commonName”和“surName”属性。

使用属性类型同义词，一个目录可以为同一属性分配多个名称。 例如，“cn”和“commonName”可能都指向相同的属性。 要求“cn”可能会返回“commonName”属性。

一些目录支持属性的语言代码。 例如，要求“description”属性的目录可能会返回以下所有属性：

• 描述
• 描述; lang-en
• 描述;兰德
• 描述; lang-fr

操作属性

某些目录具有“操作属性”的概念，这是与管理目的的目录对象相关联的属性。 操作属性的示例是对象的访问控制列表。

在getAttributes()和search()方法中，您可以指定与请求的对象相关联的所有属性由供应null返回作为要返回的属性列表。 返回的属性不包括操作属性。 为了检索操作属性，您必须明确命名它们。

命名上下文

名称必须解析为上下文的某些方法（例如，在搜索单一级别的上下文时）。 这些方法的文档使用名为context的术语来描述其名称参数。 对于这些方法，如果命名对象不是DirContext，则抛出NotContextException 。 除了这些方法，不需要将命名对象作为DirContext。

参数

作为参数传递给任何方法的Attributes，SearchControls，或阵列对象不会由服务提供者进行修改。 服务提供商可以在操作期间保留对其的引用，包括方法结果的任何枚举以及生成的任何引用的处理。 呼叫者在此期间不应修改对象。 由任何方法返回的Attributes对象由调用者拥有。 呼叫者可以随后修改它; 服务提供商不会。

例外

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

从以下版本开始：

1.3

另请参见：

Context

Field Summary

Fields

Modifier and Type	Field and Description
static int	ADD_ATTRIBUTE 此常数指定添加具有指定值的属性。
static int	REMOVE_ATTRIBUTE 该常量指定从属性中删除指定的属性值。
static int	REPLACE_ATTRIBUTE 该常数指定用指定值替换属性。

Fields inherited from interface 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

方法摘要

Modifier and Type	Method and Description
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) 在命名的上下文或对象中搜索满足给定搜索过滤器的条目。

Methods inherited from interface 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) ， Constant Field Values

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE

该常数指定用指定值替换属性。

如果属性已存在，则使用新的指定值替换所有现有值。 如果属性不存在，创建它。 如果未指定值，则删除属性的所有值。 如果属性需要至少有一个值，则删除最后一个值将删除该属性。 如果尝试向单值属性添加多个值，则抛出InvalidAttributeValueException 。

该常数的值为2 。

另请参见：

ModificationItem ， modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes) ， Constant Field Values

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE

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

所得到的属性具有其先前值集合和指定值集合的设置差异。 如果未指定值，则删除整个属性。 如果属性不存在，或者指定值集合的某些或所有成员不存在，则该缺失可能会被忽略，并且操作成功，或者可能会抛出NamingException以指示缺少。 如果属性需要至少有一个值，则删除最后一个值将删除该属性。

该常数的值为3 。

另请参见：

ModificationItem ， modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes) ， Constant Field Values

方法详细信息

getAttributes

Attributes getAttributes(Name name)
                  throws NamingException

检索与命名对象关联的所有属性。 请参阅有关属性模型，属性类型名称和操作属性的类描述。

参数

name - 从中检索属性的对象的名称

结果

与name相关联的一组name 。 如果name没有属性，返回一个空属性集; 从不为空。

异常

NamingException - 如果遇到命名异常

另请参见：

getAttributes(String) ， getAttributes(Name, String[])

getAttributes

Attributes getAttributes(String name)
                  throws NamingException

检索与命名对象关联的所有属性。 详见getAttributes(Name) 。

参数

name - 从中检索属性的对象的名称

结果

与name相关联的一组 name

异常

NamingException - 如果遇到命名异常

getAttributes

Attributes getAttributes(Name name,
                         String[] attrIds)
                  throws NamingException

检索与命名对象关联的所选属性。 请参阅有关属性模型，属性类型名称和操作属性的类描述。

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

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

请参阅类描述也操作属性 。

参数

name - 从中检索属性的对象的名称

attrIds - 要检索的属性的标识符。 null表示应检索所有属性; 一个空数组表示不应该检索。

结果

请求的属性; 从不为空

异常

NamingException - 如果遇到命名异常

getAttributes

Attributes getAttributes(String name,
                         String[] attrIds)
                  throws NamingException

检索与命名对象关联的所选属性。 详见getAttributes(Name, String[]) 。

参数

name - 从中检索属性的对象的名称

attrIds - 要检索的属性的标识符。 null表示应检索所有属性; 一个空数组表示不应该检索。

结果

请求的属性; 从不为空

异常

NamingException - 如果遇到命名异常

modifyAttributes

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

修改与命名对象关联的属性。 未指定修改的顺序。 在可能的情况下，修改以原子方式执行。

参数

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

mod_op -修改操作的一个： ADD_ATTRIBUTE ， REPLACE_ATTRIBUTE ， REMOVE_ATTRIBUTE 。

attrs - 用于修改的属性; 可能不为空

异常

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 - 用于修改的属性; 可能不为空

异常

AttributeModificationException - 如果修改无法成功完成

NamingException - 如果遇到命名异常

modifyAttributes

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

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

参数

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

mods - 要执行的有序修改序列; 可能不为空

异常

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

NamingException - 如果遇到命名异常

另请参见：

modifyAttributes(Name, int, Attributes) ， ModificationItem

modifyAttributes

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

使用有序的修改列表修改与命名对象关联的属性。 详见modifyAttributes(Name, ModificationItem[]) 。

参数

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

mods - 要执行的有序修改序列; 可能不为空

异常

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

NamingException - 如果遇到命名异常

bind

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

将名称绑定到对象，以及关联的属性。 如果attrs为null，则所得绑定将具有与obj相关的属性，如果obj是DirContext，否则没有属性。 如果attrs为非空值，则结果绑定将具有attrs作为其属性; 与obj关联的任何属性将被忽略。

参数

name - 要绑定的名称 可能不是空的

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

attrs - 与绑定关联的属性

异常

NameAlreadyBoundException - 如果名称已经绑定

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 - 如果名称已经绑定

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

NamingException - 如果遇到命名异常

rebind

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

将名称绑定到对象以及关联的属性，覆盖任何现有绑定。 如果attrs为空， obj为DirContext ，则使用obj的属性 。 如果attrs为空且obj不是DirContext ，则与已经绑定在目录中的对象相关联的任何现有属性保持不变。 如果attrs不为null，在目录已经绑定的对象关联的所有现有属性被删除，attrs与命名对象关联。 如果obj是DirContext ，并且attrs是非空的，那么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为空，则此方法相当于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 - 要检索其模式的对象的名称

结果

与上下文相关联的模式; 从不为空

异常

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchema

DirContext getSchema(String name)
              throws NamingException

检索与命名对象关联的模式。 详情请见getSchema(Name) 。

参数

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

结果

与上下文相关联的模式; 从不为空

异常

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name)
                             throws NamingException

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

目录模式中找到的一类信息是类定义 。 “对象类”定义指定对象的类型以及对象必须/可以具有的属性（强制和可选）。 请注意，这里所指的术语“对象类”在目录中是以Java的方式而不是目录。 例如，如果命名对象是“Person”类的目录对象， 那么getSchemaClassDefinition()将返回一个DirContext，表示（目录）的对象类定义“Person”。

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

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

参数

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

结果

该DirContext包含命名对象的类定义; 从不为空

异常

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name)
                             throws NamingException

检索包含命名对象的类定义的模式对象的上下文。 详见getSchemaClassDefinition(Name) 。

参数

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

结果

该DirContext包含命名对象的类定义; 从不为空

异常

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

search

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

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

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

在属性A ₁ matchingAttributes被认为是匹配的属性A ₂的物体的，如果A ₁和A ₂具有相同的标识符，和A ₁的每个值等于A ₂的某个值。 这意味着值的顺序不重要，并且A ₂可能包含在A _1中找不到的“额外”值，而不影响比较。 这也意味着如果A ₁没有值，则匹配的测试等同于测试具有相同标识符的属性A ₂的存在。

用于比较属性值的“等同”的精确定义由底层目录服务定义。 例如，它可能使用Object.equals方法，或者可能使用模式来指定不同的相等操作。 对于基于除等于的操作（如子串比较）进行匹配，请使用采用过滤器参数的版本search 。

当对此DirContext进行更改时，对此方法的以前调用返回的对枚举的影响是未定义的。

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

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

请参阅类描述也操作属性 。

参数

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

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

attributesToReturn - 要返回的属性。 null表示要返回的所有属性; 一个空数组表示不返回任何数组。

结果

SearchResult对象的非空枚举。 每个SearchResult包含由attributesToReturn标识的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对象的非空枚举

异常

NamingException - 如果遇到命名异常

search

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

在单个上下文中搜索包含指定属性集的对象。 此方法返回此类对象的所有属性。 它相当于将atributesToReturn参数提供给方法search(Name, Attributes, String[]) 。
见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，解释如下attr和value RFC中提及。

attr是属性的标识符。

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

对于断言“someCount = 127”，例如， attr是“someCount”， value是“127”。 提供者根据属性ID（“someCount”）（以及可能的模式）确定属性的值是整数。 然后适当地解析字符串“127”。

过滤器字符串中的任何非ASCII字符都应由适当的Java（Unicode）字符表示，而不是以UTF-8字节编码。 或者，可以使用RFC 2254中描述的“反斜杠十六进制”符号。

如果目录不支持部分或全部其属性的字符串表示的形式search接受在对象的形式过滤器参数可以用来代替。 然后，这样一个目录的服务提供商将把过滤器参数转换成用于过滤器评估的服务特定表示。 见search(Name, String, Object[], SearchControls) 。

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

并非RFC 2254中定义的所有运算符都适用于所有属性。 当操作员不适用时，抛出异常InvalidSearchFilterException 。

结果以枚举SearchResult s的形式返回。 每个SearchResult包含对象的名称和有关对象的其他信息（请参阅SearchResult）。 该名称是相对于搜索的目标上下文（由name参数命名的），或者它是一个URL字符串。 如果目标上下文包括在枚举（如可能时cons指定的检索范围SearchControls.OBJECT_SCOPE或SearchControls.SUBSTREE_SCOPE ），其名称为空字符串。 SearchResult也可以包含匹配对象的属性，如果cons参数指定返回属性。

如果对象没有请求的属性，则该不存在的属性将被忽略。 将返回对象确实拥有的那些请求的属性。

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

请参阅类描述也操作属性 。

参数

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

filter - 用于搜索的过滤器表达式; 可能不为空

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

结果

枚举满足过滤器的对象的SearchResult s; 从不为空

异常

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 - 用于搜索的过滤器表达式; 可能不为空

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

结果

枚举满足过滤器的对象为 SearchResult s。

异常

InvalidSearchFilterException - 如果指定的搜索过滤器不被底层目录支持或理解

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

NamingException - 如果遇到命名异常

search

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

在命名的上下文或对象中搜索满足给定搜索过滤器的条目。 按照搜索控件的指定执行搜索。

filterExpr的filterExpr基于RFC 2254.它还可以包含{i}格式的{i} ，其中i是一个整数，它引用了filterArgs数组中的对象。 filterExpr的filterExpr与方法search(Name, String, SearchControls)的filter参数的search(Name, String, SearchControls) 。

当变量{i}出现在搜索过滤器中时，表示在该位置使用过滤器参数filterArgs[i] 。 在RFC 2254第4节的过滤器语法中出现attr ， value或matchingrule生产的任何地方都可以使用这些变量。当一个字符串值过滤器参数代替一个变量时，过滤器被解释为：变量的位置，具有根据RFC 2254的规则被转义的过滤器（如'*' ）中具有特殊意义的任何字符。

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

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

SearchResult也可以包含匹配对象的属性，如果cons参数指定返回属性。

如果对象没有请求的属性，则该不存在的属性将被忽略。 将返回对象确实拥有的那些请求的属性。

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

如果为此方法提供了带有无效变量替换的搜索过滤器，则结果未定义。 当对此DirContext进行更改时，对此方法的先前调用返回的对枚举的影响是未定义的。

请参阅类描述也操作属性 。

参数

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

filterExpr - 用于搜索的过滤器表达式。 该表达式可能包含“ {i} ”形式的{i} ，其中i是非负整数。 可能不为空

filterArgs - 在filterExpr中替换变量的参数filterExpr 。 filterArgs[i]的值将代替每次出现的“ {i} ”。 如果为空，则相当于一个空数组。

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

结果

枚举满足过滤器的对象的SearchResult s; 从不为空

异常

ArrayIndexOutOfBoundsException - 如果 filterExpr包含 {i}表达式，其中 i位于数组边界之外 filterArgs

InvalidSearchControlsException - 如果 cons包含无效设置

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

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} ，其中i是非负整数。 可能不为空

filterArgs - 在filterExpr中替换变量的参数filterExpr 。 filterArgs[i]的值将取代每一次“ {i} ”。 如果为空，则相当于一个空数组。

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

结果

枚举满足过滤器的对象的SearchResult s; 从不为空

异常

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

InvalidSearchControlsException - 如果 cons包含无效设置

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

NamingException - 如果遇到命名异常