-
- 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
方法的名称参数。属性模型
有两个基本模型应该与什么属性相关联。 首先,属性可以直接与DirContext对象相关联。 在这个模型中,命名对象的属性操作大致等同于对名称(返回DirContext对象)的查找,后跟在调用者提供空名称的DirContext对象上调用的属性操作。 可以将属性视为与对象一起存储(请注意,这并不意味着实现必须这样做)。第二个模型是属性与DirContext中的名称(通常是原子名称)相关联。 在该模型中,命名对象的属性操作大致等同于对命名对象的父DirContext的名称进行查找,后跟在调用者提供终端原子名称的父级上调用的属性操作。 属性可以被视为存储在父DirContext中(同样,这并不意味着实现必须这样做)。 不是DirContexts的对象可以具有属性,只要他们的父母是DirContexts。
JNDI支持这两种模式。 各个服务提供商决定在哪里“存储”属性。 如果对象的属性被存储为对象的一部分,或存储在父对象中并与对象的名称相关联,那么JNDI客户端是最安全的。
属性类型名称
在getAttributes()
和search()
方法中,您可以通过提供属性名称(字符串)的列表来提供要返回的属性。 您返回的属性可能不具有与您指定的属性名称相同的名称。 这是因为某些目录支持使其返回其他属性的功能。 这些功能包括属性子类化,属性名称同义词和属性语言代码。在属性子类化中,属性在类层次结构中定义。 在某些目录中,例如,“name”属性可能是所有名称相关属性的超类,包括“commonName”和“surName”。 要求“name”属性可能会返回“commonName”和“surName”属性。
使用属性类型同义词,一个目录可以为同一属性分配多个名称。 例如,“cn”和“commonName”可能都指向相同的属性。 要求“cn”可能会返回“commonName”属性。
一些目录支持属性的语言代码。 例如,要求“description”属性的目录可能会返回以下所有属性:
- 描述
- 描述;朗烯
- 描述;朗德
- 描述;朗-fr的
操作属性
某些目录具有“操作属性”的概念,这是与管理目的的目录对象相关联的属性。 操作属性的示例是对象的访问控制列表。
在
getAttributes()
和search()
方法中,您可以指定与请求的对象相关联的所有属性由供应商null
作为要返回的属性列表返回。 返回的属性不包括操作属性。 为了检索操作属性,您必须明确命名它们。命名上下文
名称必须解析为上下文的某些方法(例如,在搜索单一级别的上下文时)。 这些方法的文档使用名为context的术语来描述其名称参数。 对于这些方法,如果命名对象不是DirContext,则抛出
NotContextException
。 除了这些方法,不需要将命名对象设为DirContext。参数
一个
Attributes
,SearchControls
作为参数传递给任何方法,或阵列对象不会由服务提供者进行修改。 服务提供商可以在操作期间保留对其的引用,包括方法结果的任何枚举以及生成的任何引用的处理。 呼叫者在此期间不应修改对象。 由任何方法返回的一个Attributes
对象由调用者拥有。 呼叫者可以随后修改它; 服务提供商不会。例外
此接口中的所有方法都可能会抛出NamingException或其任何子类。 有关每个异常的详细信息,请参阅NamingException及其子类。
- 从以下版本开始:
- 1.3
- 另请参见:
-
Context
-
-
Field Summary
Fields Modifier and Type Field 描述 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 方法 描述 void
bind(String name, Object obj, Attributes attrs)
将名称绑定到对象,以及关联的属性。void
bind(Name name, Object obj, Attributes attrs)
将名称绑定到对象,以及关联的属性。DirContext
createSubcontext(String name, Attributes attrs)
创建和绑定新的上下文以及关联的属性。DirContext
createSubcontext(Name name, Attributes attrs)
创建和绑定新的上下文以及关联的属性。Attributes
getAttributes(String name)
检索与命名对象关联的所有属性。Attributes
getAttributes(String name, String[] attrIds)
检索与命名对象关联的所选属性。Attributes
getAttributes(Name name)
检索与命名对象关联的所有属性。Attributes
getAttributes(Name name, String[] attrIds)
检索与命名对象关联的所选属性。DirContext
getSchema(String name)
检索与命名对象关联的模式。DirContext
getSchema(Name name)
检索与命名对象关联的模式。DirContext
getSchemaClassDefinition(String name)
检索包含命名对象的类定义的模式对象的上下文。DirContext
getSchemaClassDefinition(Name name)
检索包含命名对象的类定义的模式对象的上下文。void
modifyAttributes(String name, int mod_op, Attributes attrs)
修改与命名对象关联的属性。void
modifyAttributes(String name, ModificationItem[] mods)
使用有序的修改列表修改与命名对象关联的属性。void
modifyAttributes(Name name, int mod_op, Attributes attrs)
修改与命名对象关联的属性。void
modifyAttributes(Name name, ModificationItem[] mods)
使用有序的修改列表修改与命名对象关联的属性。void
rebind(String name, Object obj, Attributes attrs)
将名称绑定到对象以及关联的属性,覆盖任何现有绑定。void
rebind(Name name, Object obj, Attributes attrs)
将名称绑定到对象以及关联的属性,覆盖任何现有绑定。NamingEnumeration<SearchResult>
search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)
在命名的上下文或对象中搜索满足给定搜索过滤器的条目。NamingEnumeration<SearchResult>
search(String name, String filter, SearchControls cons)
在命名的上下文或对象中搜索满足给定搜索过滤器的条目。NamingEnumeration<SearchResult>
search(String name, Attributes matchingAttributes)
在单个上下文中搜索包含指定属性集的对象。NamingEnumeration<SearchResult>
search(String 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(Name name, Attributes matchingAttributes)
在单个上下文中搜索包含指定属性集的对象。NamingEnumeration<SearchResult>
search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
在单个上下文中搜索包含指定属性集的对象,并检索所选属性。-
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
。
-
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
相关的属性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
不为空,则与目标中已绑定的对象关联的任何现有属性都将被删除,并且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
为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
- 要检索其模式的对象的名称 - 结果
- 与上下文相关联的模式; 从不为空
- 异常
-
OperationNotSupportedException
- 如果不支持模式 -
NamingException
- 如果遇到命名异常
-
getSchema
DirContext getSchema(String name) throws NamingException
检索与命名对象关联的模式。 详见getSchema(Name)
。- 参数
-
name
- 要检索其模式的对象的名称 - 结果
- 与上下文相关联的模式; 从不为空
- 异常
-
OperationNotSupportedException
- 如果不支持模式 -
NamingException
- 如果遇到命名异常
-
getSchemaClassDefinition
DirContext getSchemaClassDefinition(Name name) throws NamingException
检索包含命名对象的类定义的模式对象的上下文。目录模式中找到的一类信息是类定义 。 “对象类”定义指定对象的类型以及对象必须/可以具有的属性(强制和可选)。 请注意,这里所指的术语“对象类”在目录中而不是Java意义上。 例如,如果命名对象是“Person”类的目录对象,
getSchemaClassDefinition()
将返回一个表示“目录”对象类定义的“Person”的DirContext
。可以从对象类定义检索的信息与目录相关。
在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
为空或为null,则返回目标上下文中的所有对象。如果A 1和A 2具有相同的标识符,则
matchingAttributes
的属性A 1被认为与对象的属性A 2相匹配,并且A 1的每个值等于A 2的某个值。 这意味着值的顺序不重要,并且A 2可能包含在A 1中找不到的“额外”值,而不影响比较。 这也意味着如果A 1没有值,则匹配的测试等同于测试具有相同标识符的属性A 2的存在。用于比较属性值的“等同”的精确定义由底层目录服务定义。 例如,它可能使用
Object.equals
方法,或者可能使用模式来指定不同的相等运算。 对于基于除等于的操作(如子串比较)进行search
,请使用采用过滤器参数的search
方法的版本。当对此
DirContext
进行更改时,对此方法的以前调用返回的对枚举的影响是未定义的。如果对象没有指定属性,该目录将忽略不存在的属性,并返回对象所具有的请求属性。
目录可能会返回比所请求的更多属性(请参阅类描述中的属性类型名称 ),但不允许返回任意的,不相关的属性。
请参阅类描述中的操作属性 。
- 参数
-
name
- 要搜索的上下文的名称 -
matchingAttributes
- 要搜索的属性。 如果为空,则返回目标上下文中的所有对象。 -
attributesToReturn
- 要返回的属性。 null表示要返回的所有属性; 一个空数组表示不返回任何数组。 - 结果
-
SearchResult
对象的非空枚举。 每个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
对象 - 异常
-
NamingException
- 如果遇到命名异常
-
search
NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes) throws NamingException
在单个上下文中搜索包含指定属性集的对象。 此方法返回此类对象的所有属性。 这相当于将attributesToReturn
参数提供给方法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,对RFC中提及的attr
和value
进行了以下解释。attr
是属性的标识符。value
是属性值的字符串表示形式。 将此字符串表示形式转换为属性值是特定于目录的。对于断言“someCount = 127”,例如,
attr
是“someCount”,而value
是“127”。 提供者根据属性ID(“someCount”)(以及可能的模式)确定属性的值是整数。 然后适当地解析字符串“127”。过滤器字符串中的任何非ASCII字符都应由适当的Java(Unicode)字符表示,而不是以UTF-8字节编码。 或者,可以使用RFC 2254中描述的“反斜杠十六进制”符号。
如果该目录不支持其某些或全部属性的字符串表示形式,则可以使用以Object形式接受过滤器参数的形式为
search
。 然后,这样一个目录的服务提供商将把过滤器参数转换成用于过滤器评估的服务特定表示。 参见search(Name, String, Object[], SearchControls)
。RFC 2254为过滤器定义了某些运算符,包括子串匹配,等式,近似匹配,大于,小于。 这些运算符映射到基础目录中具有相应语义的运算符。 例如,对于equals运算符,假设目录具有定义过滤器中属性“等于”的匹配规则。 该规则将用于检查过滤器中指定的属性与目录中对象属性的相等性。 类似地,如果目录具有用于排序的匹配规则,则该规则将用于进行“大于”和“小于”比较。
并非RFC 2254中定义的所有运算符都适用于所有属性。 当操作员不适用时,抛出异常
InvalidSearchFilterException
。结果以枚举
SearchResult
秒的形式返回。 每个SearchResult
包含对象的名称和有关对象的其他信息(请参阅SearchResult)。 该名称是相对于搜索的目标上下文(由name
参数命名的),或者它是一个URL字符串。 如果目标上下文包含在枚举中(如果cons
指定搜索范围为SearchControls.OBJECT_SCOPE
或SearchControls.SUBSTREE_SCOPE
),则其名称为空字符串。 如果cons
参数指定返回属性,则SearchResult
也可能包含匹配对象的属性。如果对象没有请求的属性,则该不存在的属性将被忽略。 将返回对象确实拥有的那些请求的属性。
目录可能会返回比所请求的更多属性(请参阅类描述中的属性类型名称 ),但不允许返回任意不相关的属性。
请参阅类描述中的操作属性 。
- 参数
-
name
- 要搜索的上下文或对象的名称 -
filter
- 用于搜索的过滤器表达式; 可能不为空 -
cons
- 控制搜索的搜索控件。 如果为空,则使用默认搜索控件(相当于(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
- 参数
-
name
- 要搜索的上下文或对象的名称 -
filter
- 用于搜索的过滤器表达式; 可能不为空 -
cons
- 控制搜索的搜索控件。 如果为空,则使用默认搜索控件(相当于(new SearchControls())
)。 - 结果
-
对满足过滤器的对象的枚举为
SearchResult
s。 - 异常
-
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]
。 在RFC 2254第4节的过滤器语法中出现attr , value或matchingrule生产的任何地方都可以使用这些变量。当一个字符串值过滤器参数代替一个变量时,过滤器被解释为:变量的位置,具有根据RFC 2254的规则被转义的过滤器(例如'*'
)中具有特殊意义的任何字符。对于不对某些或全部属性使用字符串表示形式的目录,与属性值相对应的过滤器参数可能不是String类型。 例如,支持非结构化二进制值属性的目录应该接受字节数组作为过滤器参数。 任何其他类型的过滤器参数的解释(如果有)由该目录的服务提供者确定,该服务提供者将过滤器操作映射到基础目录中具有相应语义的操作。
此方法返回结果的枚举。 枚举中的每个元素都包含对象的名称和有关对象的其他信息(参见
SearchResult
)。 该名称是相对于搜索的目标上下文(由name
参数命名的),或者它是一个URL字符串。 如果目标上下文包含在枚举中(cons
指定SearchControls.OBJECT_SCOPE
或SearchControls.SUBSTREE_SCOPE
的搜索范围是可能的),其名称为空字符串。如果
cons
参数指定返回属性,则SearchResult
也可能包含匹配对象的属性。如果对象没有请求的属性,则该不存在的属性将被忽略。 将返回对象确实拥有的那些请求的属性。
目录可能会返回比所请求的更多属性(请参阅类描述中的属性类型名称 ),但不允许返回任意不相关的属性。
如果为此方法提供了具有无效变量替换的搜索过滤器,则结果未定义。 当对此DirContext进行更改时,对此方法的先前调用返回的对枚举的影响是未定义的。
请参阅类描述中的操作属性 。
- 参数
-
name
- 要搜索的上下文或对象的名称 -
filterExpr
- 用于搜索的过滤器表达式。 该表达式可能包含“{i}
”形式的变量,其中i
是非负整数。 可能不为空 -
filterArgs
- 用于替换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
- 参数
-
name
- 要搜索的上下文或对象的名称 -
filterExpr
- 用于搜索的过滤器表达式。 该表达式可能包含“{i}
”形式的变量,其中i
是非负整数。 可能不为空 -
filterArgs
- 在filterExpr
替换变量的参数数组。filterArgs[i]
的值将代替每次出现的“{i}
”。 如果为空,则相当于一个空数组。 -
cons
- 控制搜索的搜索控件。 如果为null,则使用默认搜索控件(相当于(new SearchControls())
)。 - 结果
-
枚举满足过滤条件的物件
SearchResult
s; 从不为空 - 异常
-
ArrayIndexOutOfBoundsException
- 如果filterExpr
包含{i}
表达式,其中i
位于数组边界之外filterArgs
-
InvalidSearchControlsException
- 如果cons
包含无效设置 -
InvalidSearchFilterException
- 如果filterExpr
与filterArgs
表示无效的搜索过滤器 -
NamingException
- 如果遇到命名异常
-
-