javax.naming.directory
类 InitialDirContext

java.lang.Object
  javax.naming.InitialContext
      javax.naming.directory.InitialDirContext

所有已实现的接口：

Context, DirContext

直接已知子类：

InitialLdapContext

public class InitialDirContext
extends InitialContext
implements DirContext

此类是执行目录操作的初始上下文。InitialContext 的类描述中的文档（包括关于同步的那些文档）在此处同样适用。

从以下版本开始：

1.3

另请参见：

InitialContext

字段摘要

从类 javax.naming.InitialContext 继承的字段

defaultInitCtx, gotDefault, myProps

从接口 javax.naming.directory.DirContext 继承的字段

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, 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

构造方法摘要

	InitialDirContext() 构造一个初始 DirContext。
protected	InitialDirContext(boolean lazy) 构造一个具有不进行初始化的选项的初始 DirContext。
	InitialDirContext(Hashtable<?,?> environment) 使用所提供的环境构造一个初始 DirContext。

方法摘要

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.InitialContext 继承的方法

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

从接口 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

构造方法详细信息

InitialDirContext

protected InitialDirContext(boolean lazy)
                     throws NamingException

构造一个具有不进行初始化的选项的初始 DirContext。如果子类在调用 InitialDirContext 构造方法时仍然未知环境属性的值，则可以在其中使用此构造方法。子类的构造方法将调用此构造方法，计算环境的值，然后在返回之前调用 init()。

参数：

lazy - 为 true 表示不初始化该初始 DirContext；为 false 等效于调用 new InitialDirContext()

抛出：

NamingException - 如果遇到命名异常

从以下版本开始：

1.3

另请参见：

InitialContext.init(Hashtable)

InitialDirContext

public InitialDirContext()
                  throws NamingException

构造一个初始 DirContext。不提供环境属性。等效于 new InitialDirContext(null)。

抛出：

NamingException - 如果遇到命名异常

另请参见：

InitialDirContext(Hashtable)

InitialDirContext

public InitialDirContext(Hashtable<?,?> environment)
                  throws NamingException

使用所提供的环境构造一个初始 DirContext。环境属性已在 javax.naming.InitialContext 类描述中讨论。

此构造方法不会修改 environment 或保存一个对它的引用，但可能保存一个副本。

参数：

environment - 用于创建初始 DirContext 的环境。null 指示一个空环境。

抛出：

NamingException - 如果遇到命名异常

方法详细信息

getAttributes

public Attributes getAttributes(String name)
                         throws NamingException

从接口 DirContext 复制的描述

检索所有与命名对象关联的属性。有关详细信息，请参阅 DirContext.getAttributes(Name)。

指定者：

接口 DirContext 中的 getAttributes

参数：

name - 对象名，通过该对象名检索属性

返回：

与 name 关联的属性集

抛出：

NamingException - 如果遇到命名异常

getAttributes

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

从接口 DirContext 复制的描述

检索与命名对象关联的选定属性。有关详细信息，请参阅 DirContext.getAttributes(Name, String[])。

指定者：

接口 DirContext 中的 getAttributes

参数：

name - 对象名，通过该对象名检索属性

attrIds - 要检索的属性的标识符。null 指示应该检索所有属性；空数组指示不应检索任何属性。

返回：

请求的属性；永远不为 null

抛出：

NamingException - 如果遇到命名异常

getAttributes

public Attributes getAttributes(Name name)
                         throws NamingException

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 getAttributes

参数：

name - 对象名，通过该对象名检索属性

返回：

与 name 关联的属性集。如果名称没有属性，则返回空属性集；永远不为 null。

抛出：

NamingException - 如果遇到命名异常

另请参见：

DirContext.getAttributes(String), DirContext.getAttributes(Name, String[])

getAttributes

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

从接口 DirContext 复制的描述

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

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

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

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

指定者：

接口 DirContext 中的 getAttributes

参数：

name - 对象名，通过该对象名检索属性

attrIds - 要检索的属性的标识符。null 指示应该检索所有属性；空数组指示不应检索任何属性。

返回：

请求的属性；永远不为 null

抛出：

NamingException - 如果遇到命名异常

modifyAttributes

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 modifyAttributes

参数：

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

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

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

抛出：

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

NamingException - 如果遇到命名异常

modifyAttributes

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 modifyAttributes

参数：

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

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

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

抛出：

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

NamingException - 如果遇到命名异常

