Module  java.naming
软件包  javax.naming

Class InitialContext

  • All Implemented Interfaces:
    Context
    已知直接子类：
    InitialDirContext 

    public class InitialContext
extends Object
implements Context
    这个类是执行命名操作的起始上下文。

    所有命名操作都与上下文相关。 初始上下文实现了Context接口，并提供了解析名称的起点。

    当构建初始上下文时，将使用传递给构造函数的环境参数中定义的属性和任何application resource files初始化其环境。

    JNDI通过合并来自以下两个来源的值来确定每个属性的值：

    1. 从构造函数的环境参数和系统属性中首次出现属性。
    2. 应用程序资源文件（ jndi.properties ）。
    对于在这两个来源中找到的每个属性，或在多个应用程序资源文件中，属性的值如下所示。 如果属性是指定JNDI工厂列表的标准JNDI属性之一（请参阅Context ），则所有值都将连接到单个冒号分隔列表中。 对于其他属性，仅使用第一个找到的值。

    初始上下文实现在运行时确定。 默认策略使用环境属性“ java.naming.factory.initial ”，其中包含初始上下文工厂的类名。 解决URL字符串时会出现此策略的一个例外，如下所述。

    当一个URL字符串（ String形式一个scheme_id的：rest_of_name）作为名称参数传递给任何方法，一个URL上下文工厂处理该方案的定位和用于解析URL。 如果没有找到这样的工厂，则使用由"java.naming.factory.initial"指定的初始上下文。 类似地，当第一个组件是URL字符串的CompositeName对象作为name参数传递给任何方法时，会定位一个URL上下文工厂，并用于解析名字组件。 有关URL上下文工厂位置的描述，请参阅NamingManager.getURLContext() 。

    定位初始上下文和URL上下文工厂的默认策略可以通过调用NamingManager.setInitialContextFactoryBuilder()来覆盖。

    当初始上下文无法实例化时抛出NoInitialContextException。 在与InitialContext的任何交互期间都可以抛出此异常，不仅在构建InitialContext时。 例如，初始上下文的实现可能只有在实际方法被调用时才可能懒惰地检索上下文。 应用程序不应该依赖于何时确定初始上下文的存在。

    当环境属性“java.naming.factory.initial”不为空时，InitialContext构造函数将尝试创建其中指定的初始上下文。 那时候，如果遇到问题，最初的上下文工厂可能会引发异常。 然而，它是提供者实现相关的，当它验证并向初始上下文的用户指示任何环境属性或连接相关的问题。 它可以懒惰地进行延迟，直到在上下文中执行操作，或者在构建上下文时急切地。

    InitialContext实例与多线程的并发访问不同步。 每个处理不同InitialContext实例的多个线程不需要同步。 需要同时访问单个InitialContext实例的线程应在其间同步并提供必要的锁定。

    从以下版本开始：
    1.3，JNDI 1.1
    另请参见：
    Context ， NamingManager.setInitialContextFactoryBuilder

    • 字段详细信息

      • defaultInitCtx

        protected Context defaultInitCtx
        保留调用NamingManager.getInitialContext（）的结果的字段。 getDefaultInitCtx（）是第一次调用getDefaultInitCtx（）时设置的。 getDefaultInitCtx（）的后续调用返回defaultInitCtx的值。
        另请参见：
        getDefaultInitCtx()

      • gotDefault

        protected boolean gotDefault
        指示是否通过调用NamingManager.getInitialContext（）获取初始上下文的字段。 如果为true，其结果为defaultInitCtx 。

    • 构造方法详细信息

      • InitialContext

        protected InitialContext​(boolean lazy)
                  throws NamingException
        构造一个初始上下文，并选择不初始化它。 当调用InitialContext构造函数时，当环境参数的值尚未知道时，这可能由子类中的构造函数使用。 子类的构造函数将调用此构造函数，计算环境值，然后在返回之前调用init() 。
        参数
        lazy - 真正的手段不初始化初始上下文; false相当于调用new InitialContext()
        异常
        NamingException - 如果遇到命名异常
        从以下版本开始：
        1.3
        另请参见：
        init(Hashtable)

      • InitialContext

        public InitialContext​(Hashtable<?,?> environment)
               throws NamingException
        使用提供的环境构建初始上下文。 环境属性在类描述中讨论。

        此构造函数不会修改environment或保存对其的引用，但可以保存克隆。 在environment传递给构造函数后，调用者不应修改可变键和值。

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

    • 方法详细信息

      • init

        protected void init​(Hashtable<?,?> environment)
             throws NamingException
        使用提供的环境初始化初始上下文。 环境属性在类描述中讨论。

        此方法将修改environment并保存其引用。 来电者可能不再修改它。

        参数
        environment - 用于创建初始上下文的环境。 空指示空的环境。
        异常
        NamingException - 如果遇到命名异常
        从以下版本开始：
        1.3
        另请参见：
        InitialContext(boolean)

      • doLookup

        public static <T> T doLookup​(Name name)
                      throws NamingException
        一种用于检索命名对象的静态方法。 这是一个等效于调用的快捷方法：

        InitialContext ic = new InitialContext(); Object obj = ic.lookup();

        如果name为空，则返回此上下文的新实例（其表示与该上下文相同的命名上下文，但其环境可以单独修改，并且可以并发访问）。

        参数类型
        T - 返回对象的类型
        参数
        name - 要查找的对象的名称
        结果
        该对象绑定到 name
        异常
        NamingException - 如果遇到命名异常
        从以下版本开始：
        1.6
        另请参见：
        doLookup(String) ， lookup(Name)

      • doLookup

        public static <T> T doLookup​(String name)
                      throws NamingException
        一种用于检索命名对象的静态方法。 详见doLookup(Name) 。
        参数类型
        T - 返回对象的类型
        参数
        name - 要查找的对象的名称
        结果
        对象绑定到 name
        异常
        NamingException - 如果遇到命名异常
        从以下版本开始：
        1.6

      • getDefaultInitCtx

        protected Context getDefaultInitCtx​()
                             throws NamingException
        通过调用NamingManager.getInitialContext()初始上下文并将其缓存在defaultInitCtx中。 设置gotDefault以便我们知道我们以前尝试过。
        结果
        非空高速缓存的初始上下文。
        异常
        NoInitialContextException - 如果找不到初始上下文。
        NamingException - 如果遇到命名异常。

      • getURLOrDefaultInitCtx

        protected Context getURLOrDefaultInitCtx​(String name)
                                  throws NamingException
        检索用于解析字符串名称name的上下文。 如果name名称是URL字符串，则尝试为其找到URL上下文。 如果没有找到，或者如果name不是URL字符串，则返回getDefaultInitCtx() 。

        有关子类应如何使用此方法的说明，请参阅getURLOrDefaultInitCtx（Name）。

        参数
        name - 获取上下文的非空名称。
        结果
        name的URL上下文或缓存的初始上下文。 结果不能为空。
        异常
        NoInitialContextException - 如果找不到初始上下文。
        NamingException - 遇到命名异常。
        另请参见：
        NamingManager.getURLContext(java.lang.String, java.util.Hashtable<?, ?>)

      • getURLOrDefaultInitCtx

        protected Context getURLOrDefaultInitCtx​(Name name)
                                  throws NamingException
        检索上下文以解析name 。 如果name名称的第一个组件是URL字符串，则尝试为其找到一个URL上下文。 如果没有找到，或者如果name的第一个组件不是URL字符串，则返回getDefaultInitCtx() 。

        当创建InitialContext的子类时，请使用以下方法。 定义一种使用此方法获取所需子类的初始上下文的新方法。 

         protected XXXContext getURLOrDefaultInitXXXCtx(Name name)
 throws NamingException {
  Context answer = getURLOrDefaultInitCtx(name);
  if (!(answer instanceof XXXContext)) {
    if (answer == null) {
      throw new NoInitialContextException();
    } else {
      throw new NotContextException("Not an XXXContext");
    }
  }
  return (XXXContext)answer;
 }
        当为子类中的新方法提供实现时，使用这个新定义的方法来获取初始上下文。 
         public Object XXXMethod1(Name name, ...) {
  throws NamingException {
    return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...);
 }
        参数
        name - 获取上下文的非空名称。
        结果
        name的URL上下文或缓存的初始上下文。 结果不能为空。
        异常
        NoInitialContextException - 如果找不到初始上下文。
        NamingException - 遇到命名异常。
        另请参见：
        NamingManager.getURLContext(java.lang.String, java.util.Hashtable<?, ?>)

      • unbind

        public void unbind​(Name name)
            throws NamingException
        描述从接口Context复制
        取消绑定命名对象。 从目标上下文中删除name的终端原子名称 - 由name的末端原子部分name 。

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

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

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

      • destroySubcontext

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

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

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

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

      • lookupLink

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

      • getNameParser

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

      • composeName

        public String composeName​(String name,
                          String prefix)
                   throws NamingException
        使用相对于该上下文的名称组合此上下文的名称。 由于初始上下文可能永远不会相对于自身以外的任何上下文命名，因此prefix参数的值必须为"" （ "" ）。
        Specified by:
        composeName在接口 Context
        参数
        name - 相对于此上下文的名称
        prefix - 此上下文相对于其祖先之一的名称
        结果
        组成为 prefix和 name
        异常
        NamingException - 如果遇到命名异常

      • composeName

        public Name composeName​(Name name,
                        Name prefix)
                 throws NamingException
        使用相对于该上下文的名称组合此上下文的名称。 由于初始上下文可能永远不会相对于自身以外的任何上下文命名，所以prefix参数的值必须为prefix 。
        Specified by:
        composeName在接口 Context
        参数
        name - 相对于此上下文的名称
        prefix - 此上下文相对于其祖先之一的名称
        结果
        组成 prefix和 name
        异常
        NamingException - 如果遇到命名异常
        另请参见：
        Context.composeName(String, String)

      • addToEnvironment

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

      • close

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

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

        Specified by:
        close在接口 Context
        异常
        NamingException - 如果遇到命名异常

      • getNameInNamespace

        public String getNameInNamespace​()
                          throws NamingException
        描述从接口Context复制
        在其自己的命名空间中检索此上下文的全名。

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

        Specified by:
        getNameInNamespace在接口 Context
        结果
        这个上下文的名称在自己的命名空间中; 从不为空
        异常
        OperationNotSupportedException - 如果命名系统没有全名的概念
        NamingException - 如果遇到命名异常