模块  java.naming
软件包  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方法的name参数的解释的讨论，请参见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”属性的这样的目录可能会返回以下所有属性：

    • 描述
    • 描述;朗烯
    • 描述;朗德
    • 描述;朗-fr的

    操作属性

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

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

    命名上下文

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

    参数

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

    例外

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

    从以下版本开始：
    1.3
    另请参见：
    Context

    • 字段详细信息

      • 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关联的属性name 。 如果name没有属性，则返回空属性集; 永远不会。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        getAttributes(String) ， getAttributes(Name, String[])

      • 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 - 用于修改的属性; 可能不是null
        异常
        AttributeModificationException - 如果修改无法成功完成
        NamingException - 如果遇到命名异常
        另请参见：
        modifyAttributes(Name, ModificationItem[])

      • rebind

        void rebind​(Name name,
            Object obj,
            Attributes attrs)
     throws NamingException
        将名称绑定到对象以及相关属性，覆盖任何现有绑定。 如果attrs为null，并且obj是DirContext ，从属性obj使用。 如果attrs为空且obj不是DirContext ，则与已绑定在目录中的对象关联的任何现有属性保持不变。 如果attrs为非null，则删除与已绑定在目录中的对象关联的任何现有属性，并将attrs与命名对象关联。 如果obj是DirContext且attrs非空，则忽略obj的属性。
        参数
        name - 要绑定的名称; 可能不是空的
        obj - 要绑定的对象; 可能为空
        attrs - 与绑定关联的属性
        异常
        InvalidAttributesException - 如果未提供绑定的某些“强制”属性
        NamingException - 如果遇到命名异常
        另请参见：
        Context.bind(Name, Object) ， bind(Name, Object, Attributes)

      • createSubcontext

        DirContext createSubcontext​(Name name,
                            Attributes attrs)
                     throws NamingException
        创建并绑定新上下文以及相关属性。 此方法创建具有给定名称的新子上下文，将其绑定在目标上下文中（由名称的终端原子组件命名），并将提供的属性与新创建的对象相关联。 所有中间和目标上下文必须已存在。 如果attrs为null，则此方法等效于Context.createSubcontext() 。
        参数
        name - 要创建的上下文的名称; 可能不是空的
        attrs - 与新创建的上下文关联的属性
        结果
        新创建的上下文
        异常
        NameAlreadyBoundException - 如果名称已绑定
        InvalidAttributesException - 如果 attrs不包含创建所需的所有必需属性
        NamingException - 如果遇到命名异常
        另请参见：
        Context.createSubcontext(Name)

      • getSchema

        DirContext getSchema​(Name name)
              throws NamingException
        检索与命名对象关联的模式。 该模式描述了有关命名空间结构和存储在其中的属性的规则。 模式指定可以将哪些类型的对象添加到目录以及可以添加它们的位置; 对象可以具有哪些强制和可选属性。 模式的支持范围是特定于目录的。

        此方法返回适用于命名对象的架构信息树的根。 几个命名对象（甚至整个目录）可能共享相同的模式。

        诸如模式树的结构和内容，修改模式树内容的权限以及此类修改对目录的影响等问题取决于基础目录。

        参数
        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 - 如果遇到命名异常

      • search

        NamingEnumeration<SearchResult> search​(Name name,
                                       Attributes matchingAttributes,
                                       String[] attributesToReturn)
                                throws NamingException
        在单个上下文中搜索包含指定属性集的对象，并检索所选属性。 使用默认的SearchControls设置执行搜索。

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

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

        用于比较属性值的“相等”的精确定义由底层目录服务定义。 例如，它可能使用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​(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中描述的“反斜杠 - 十六进制”符号。

        如果目录不支持其部分或全部属性的字符串表示形式，则可以使用以对象形式接受过滤器参数的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 ），则其名称为空字符串。 如果cons参数指定返回属性，则SearchResult还可能包含匹配对象的属性。

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

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

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

        参数
        name - 要搜索的上下文或对象的名称
        filter - 用于搜索的过滤器表达式; 可能不是null
        cons - 控制搜索的搜索控件。 如果为null，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        满足过滤器的对象的SearchResult的枚举; 永远不会
        异常
        InvalidSearchFilterException - 如果基础目录不支持或不理解指定的搜索过滤器
        InvalidSearchControlsException - 如果搜索控件包含无效设置
        NamingException - 如果遇到命名异常
        另请参见：
        search(Name, String, Object[], SearchControls) ， SearchControls ， SearchResult

      • search

        NamingEnumeration<SearchResult> search​(Name name,
                                       String filterExpr,
                                       Object[] filterArgs,
                                       SearchControls cons)
                                throws NamingException
        在命名的上下文或对象中搜索满足给定搜索过滤器的条目。 执行搜索控件指定的搜索。

        filterExpr的解释基于RFC 2254.它可能另外包含{i}形式的{i} - 其中i是一个整数 - 表示filterArgs数组中的对象。 filterExpr的解释在其他方面与方法search(Name, String, SearchControls)的filter参数的解释相同。

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

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

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

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

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

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

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

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

        参数
        name - 要搜索的上下文或对象的名称
        filterExpr - 用于搜索的过滤器表达式。 表达式可以包含“ {i} ”形式的变量，其中i是非负整数。 不能为空。
        filterArgs - 替换filterExpr的变量的参数数组。 filterArgs[i]的值将替换每次出现的“ {i} ”。 如果为null，则等效于空数组。
        cons - 控制搜索的搜索控件。 如果为null，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        满足过滤器的对象的SearchResult的枚举; 永远不会
        异常
        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是非负整数。 不能为空。
        filterArgs - 替换filterExpr的变量的参数数组。 filterArgs[i]的值将替换每次出现的“ {i} ”。 如果为null，则等效于空数组。
        cons - 控制搜索的搜索控件。 如果为null，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        满足过滤器的对象的SearchResult的枚举; 永远不会
        异常
        ArrayIndexOutOfBoundsException - 如果 filterExpr包含 {i}表达式，其中 i超出数组的范围 filterArgs
        InvalidSearchControlsException - 如果 cons包含无效设置
        InvalidSearchFilterException - 如果 filterExpr与 filterArgs表示无效的搜索过滤器
        NamingException - 如果遇到命名异常