模块 java.naming
包 javax.naming

接口 Context

所有已知的子接口：
DirContext , EventContext , EventDirContext , LdapContext
所有已知的实现类：
InitialContext , InitialDirContext , InitialLdapContext
public interface Context
这个接口代表一个命名上下文，它由一组名称到对象的绑定组成。它包含检查和更新这些绑定的方法。

名称

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

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

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

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

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

异常

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

并发访问

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

出于并发控制的目的，返回 NamingEnumeration 的 Context 操作在枚举仍在使用中或仍在遵循该操作生成的任何引用时不被视为已完成。

参数

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

环境属性

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

当上下文方法从一个上下文进行到下一个上下文时，环境从父上下文继承。一个上下文的环境变化不会直接影响其他上下文的环境。

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

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

资源文件

为了简化设置 JNDI 应用程序所需环境的任务，应用程序组件和服务提供者可以与 resource files. 一起分发。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 资源文件：provider 和 application。

提供者资源文件

每个服务提供者都有一个可选资源，其中列出了特定于该提供者的属性。该资源的名称是：
[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 的 application resource files。此外，如果 Java 安装目录包含内置属性文件（通常为 conf/jndi.properties ），JNDI 会将其视为附加的应用程序资源文件。这些文件中包含的所有属性都放置在初始上下文的环境中。这个环境然后被其他上下文继承。

对于在多个应用程序资源文件中找到的每个属性，JNDI 使用找到的第一个值，或者在一些有意义的情况下，它连接所有的值（细节在下面给出）。例如，如果在三个 jndi.properties 资源文件中找到“java.naming.factory.object”属性，则对象工厂列表是所有三个文件的属性值的串联。使用此方案，每个可部署组件负责列出它导出的工厂。 JNDI 在搜索工厂类时自动收集并使用所有这些导出列表。

属性搜索算法

当 JNDI 构造初始上下文时，上下文的环境使用传递给构造函数的环境参数中定义的属性、系统属性和应用程序资源文件进行初始化。有关详细信息，请参阅 InitialContext 。这个初始环境然后由其他上下文实例继承。

当 JNDI 类库需要确定属性的值时，它通过按顺序合并以下两个来源的值来实现：

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

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

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

自从：
1.3

  • 字段详细信息

  • 方法详情

    • lookup

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

    • lookup

      Object  lookup(String  name) throws NamingException
      检索命名对象。有关详细信息，请参阅 lookup(Name) 。
      参数：
      name - 要查找的对象的名称
      返回：
      绑定到 name 的对象
      抛出：
      NamingException - 如果遇到命名异常

    • bind

      void bind(Name  name, Object  obj) throws NamingException
      将名称绑定到对象。所有中间上下文和目标上下文（由名称的终端原子组件以外的所有内容命名）必须已经存在。
      参数：
      name - 要绑定的名称；可能不为空
      obj - 要绑定的对象；可能为空
      抛出：
      NameAlreadyBoundException - 如果名称已经绑定
      InvalidAttributesException - 如果对象没有提供所有强制属性
      NamingException - 如果遇到命名异常
      参见：

    • bind

      void bind(String  name, Object  obj) throws NamingException
      将名称绑定到对象。有关详细信息，请参阅 bind(Name, Object) 。
      参数：
      name - 要绑定的名称；可能不为空
      obj - 要绑定的对象；可能为空
      抛出：
      NameAlreadyBoundException - 如果名称已经绑定
      InvalidAttributesException - 如果对象没有提供所有强制属性
      NamingException - 如果遇到命名异常

    • rebind

      void rebind(Name  name, Object  obj) throws NamingException
      将名称绑定到对象，重写任何现有绑定。所有中间上下文和目标上下文（由名称的终端原子组件以外的所有内容命名）必须已经存在。

      如果对象是 DirContext ，则与名称关联的任何现有属性都将替换为对象的属性。否则，与名称关联的任何现有属性都保持不变。

      参数：
      name - 要绑定的名称；可能不为空
      obj - 要绑定的对象；可能为空
      抛出：
      InvalidAttributesException - 如果对象没有提供所有强制属性
      NamingException - 如果遇到命名异常
      参见：

    • rebind

      void rebind(String  name, Object  obj) throws NamingException
      将名称绑定到对象，覆盖任何现有绑定。有关详细信息，请参阅 rebind(Name, Object) 。
      参数：
      name - 要绑定的名称；可能不为空
      obj - 要绑定的对象；可能为空
      抛出：
      InvalidAttributesException - 如果对象没有提供所有强制属性
      NamingException - 如果遇到命名异常

    • unbind

      void unbind(Name  name) throws NamingException
      解除绑定命名对象。从目标上下文中删除 name 中的终端原子名称——除了 name 的终端原子部分之外的所有名称。

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

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

      参数：
      name - 要解除绑定的名称；可能不为空
      抛出：
      NameNotFoundException - 如果中间上下文不存在
      NamingException - 如果遇到命名异常
      参见：

    • unbind

      void unbind(String  name) throws NamingException
      解除绑定命名对象。有关详细信息，请参阅 unbind(Name) 。
      参数：
      name - 要解除绑定的名称；可能不为空
      抛出：
      NameNotFoundException - 如果中间上下文不存在
      NamingException - 如果遇到命名异常

    • rename

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

    • rename

      void rename(String  oldName, String  newName) throws NamingException
      将新名称绑定到绑定到旧名称的对象，并取消绑定旧名称。有关详细信息，请参阅 rename(Name, Name) 。
      参数：
      oldName - 现有绑定的名称；可能不为空
      newName - 新绑定的名称；可能不为空
      抛出：
      NameAlreadyBoundException - 如果 newName 已经绑定
      NamingException - 如果遇到命名异常

    • list

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

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

      参数：
      name - 要列出的上下文的名称
      返回：
      此上下文中绑定的名称和类名称的枚举。枚举的每个元素都是 NameClassPair 类型。
      抛出：
      NamingException - 如果遇到命名异常
      参见：

    • list

      NamingEnumeration <NameClassPair > list(String  name) throws NamingException
      枚举命名上下文中绑定的名称，以及绑定到它们的对象的类名。有关详细信息，请参阅 list(Name) 。
      参数：
      name - 要列出的上下文的名称
      返回：
      此上下文中绑定的名称和类名称的枚举。枚举的每个元素都是 NameClassPair 类型。
      抛出：
      NamingException - 如果遇到命名异常

    • listBindings

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

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

      参数：
      name - 要列出的上下文的名称
      返回：
      此上下文中绑定的枚举。枚举的每个元素都是 Binding 类型。
      抛出：
      NamingException - 如果遇到命名异常
      参见：

    • listBindings

      NamingEnumeration <Binding > listBindings(String  name) throws NamingException
      枚举命名上下文中绑定的名称，以及绑定到它们的对象。有关详细信息，请参阅 listBindings(Name) 。
      参数：
      name - 要列出的上下文的名称
      返回：
      此上下文中绑定的枚举。枚举的每个元素都是 Binding 类型。
      抛出：
      NamingException - 如果遇到命名异常

    • destroySubcontext

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

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

      在联合命名系统中，来自一个命名系统的上下文可以绑定到另一个命名系统中的名称。随后可以使用复合名称查找外部上下文并对其执行操作。但是，使用此复合名称破坏上下文的尝试将失败并返回 NotContextException ，因为外部上下文不是它所绑定的上下文的“子上下文”。相反，使用 unbind() 删除外部上下文的绑定。销毁外部上下文需要 destroySubcontext() 在来自外部上下文的“本地”命名系统的上下文上执行。

      参数：
      name - 要销毁的上下文的名称；可能不为空
      抛出：
      NameNotFoundException - 如果中间上下文不存在
      NotContextException - 如果名称已绑定但未命名上下文，或未命名适当类型的上下文
      ContextNotEmptyException - 如果命名上下文不为空
      NamingException - 如果遇到命名异常
      参见：

    • destroySubcontext

      void destroySubcontext(String  name) throws NamingException
      销毁命名上下文并将其从命名空间中删除。有关详细信息，请参阅 destroySubcontext(Name) 。
      参数：
      name - 要销毁的上下文的名称；可能不为空
      抛出：
      NameNotFoundException - 如果中间上下文不存在
      NotContextException - 如果名称已绑定但未命名上下文，或未命名适当类型的上下文
      ContextNotEmptyException - 如果命名上下文不为空
      NamingException - 如果遇到命名异常

    • createSubcontext

      Context  createSubcontext(Name  name) throws NamingException
      创建并绑定一个新的上下文。使用给定的名称创建一个新上下文并将其绑定到目标上下文（由名称的终端原子组件以外的所有内容命名）。所有中间上下文和目标上下文必须已经存在。
      参数：
      name - 要创建的上下文的名称；可能不为空
      返回：
      新创建的上下文
      抛出：
      NameAlreadyBoundException - 如果名称已经绑定
      InvalidAttributesException - 如果创建子上下文需要指定强制属性
      NamingException - 如果遇到命名异常
      参见：

    • createSubcontext

      Context  createSubcontext(String  name) throws NamingException
      创建并绑定一个新的上下文。有关详细信息，请参阅 createSubcontext(Name) 。
      参数：
      name - 要创建的上下文的名称；可能不为空
      返回：
      新创建的上下文
      抛出：
      NameAlreadyBoundException - 如果名称已经绑定
      InvalidAttributesException - 如果创建子上下文需要指定强制属性
      NamingException - 如果遇到命名异常

    • lookupLink

      Object  lookupLink(Name  name) throws NamingException
      检索命名对象，除了名称的终端原子组件之外的链接。如果绑定到 name 的对象不是链接，则返回对象本身。
      参数：
      name - 要查找的对象的名称
      返回：
      绑定到 name 的对象，不遵循终端链接（如果有）。
      抛出：
      NamingException - 如果遇到命名异常
      参见：

    • lookupLink

      Object  lookupLink(String  name) throws NamingException
      检索命名对象，除了名称的终端原子组件之外的链接。有关详细信息，请参阅 lookupLink(Name) 。
      参数：
      name - 要查找的对象的名称
      返回：
      绑定到 name 的对象，不遵循终端链接（如果有）
      抛出：
      NamingException - 如果遇到命名异常

    • getNameParser

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

    • getNameParser

      NameParser  getNameParser(String  name) throws NamingException
      检索与命名上下文关联的解析器。有关详细信息，请参阅 getNameParser(Name) 。
      参数：
      name - 从中获取解析器的上下文的名称
      返回：
      可以将复合名称解析为其原子组件的名称解析器
      抛出：
      NamingException - 如果遇到命名异常

    • composeName

      Name  composeName(Name  name, Name  prefix) throws NamingException
      将此上下文的名称与相对于此上下文的名称组合在一起。给定一个相对于此上下文的名称 (name)，以及此上下文相对于其祖先之一的名称 (prefix)，此方法使用适用于所涉及的命名系统的语法返回两个名称的组合。也就是说，如果 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  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 - 如果遇到命名异常
      参见：

    • removeFromEnvironment

      Object  removeFromEnvironment(String  propName) throws NamingException
      从此上下文的环境中删除环境属性。有关环境属性的更多详细信息，请参阅类描述。
      参数：
      propName - 要删除的环境属性的名称；不能为空
      返回：
      属性的先前值，如果属性不在环境中则为 null
      抛出：
      NamingException - 如果遇到命名异常
      参见：

    • getEnvironment

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

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

      返回：
      这个上下文的环境；永不为空
      抛出：
      NamingException - 如果遇到命名异常
      参见：

    • close

      void close() throws NamingException
      关闭此上下文。此方法立即释放此上下文的资源，而不是等待它们被垃圾收集器自动释放。

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

      抛出：
      NamingException - 如果遇到命名异常

    • getNameInNamespace

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

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

      返回：
      此上下文在其自己的命名空间中的名称；永不为空
      抛出：
      OperationNotSupportedException - 如果命名系统没有全名的概念
      NamingException - 如果遇到命名异常
      自从：
      1.3