另请参见：

DirContext.modifyAttributes(Name, ModificationItem[])

modifyAttributes

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 modifyAttributes

参数：

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

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

抛出：

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

NamingException - 如果遇到命名异常

modifyAttributes

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 modifyAttributes

参数：

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

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

抛出：

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

NamingException - 如果遇到命名异常

另请参见：

DirContext.modifyAttributes(Name, int, Attributes), ModificationItem

bind

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 bind

参数：

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

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

attrs - 要与绑定关联的属性

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

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

NamingException - 如果遇到命名异常

bind

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 bind

参数：

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

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

attrs - 要与绑定关联的属性

抛出：

NameAlreadyBoundException - 如果已经绑定了 name

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

NamingException - 如果遇到命名异常

另请参见：

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

rebind

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 rebind

参数：

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

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

attrs - 要与绑定关联的属性

抛出：

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

NamingException - 如果遇到命名异常

rebind

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 rebind

参数：

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

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

attrs - 要与绑定关联的属性

抛出：

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

NamingException - 如果遇到命名异常

另请参见：

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

createSubcontext

public DirContext createSubcontext(String name,
                                   Attributes attrs)
                            throws NamingException

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 createSubcontext

参数：

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

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

返回：

新创建的上下文

抛出：

NameAlreadyBoundException - 如果已经绑定了名称

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

NamingException - 如果遇到命名异常

createSubcontext

public DirContext createSubcontext(Name name,
                                   Attributes attrs)
                            throws NamingException

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 createSubcontext

参数：

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

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

返回：

新创建的上下文

抛出：

NameAlreadyBoundException - 如果已经绑定了名称

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

NamingException - 如果遇到命名异常

另请参见：

Context.createSubcontext(Name)

getSchema

public DirContext getSchema(String name)
                     throws NamingException

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 getSchema

参数：

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

返回：

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

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchema

public DirContext getSchema(Name name)
                     throws NamingException

从接口 DirContext 复制的描述

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

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

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

指定者：

接口 DirContext 中的 getSchema

参数：

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

返回：

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

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(String name)
                                    throws NamingException

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 getSchemaClassDefinition

参数：

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

返回：

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

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(Name name)
                                    throws NamingException

从接口 DirContext 复制的描述

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

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

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

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

指定者：

接口 DirContext 中的 getSchemaClassDefinition

参数：

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

返回：

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

抛出：

OperationNotSupportedException - 如果不支持模式

NamingException - 如果遇到命名异常

search

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 search

参数：

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

matchingAttributes - 要搜索的属性

返回：

SearchResult 对象的枚举

抛出：

NamingException - 如果遇到命名异常

search

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 search

参数：

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

matchingAttributes - 要搜索的属性

返回：

SearchResult 对象的枚举

抛出：

NamingException - 如果遇到命名异常

另请参见：

DirContext.search(Name, Attributes, String[])

search

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 search

参数：

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

matchingAttributes - 要搜索的属性

attributesToReturn - 要返回的属性

返回：

SearchResult 对象的非 null 枚举

抛出：

NamingException - 如果遇到命名异常

search

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

从接口 DirContext 复制的描述

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

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

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

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

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

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

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

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

指定者：

接口 DirContext 中的 search

参数：

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

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

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

返回：

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

抛出：

NamingException - 如果遇到命名异常

另请参见：

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

search

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 search

参数：

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

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

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

返回：

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

抛出：

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

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

NamingException - 如果遇到命名异常

search

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

从接口 DirContext 复制的描述

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

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 参数指定返回该属性的话。

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

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

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

指定者：

接口 DirContext 中的 search

参数：

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

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

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

返回：

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

抛出：

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

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

NamingException - 如果遇到命名异常

另请参见：

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

search

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

从接口 DirContext 复制的描述

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

指定者：

接口 DirContext 中的 search

参数：

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

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

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

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

返回：

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

抛出：

InvalidSearchControlsException - 如果 cons 包含无效设置

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

NamingException - 如果遇到命名异常

search

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

从接口 DirContext 复制的描述

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

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 作出更改时，对以前调用此方法返回的枚举的影响是不确定的。

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

指定者：

接口 DirContext 中的 search

参数：

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

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

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

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

返回：

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

抛出：

InvalidSearchControlsException - 如果 cons 包含无效设置

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

NamingException - 如果遇到命名异常

另请参见：

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