模块  java.naming
软件包  javax.naming.event

Interface EventContext

  • All Superinterfaces:
    Context
    All Known Subinterfaces:
    EventDirContext 
    public interface EventContext
extends Context
    包含注册/取消注册侦听器的方法，以便在上下文中命名的对象发生更改时触发事件。

    目标

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

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

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

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

    事件来源

    您调用注册方法的EventContext实例是（可能）生成的事件的事件源 。 源不一定是目标指定的对象。 仅当目标是空名称时，才是目标由源命名的对象。 换句话说，目标与scope参数一起用于标识侦听器感兴趣的对象，但事件源是侦听器已注册的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 。

        另请参见：
        常数字段值

      • ONELEVEL_SCOPE

        static final int ONELEVEL_SCOPE
        用于表示对目标指定的上下文中的对象的事件感兴趣的常量，不包括目标指定的上下文。

        此常量的值为1 。

        另请参见：
        常数字段值

      • SUBTREE_SCOPE

        static final int SUBTREE_SCOPE
        表示对目标指定的对象的子树中的对象的事件感兴趣的常量，包括目标命名的对象。

        此常量的值为2 。

        另请参见：
        常数字段值

    • 方法详细信息

      • addNamingListener

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

        target仅在scope为ONELEVEL_SCOPE target需要命名上下文。 target如果可以命名一个非上下文scope要么是OBJECT_SCOPE或SUBTREE_SCOPE 。 将SUBTREE_SCOPE用于非上下文可能很有用，例如，如果调用者事先不知道target是否是上下文并且只想注册对以target根的（可能是简并子树）的target 。

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

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

      • removeNamingListener

        void removeNamingListener​(NamingListener l)
                   throws NamingException
        从接收到此EventContext触发的命名事件中删除侦听EventContext 。 监听器可能已使用此EventContext多次注册，可能具有不同的目标/范围参数。 调用此方法后，侦听器将不再接收使用此EventContext实例作为事件源的事件（已分派过程中的事件除外）。 如果侦听器未注册或不再注册此EventContext实例，则此方法不执行任何操作。
        参数
        l - 非 l的侦听器。
        异常
        NamingException - 如果在删除侦听器时遇到问题。
        另请参见：
        addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener)

      • targetMustExist

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