Module  java.naming
软件包  javax.naming.directory

Class InitialDirContext

    • 构造方法详细信息

      • 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​(Hashtable<?,?> environment)
                  throws NamingException
        使用提供的环境构建初始DirContext。 javax.naming.InitialContext类描述中讨论环境属性。

        此构造函数不会修改environment或保存对其的引用，但可以保存克隆。 environment来电者不能修改可变键和值， environment它已被传递给构造函数。

        参数
        environment - 用于创建初始DirContext的环境。 空指示空的环境。
        异常
        NamingException - 如果遇到命名异常

    • 方法详细信息

      • getAttributes

        public Attributes getAttributes​(Name name,
                                String[] attrIds)
                         throws NamingException
        描述从接口DirContext复制
        检索与命名对象关联的所选属性。 请参阅有关属性模型，属性类型名称和操作属性的类描述。

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

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

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

        Specified by:
        getAttributes在接口 DirContext
        参数
        name - 从中检索属性的对象的名称
        attrIds - 要检索的属性的标识符。 null表示应检索所有属性; 一个空数组表示不应该检索。
        结果
        请求的属性; 从不为空
        异常
        NamingException - 如果遇到命名异常

      • rebind

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

      • createSubcontext

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

      • getSchema

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

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

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

        Specified by:
        getSchema在接口 DirContext
        参数
        name - 要检索其模式的对象的名称
        结果
        与上下文相关联的模式; 从不为空
        异常
        OperationNotSupportedException - 如果不支持模式
        NamingException - 如果遇到命名异常

      • getSchemaClassDefinition

        public DirContext getSchemaClassDefinition​(Name name)
                                    throws NamingException
        说明从界面DirContext复制
        检索包含命名对象的类定义的模式对象的上下文。

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

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

        在JNDI 1.2之前，此方法返回一个表示命名对象的类定义的模式对象。 自JNDI 1.2起，该方法返回一个DirContext其中包含所有命名对象的类定义。

        Specified by:
        getSchemaClassDefinition在接口 DirContext
        参数
        name - 要检索其对象类定义的对象的名称
        结果
        DirContext包含命名对象的类定义; 从不为空
        异常
        OperationNotSupportedException - 如果不支持模式
        NamingException - 如果遇到命名异常

      • search

        public NamingEnumeration<SearchResult> search​(Name name,
                                              Attributes matchingAttributes,
                                              String[] attributesToReturn)
                                       throws NamingException
        描述从界面DirContext复制
        在单个上下文中搜索包含指定属性集的对象，并检索所选属性。 使用默认的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 ，请使用采用过滤器参数的search方法的版本。

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

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

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

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

        Specified by:
        search在接口 DirContext
        参数
        name - 要搜索的上下文的名称
        matchingAttributes - 要搜索的属性。 如果为空，则返回目标上下文中的所有对象。
        attributesToReturn - 要返回的属性。 null表示要返回的所有属性; 一个空数组表示不返回任何数组。
        结果
        SearchResult对象的非空枚举。 每个SearchResult包含由attributesToReturn标识的属性和相对于由name命名的上下文命名的对应对象的名称。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        SearchControls ， SearchResult ， DirContext.search(Name, String, Object[], SearchControls)

      • 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”。

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

        如果目录不支持其某些或全部属性的字符串表示形式，则可以使用以Object形式接受过滤器参数的形式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也可能包含匹配对象的属性。

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

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

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

        Specified by:
        search在接口 DirContext
        参数
        name - 要搜索的上下文或对象的名称
        filter - 用于搜索的过滤器表达式; 可能不为空
        cons - 控制搜索的搜索控件。 如果为空，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        枚举满足过滤器的物体SearchResult s; 从不为空
        异常
        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) 。
        Specified by:
        search在接口 DirContext
        参数
        name - 要搜索的上下文或对象的名称
        filterExpr - 用于搜索的过滤器表达式。 该表达式可能包含“ {i} ”形式的变量，其中i是非负整数。 可能不为空
        filterArgs - 在filterExpr替换变量的参数数组。 filterArgs[i]的值将取代每个“ {i} ”的发生。 如果为空，则相当于一个空数组。
        cons - 控制搜索的搜索控件。 如果为空，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        枚举满足过滤器的物体SearchResult s; 从不为空
        异常
        InvalidSearchControlsException - 如果 cons包含无效设置
        InvalidSearchFilterException - 如果 filterExpr与 filterArgs表示无效的搜索过滤器
        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] 。 在RFC 2254第4节的过滤器语法中出现attr ， value或matchingrule生产的任何地方都可以使用这些变量。当一个字符串值过滤器参数代替一个变量时，过滤器被解释为：变量的位置，具有根据RFC 2254的规则被转义的过滤器（例如'*' ）中具有特殊意义的任何字符。

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

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

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

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

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

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

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

        Specified by:
        search在接口 DirContext
        参数
        name - 要搜索的上下文或对象的名称
        filterExpr - 用于搜索的过滤器表达式。 该表达式可能包含“ {i} ”形式的变量，其中i是非负整数。 可能不为空
        filterArgs - 在filterExpr替换变量的参数数组。 filterArgs[i]的值将代替每次出现的“ {i} ”。 如果为空，则相当于一个空数组。
        cons - 控制搜索的搜索控件。 如果为空，则使用默认搜索控件（相当于(new SearchControls()) ）。
        结果
        枚举满足过滤器的物体SearchResult s; 从不为空
        异常
        InvalidSearchControlsException - 如果 cons包含无效设置
        InvalidSearchFilterException - 如果 filterExpr与 filterArgs表示无效的搜索过滤器
        NamingException - 如果遇到命名异常
        另请参见：
        DirContext.search(Name, Attributes, String[]) ， MessageFormat