Module  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方法的名称参数的解释，请参见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

    • 字段详细信息

      • 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​(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[])

      • 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)

      • 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和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​(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​(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
        在命名的上下文或对象中搜索满足给定搜索过滤器的条目。 按照搜索控件的指定执行搜索。 详见search(Name, String, Object[], SearchControls) 。
        参数
        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 - 如果遇到命名异常