Module  java.naming
软件包  javax.naming

Interface Context

  • All Known Subinterfaces:
    DirContext ， EventContext ， EventDirContext ， LdapContext
    所有已知实现类：
    InitialContext ， InitialDirContext ， InitialLdapContext 

    public interface Context
    该接口表示一个命名上下文，它由一组名称对对象绑定组成。 它包含检查和更新这些绑定的方法。

    名称

    作为参数传递给Context方法的每个名称都是相对于该上下文。 空的名称用于命名上下文本身。 名称参数可能永远不为空。

    大多数方法都有超载版本，一个使用一个Name参数，一个采用String 。 这些重载版本是等效的，因为如果Name和String参数只是同名的不同表示，那么相同方法的重载版本的行为相同。 在下面的方法描述中，只有一个版本被完整记录。 第二个版本代替了第一个链接：相同的文档适用于两者。

    对于支持联合的系统， Context方法的String名称参数是复合名称。 名称是的实例参数CompositeName被视为复合名称，而Name参数不属于的实例CompositeName作为化合物名称治疗（其可能是实例CompoundName或化合物名称的其它实施方式）。 这允许将NameParser.parse()的结果用作Context方法的参数。 在JNDI 1.2之前，所有的名称参数被视为复合名称。

    此外，对于支持联合的系统， NamingEnumeration从list()和listBindings()返回的所有名称都是以字符串表示的复合名称。 有关名称的字符串语法，请参阅CompositeName 。

    对于不支持联合的系统，名称参数（在Name或String表单中）和NamingEnumeration返回的名称可能是其自己的命名空间中的名称，而不是复合命名空间中的名称，由服务提供商决定。

    例外

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

    并发访问

    上下文实例不能保证与多个线程的并发访问同步。 需要同时访问单个上下文实例的线程应在其间同步并提供必要的锁定。 每个操作不同Context实例的多个线程不需要同步。 请注意， lookup方法在传递一个空名时将返回一个表示相同命名上下文的Context Context实例。

    为了并发控制的目的，返回NamingEnumeration的上下文操作在枚举仍在使用期间，或者仍然遵循该操作生成的任何引用时，不会被视为完成。

    参数

    传递给Context接口的任何方法或其子接口之一的Name参数不会被服务提供商修改。 服务提供商可以在操作期间保留对其的引用，包括方法结果的任何枚举以及生成的任何引用的处理。 呼叫者在此期间不应修改对象。 由任何此类方法返回的A Name由呼叫者拥有。 呼叫者可以随后修改它; 服务提供商可能不会。

    环境属性

    JNDI应用程序需要一种方式来传达定义访问命名和目录服务的环境的各种首选项和属性。 例如，上下文可能需要指定安全凭据才能访问该服务。 另一个上下文可能需要提供服务器配置信息。 这些被称为上下文的环境 。 Context接口提供了检索和更新此环境的方法。

    随着上下文方法从一个上下文进入下一个环境，环境是从父上下文继承的。 对一个环境的环境的改变不会直接影响其他环境的环境。

    当环境属性被使用和/或验证有效性时，它是实现依赖的。 例如，服务提供商使用某些与安全性相关的属性来“登录”目录。 此登录过程可能会在上下文创建时发生，或者在上下文首次调用方法时发生。 何时，以及是否发生这种情况是依赖于实现的。 当环境属性从上下文中添加或删除时，验证更改的有效性再次取决于实现。 例如，某些属性的验证可能在更改时发生，或在下一个操作在上下文中执行时，或根本不发生。

    任何具有对上下文的引用的对象都可以检查该上下文的环境。 敏感信息（如明文密码）不应存储在那里，除非已知实现保护它。

    资源文件

    为了简化设置JNDI应用程序所需环境的任务，应用程序组件和服务提供程序可能与资源文件一起分发。 JNDI资源文件是属性文件格式的文件（请参阅java.util.Properties ），其中包含键/值对列表。 关键是属性的名称（例如“java.naming.factory.object”），该值是为该属性定义的格式的字符串。 以下是JNDI资源文件的示例：

    java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
    JNDI类库读取资源文件，并使属性值免费使用。 因此，JNDI资源文件应该被认为是“世界可读”的，敏感信息（如明文密码）不应存储在那里。

    有两种JNDI资源文件： 提供者和应用程序 。

    提供者资源文件

    每个服务提供商都有一个可选资源，列出特定于该提供商的属性。 该资源的名称是：
    [ prefix/] jndiprovider.properties
    其中， prefix是提供者上下文实现的包名，每个句点（“。”）转换为斜杠（“/”）。 例如，假设服务提供商定义了一个类名为com.sun.jndi.ldap.LdapCtx的上下文实现。 此提供程序的提供程序资源名为com/sun/jndi/ldap/jndiprovider.properties 。 如果该类不在包中，则该资源的名称仅为jndiprovider.properties 。

    JNDI类库中的某些方法使用指定JNDI工厂列表的标准JNDI属性：

    • java.naming.factory.object
    • java.naming.factory.state
    • java.naming.factory.control
    • java.naming.factory.url.pkgs
    当确定这些属性的值时，JNDI库将查询提供者资源文件。 可以由服务提供商自行决定在提供商资源文件中设置这些以外的属性。 服务提供者的文件应明确说明允许哪些属性; 该文件中的其他属性将被忽略。

    应用资源文件

    当部署应用程序时，它的类路径通常会有多个代码库目录和JAR。 JNDI在类路径中定位（使用ClassLoader.getResources() ）名为jndi.properties所有应用程序资源文件 。 另外，如果Java安装目录包含内置的属性文件，通常为conf/jndi.properties ，则JNDI将其视为其他应用程序资源文件。 这些文件中包含的所有属性都放置在初始上下文的环境中。 然后，这种环境由其他上下文继承。

    对于在多个应用程序资源文件中找到的每个属性，JNDI使用发现的第一个值，或者在少数情况下，将其连接起来（详细信息如下）。 例如，如果在三个jndi.properties资源文件中找到“java.naming.factory.object”属性，则对象工厂列表是来自所有三个文件的属性值的连接。 使用此方案，每个可部署组件负责列出其出口的工厂。 搜索工厂类时，JNDI会自动收集并使用所有这些导出列表。

    搜索算法的属性

    当JNDI构造一个初始上下文时，上下文的环境是通过传递给构造函数，系统属性和应用程序资源文件的环境参数中定义的属性进行初始化的。 详见InitialContext 。 然后，这个初始环境由其他上下文实例继承。

    当JNDI类库需要确定一个属性的值时，它按照以下顺序合并来自以下两个来源的值：

    1. 上下文的环境正在运行。
    2. 提供者资源文件（ jndiprovider.properties ）用于正在操作的上下文。
    对于在这两个来源中找到的每个属性，JNDI确定属性的值如下。 如果属性是指定JNDI工厂列表（列出的above ）的标准JNDI属性之一，则值将连接到单个冒号分隔列表中。 对于其他属性，仅使用第一个找到的值。

    当服务提供商需要确定属性的值时，通常会直接从环境中获取该值。 服务提供商可以将供应商特定的属性定义为放置在其自己的提供商资源文件中。 在这种情况下，它应该合并上一段所述的值。

    以这种方式，每个服务提供商开发人员可以指定要与该服务提供商一起使用的工厂列表。 这些可以由应用程序的部署者指定的应用程序资源修改，而应用程序资源又可以由用户修改。

    从以下版本开始：
    1.3

    • Field Summary

      Fields  
      Modifier and Type Field 描述
      static String APPLET
      已过时。
      在构建初始上下文时，将忽略具有此名称的环境属性。 此常量最初用作属性名称，以在创建初始上下文时指定Applet以从中检索参数。 目前需要传递给初始上下文的任何applet属性都应该复制到环境哈希表中： 
         Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, ((Applet) this).getParameter(Context.INITIAL_CONTEXT_FACTORY)); env.put(Context.PROVIDER_URL, ((Applet) this).getParameter(Context.PROVIDER_URL)); // ... other properties ... Context ctx = new InitialContext(env);
      static String AUTHORITATIVE
      用于指定所请求的服务的权威性的环境属性的名称的常量。
      static String BATCHSIZE
      包含用于指定通过服务协议返回数据时使用的批量大小的环境属性名称的常量。
      static String DNS_URL
      持有用于指定用于JNDI URL上下文的DNS主机和域名的环境属性的名称的常量（例如“dns：//somehost/wiz.com”）。
      static String INITIAL_CONTEXT_FACTORY
      用于指定要使用的初始上下文工厂的环境属性的名称的常量。
      static String LANGUAGE
      包含用于指定与服务一起使用的首选语言的环境属性名称的常量。
      static String OBJECT_FACTORIES
      用于指定要使用的对象工厂列表的环境属性的名称的常量。
      static String PROVIDER_URL
      包含用于指定服务提供商要使用的配置信息的环境属性的名称的常量。
      static String REFERRAL
      持有用于指定如何处理服务提供商遇到的引用的环境属性的名称的常量。
      static String SECURITY_AUTHENTICATION
      持有用于指定要使用的安全级别的环境属性的名称的常量。
      static String SECURITY_CREDENTIALS
      包含用于指定用于验证呼叫者到服务的主体的凭据的环境属性的名称的常量。
      static String SECURITY_PRINCIPAL
      持有用于指定主体的身份的环境属性的常量，用于验证对该服务的呼叫者。
      static String SECURITY_PROTOCOL
      用于指定要使用的安全协议的环境属性的名称的常量。
      static String STATE_FACTORIES
      用于指定要使用的状态工厂列表的环境属性的名称的常量。
      static String URL_PKG_PREFIXES
      持有环境属性名称的常量，用于指定在URL上下文工厂中加载时使用的包前缀列表。

    • 方法详细信息

      • lookup

        Object lookup​(Name name)
       throws NamingException
        检索命名对象。 如果name为空，则返回此上下文的新实例（其表示与该上下文相同的命名上下文，但其环境可以独立修改，并且可以并发访问）。
        参数
        name - 要查找的对象的名称
        结果
        对象绑定到 name
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        lookup(String) ， lookupLink(Name)

      • unbind

        void unbind​(Name name)
     throws NamingException
        取消绑定命名对象。 从目标上下文中删除name的终端原子名称， name由name的所有终端原子部分name 。

        这种方法是幂等的。 即使终端原子名称未绑定在目标上下文中，也可以成功，但如果任何中间上下文不存在，则抛出NameNotFoundException 。

        与名称相关联的任何属性都将被删除。 中间上下文不变。

        参数
        name - 取消绑定的名称 可能不是空的
        异常
        NameNotFoundException - 如果中间上下文不存在
        NamingException - 如果遇到命名异常
        另请参见：
        unbind(String)

      • rename

        void rename​(Name oldName,
            Name newName)
     throws NamingException
        将绑定到旧名称的对象绑定一个新名称，并取消绑定旧名称。 这两个名称都是相对于这个上下文。 与旧名称相关联的任何属性都将与新名称相关联。 旧名称的中间上下文不会更改。
        参数
        oldName - 现有绑定的名称; 可能不是空的
        newName - 新绑定的名称; 可能不是空的
        异常
        NameAlreadyBoundException - 如果 newName已经绑定
        NamingException - 如果遇到命名异常
        另请参见：
        rename(String, String) ， bind(Name, Object) ， rebind(Name, Object)

      • list

        NamingEnumeration<NameClassPair> list​(Name name)
                               throws NamingException
        枚举在命名上下文中绑定的名称以及绑定到它们的对象的类名。 不包括任何subcontexts的内容。

        如果将绑定添加到此上下文或从此上下文中删除，则其对先前返回的枚举的影响是未定义的。

        参数
        name - 要列出的上下文的名称
        结果
        在此上下文中枚举绑定的名称和类名称。 枚举的每个元素都是NameClassPair型。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        list(String) ， listBindings(Name) ， NameClassPair

      • list

        NamingEnumeration<NameClassPair> list​(String name)
                               throws NamingException
        枚举在命名上下文中绑定的名称以及绑定到它们的对象的类名。 详见list(Name) 。
        参数
        name - 要列出的上下文的名称
        结果
        在此上下文中枚举绑定的名称和类名称。 枚举的每个元素都是NameClassPair 。
        异常
        NamingException - 如果遇到命名异常

      • listBindings

        NamingEnumeration<Binding> listBindings​(Name name)
                                 throws NamingException
        枚举在命名上下文中绑定的名称以及绑定到它们的对象。 不包括任何subcontexts的内容。

        如果将绑定添加到此上下文或从此上下文中删除，则其对先前返回的枚举的影响是未定义的。

        参数
        name - 要列出的上下文的名称
        结果
        在这个上下文中绑定的枚举。 枚举的每个元素都是类型Binding 。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        listBindings(String) ， list(Name) ， Binding

      • destroySubcontext

        void destroySubcontext​(Name name)
                throws NamingException
        销毁命名上下文并将其从命名空间中删除。 与名称相关联的任何属性也将被删除。 中间语境不会被破坏。

        这种方法是幂等的。 即使终端原子名称未绑定在目标上下文中，也可以成功，但如果任何中间上下文不存在，则抛出NameNotFoundException 。

        在联合命名系统中，来自一个命名系统的上下文可能绑定到另一个命名系统中的名称。 随后可以使用复合名称查找并执行对外部上下文的操作。 然而，企图破坏使用此复合名称将失败与上下文NotContextException ，因为外部上下文不是在它所在的上下文的“子上下文”。 相反，请使用unbind()删除外部上下文的绑定。 破坏外部环境要求在外部环境的“本机”命名系统的上下文中执行destroySubcontext() 。

        参数
        name - 要销毁的上下文的名称; 可能不是空的
        异常
        NameNotFoundException - 如果中间上下文不存在
        NotContextException - 如果名称是绑定的，但没有命名上下文，或者不指定适当类型的上下文
        ContextNotEmptyException - 如果命名上下文不为空
        NamingException - 如果遇到命名异常
        另请参见：
        destroySubcontext(String)

      • lookupLink

        Object lookupLink​(Name name)
           throws NamingException
        检索命名对象，除了名称的终端原子组件以外的链接。 如果绑定到name的对象不是链接，则返回对象本身。
        参数
        name - 要查找的对象的名称
        结果
        对象绑定到 name ，不跟随终端链接（如果有的话）。
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        lookupLink(String)

      • lookupLink

        Object lookupLink​(String name)
           throws NamingException
        检索命名对象，除了名称的终端原子组件以外的链接。 详见lookupLink(Name) 。
        参数
        name - 要查找的对象的名称
        结果
        对象绑定到 name ，不跟随终端链接（如果有）
        异常
        NamingException - 如果遇到命名异常

      • getNameParser

        NameParser getNameParser​(Name name)
                  throws NamingException
        检索与命名上下文关联的解析器。 在命名空间联盟中，不同的命名系统会以不同的方式解析名称。 该方法允许应用程序使用特定命名系统的命名约定来获取解析器将其解析为其原子组件的名称。 在任何单个命名系统中，通过此方法返回的NameParser对象必须相等（使用equals()测试）。
        参数
        name - 从中获取解析器的上下文的名称
        结果
        一个名称解析器，可以将复合名称解析为其原子组件
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        getNameParser(String) ， CompoundName

      • getNameParser

        NameParser getNameParser​(String name)
                  throws NamingException
        检索与命名上下文关联的解析器。 详见getNameParser(Name) 。
        参数
        name - 从中获取解析器的上下文的名称
        结果
        一个名称解析器，可以将复合名称解析为其原子组件
        异常
        NamingException - 如果遇到命名异常

      • composeName

        Name composeName​(Name name,
                 Name prefix)
          throws NamingException
        使用相对于该上下文的名称组合此上下文的名称。 命名（ name ）相对于此上下文，和名称（ prefix这相对于它的一个祖先上下文），则此方法返回使用适合于所涉及的命名系统（S）的语法的两个名字的组成。 也就是说，如果name命名相对于该上下文的对象，则结果是相同对象的名称，但相对于祖先上下文。 没有一个名字可能为空。

        例如，如果这个上下文相对于初始上下文命名为“wiz.com”，那么 

          composeName("east", "wiz.com")
        可能会返回"east.wiz.com" 。 如果这个上下文被命名为“org / research”，那么 
          composeName("user/jane", "org/research")
        可能会返回"org/research/user/jane" 
          composeName("user/jane", "research")
        返回"research/user/jane" 。
        参数
        name - 相对于此上下文的名称
        prefix - 此上下文相对于其祖先之一的名称
        结果
        组成为 prefix和 name
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        composeName(String, String)

      • composeName

        String composeName​(String name,
                   String prefix)
            throws NamingException
        使用相对于该上下文的名称组合此上下文的名称。 详见composeName(Name, Name) 。
        参数
        name - 相对于此上下文的名称
        prefix - 此上下文相对于其祖先的名称
        结果
        组成 prefix和 name
        异常
        NamingException - 如果遇到命名异常

      • addToEnvironment

        Object addToEnvironment​(String propName,
                        Object propVal)
                 throws NamingException
        在此上下文的环境中添加一个新的环境属性。 如果属性已经存在，其值将被覆盖。 有关环境属性的详细信息，请参阅类描述。
        参数
        propName - 要添加的环境属性的名称; 可能不为空
        propVal - 要添加的属性的值; 可能不为空
        结果
        该属性的前一个值，如果该属性不在之前的环境中，则返回null
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        getEnvironment() ， removeFromEnvironment(String)

      • removeFromEnvironment

        Object removeFromEnvironment​(String propName)
                      throws NamingException
        从环境环境中删除环境属性。 有关环境属性的详细信息，请参阅类描述。
        参数
        propName - 要删除的环境属性的名称; 可能不为空
        结果
        属性的先前值，如果属性不在环境中，则为null
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        getEnvironment() ， addToEnvironment(String, Object)

      • getEnvironment

        Hashtable<?,?> getEnvironment​()
                       throws NamingException
        检索此环境有效的环境。 有关环境属性的详细信息，请参阅类描述。

        调用者不应该对返回的对象进行任何更改：它们对上下文的影响是未定义的。 可以使用addToEnvironment()和removeFromEnvironment()更改此上下文的环境。

        结果
        这个环境的环境; 从不为空
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        addToEnvironment(String, Object) ， removeFromEnvironment(String)

      • close

        void close​()
    throws NamingException
        关闭这个上下文。 此方法可以立即释放上下文的资源，而不是等待垃圾回收器自动释放该资源。

        该方法是幂等的：在已经关闭的上下文中调用它没有任何效果。 不允许在封闭上下文中调用任何其他方法，并导致未定义的行为。

        异常
        NamingException - 如果遇到命名异常

      • getNameInNamespace

        String getNameInNamespace​()
                   throws NamingException
        在其自己的命名空间中检索此上下文的全名。

        许多命名服务对于各自的命名空间中的对象都有一个“全名”概念。 例如，LDAP条目具有可分辨名称，DNS记录具有完全限定名称。 此方法允许客户端应用程序检索此名称。 此方法返回的字符串不是JNDI组合名称，不应直接传递给上下文方法。 在命名系统中，全名概念没有意义，抛出OperationNotSupportedException 。

        结果
        这个上下文的名称在自己的命名空间中; 从不为空
        异常
        OperationNotSupportedException - 如果命名系统没有全名的概念
        NamingException - 如果遇到命名异常
        从以下版本开始：
        1.3