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

Interface EventContext

  • All Superinterfaces:
    Context
    All Known Subinterfaces:
    EventDirContext 

    public interface EventContext
extends Context
    包含用于注册/注销侦听器的方法，以通知在上下文中命名的对象发生变化时触发的事件。

    目标

    addNamingListener()方法中的name参数被称为目标 。 目标与范围一起确定侦听器感兴趣的对象。可以注册对不存在的目标的兴趣，但是在可以支持的程度上可能会受到限制服务提供商和底层协议/服务。

    如果服务仅支持对现有目标的注册，则尝试注册不存在的目标会导致尽可能早地抛出NameNotFoundException ，最好在调用addNamingListener() ，或者如果不可能，则侦听器将收到异常通过NamingExceptionEvent 。

    此外，对于仅支持现有目标注册的服务提供商，当侦听器注册的目标随后从命名空间中删除时，通过NamingExceptionEvent （包含NameNotFoundException ）通知收听者。

    应用程序可以使用方法targetMustExist()来检查EventContext是否支持注册不存在的目标。

    事件来源

    您调用注册方法的EventContext实例是（可能）生成的事件的事件源 。 源不一定是目标命名的对象。 只有当目标是空的名称是目标命名的对象的源。 换句话说，目标与范围参数一起用于标识侦听器感兴趣的对象，但事件源是侦听器已注册的EventContext实例。

    例如，假设一个监听器进行以下注册： 

          NamespaceChangeListener listener = ...;
      src.addNamingListener("x", SUBTREE_SCOPE, listener);
    当名为“x / y”的对象随后被删除时，对应的NamingEvent （ evt ）必须包含： 
          evt.getEventContext() == src
      evt.getOldBinding().getName().equals("x/y")

    此外，监听器注册/注销是与EventContext 实例 ，而不是与命名空间中的相应对象。 如果程序在某些时候打算移除侦听器，那么它需要保持在一个参考EventContext其所援引实例addNamingListener() （就像它需要保持对侦听器的引用，以便以后进行删除）。 它不能期望做一个lookup()并获得另一个EventContext实例来执行注销。

    注册终身

    注册听众在以下情况下注销：
    • 它使用removeNamingListener()删除。
    • 收集有关事件的信息时抛出异常。 也就是说，当听众收到一个NamingExceptionEvent 。
    • Context.close()在已注册的EventContext实例上被调用。
    在此之前，具有优秀侦听器的EventContext实例将继续存在并由服务提供商维护。

    听众实现

    注册/注销方法接受NamingListener的实例。 对于NamingListener的不同事件类型，有NamingEvent子接口。 例如， ObjectChangeListener接口是NamingEvent.OBJECT_CHANGED事件类型。 要注册对多种事件类型的兴趣，侦听器实现应该实现多个NamingListener子接口，并使用单个调用addNamingListener() 。 除了减少方法调用的次数和可能的监听器的代码大小之外，这允许一些服务提供商优化注册。

    线程问题

    像Context一般情况下，的实例EventContext不能保证是线程安全的。 当多个线程同时访问EventContext时，必须小心。 有关线程问题的更多信息，请参阅package description 。
    从以下版本开始：
    1.3

    • 字段详细信息

      • OBJECT_SCOPE

        static final int OBJECT_SCOPE
        用于表示对由目标命名的对象的事件感兴趣的常数。

        此常数的值为0 。

        另请参见：
        Constant Field Values

      • ONELEVEL_SCOPE

        static final int ONELEVEL_SCOPE
        用于表达对目标命名的上下文中关于对象的事件的兴趣的常数，不包括目标命名的上下文。

        该常数的值为1 。

        另请参见：
        Constant Field Values

      • SUBTREE_SCOPE

        static final int SUBTREE_SCOPE
        用于表示对由目标命名的对象的子树中的对象的事件感兴趣的常数，包括由目标命名的对象。

        该常数的值为2 。

        另请参见：
        Constant Field Values

    • 方法详细信息

      • addNamingListener

        void addNamingListener​(Name target,
                       int scope,
                       NamingListener l)
                throws NamingException
        添加一个侦听器，用于接收由目标和范围标识的对象更改时触发的命名事件。 这些事件的事件来源是这个上下文。 有关事件源和目标的讨论，请参阅类描述。 见常的描述OBJECT_SCOPE ， ONELEVEL_SCOPE ，并SUBTREE_SCOPE怎么看scope影响登记。

        target仅在scope为ONELEVEL_SCOPE target需要命名上下文。 如果scope是OBJECT_SCOPE或SUBTREE_SCOPE则target可能会命名为非上下文。 对于非上下文使用SUBTREE_SCOPE可能是有用的，例如，如果呼叫者不能预先知道target是否是上下文，并且仅想注册根据target的（可能是退化的子树）的target 。

        当侦听器被通知事件时，侦听器可以被执行的线程中除了执行addNamingListener()之外的线程中被调用。 当多个线程同时访问EventContext时，必须小心。 有关线程问题的更多信息，请参阅package description 。

        参数
        target - 相对于此上下文解析的非 target名称。
        scope -一个 OBJECT_SCOPE ， ONELEVEL_SCOPE ，或 SUBTREE_SCOPE 。
        l - 非正常听众。
        异常
        NamingException - 如果在添加侦听器时遇到问题。
        另请参见：
        removeNamingListener(javax.naming.event.NamingListener)

      • addNamingListener

        void addNamingListener​(String target,
                       int scope,
                       NamingListener l)
                throws NamingException
        添加一个侦听器，用于接收由字符串目标名称和范围指定的对象更改时触发的命名事件。 有关详细信息，请参阅接收Name的重载。
        参数
        target - 相对于此上下文解析的对象的非 target字符串名称。
        scope -一个 OBJECT_SCOPE ， ONELEVEL_SCOPE ，或 SUBTREE_SCOPE 。
        l - 非正常听众。
        异常
        NamingException - 如果在添加侦听器时遇到问题。
        另请参见：
        removeNamingListener(javax.naming.event.NamingListener)

      • removeNamingListener

        void removeNamingListener​(NamingListener l)
                   throws NamingException
        从接收到EventContext触发的命名事件中删除一个监听EventContext 。 收听者可能已经使用此EventContext注册了EventContext ，也许具有不同的目标/范围参数。 调用此方法后，侦听器将不再接收事件，而此事件源为EventContext （除了正在发送的事件之外）。 如果监听器没有或已经不再注册了这个EventContext实例，这个方法不会做任何事情。
        参数
        l - 非正常听众。
        异常
        NamingException - 如果在删除侦听器时遇到问题。
        另请参见：
        addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener)

      • targetMustExist

        boolean targetMustExist​()
                 throws NamingException
        确定侦听器是否可以注册不存在的目标的兴趣。
        结果
        如果目标必须存在，则为true; 如果目标不需要，则为false。
        异常
        NamingException - 如果上下文在这方面的行为无法确定。