Module java.naming
Package javax.naming.event

Interface EventContext

所有超接口:
Context
所有已知子接口:
EventDirContext
public interface EventContext extends Context
包含用于注册/取消注册侦听器以便在上下文中命名的对象发生更改时通知的方法。

目标

addNamingListener() 方法中的名称参数被称为目标。目标与范围一起标识出侦听器感兴趣的对象。可以注册对不存在的目标的兴趣，但是服务提供程序和底层协议/服务支持此操作的程度可能会有限制。

如果服务仅支持对现有目标进行注册，那么尝试为不存在的目标注册将导致尽早抛出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 实例进行的，而不是与命名空间中的相应对象进行的。如果程序打算在某个时刻删除侦听器，则需要保留对调用addNamingListener()的EventContext实例的引用（就像需要保留对侦听器的引用以便稍后删除一样）。它不能期望执行lookup()并获得另一个EventContext实例，以便执行取消注册。

注册的生命周期

当以下情况发生时，已注册的侦听器将被取消注册：
  • 使用removeNamingListener()将其移除。
  • 在收集有关事件信息时抛出异常。也就是说，当侦听器收到NamingExceptionEvent时。
  • 在已注册的EventContext实例上调用Context.close()。
在那之前，具有未完成侦听器的EventContext实例将继续存在并由服务提供程序维护。

侦听器实现

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

线程问题

与一般Context实例一样，EventContext实例不能保证是线程安全的。当多个线程同时访问同一EventContext时，必须小心。有关线程问题的更多信息，请参阅包描述。
自版本:
1.3

  • Field Details

    • OBJECT_SCOPE

      static final int OBJECT_SCOPE
      表达对涉及目标命名对象的事件感兴趣的常量。

      此常量的值为0。

      另请参阅:

    • ONELEVEL_SCOPE

      static final int ONELEVEL_SCOPE
      表达对涉及目标命名上下文中的对象的事件感兴趣的常量。

      此常量的值为1。

      另请参阅:

    • SUBTREE_SCOPE

      static final int SUBTREE_SCOPE
      表达对涉及目标命名对象的子树中的对象的事件感兴趣的常量。

      此常量的值为2。

      另请参阅:

  • Method Details

    • addNamingListener

      void addNamingListener(Name target, int scope, NamingListener l) throws NamingException
      添加侦听器，以便在由目标和范围标识的对象更改时接收命名事件。这些事件的事件源是此上下文。有关事件源和目标的讨论，请参阅类描述。请参阅常量OBJECT_SCOPE、ONELEVEL_SCOPE和SUBTREE_SCOPE的描述，了解scope如何影响注册。

      当scope为ONELEVEL_SCOPE时，target需要命名一个上下文。如果scope为OBJECT_SCOPE或SUBTREE_SCOPE，则target可以命名非上下文。例如，对于非上下文使用SUBTREE_SCOPE可能很有用，例如，如果调用者事先不知道target是否为上下文，只想注册对以target为根的（可能退化的子树）的兴趣。

      当侦听器收到事件通知时，侦听器可能在与执行addNamingListener()的线程不同的线程中被调用。当多个线程同时访问同一EventContext时，必须小心。有关线程问题的更多信息，请参阅包描述。

      参数:
      target - 一个非空名称，将相对于此上下文解析。
      scope - OBJECT_SCOPE、ONELEVEL_SCOPE或SUBTREE_SCOPE之一。
      l - 非空侦听器。
      抛出:
      NamingException - 如果添加侦听器时遇到问题。
      另请参阅:

    • addNamingListener

      void addNamingListener(String target, int scope, NamingListener l) throws NamingException
      添加侦听器，以便在命名为字符串目标名称和范围更改时接收命名事件。有关接受Name的重载的详细信息，请参阅。
      参数:
      target - 相对于此上下文解析的非空字符串名称。
      scope - OBJECT_SCOPE、ONELEVEL_SCOPE或SUBTREE_SCOPE之一。
      l - 非空侦听器。
      抛出:
      NamingException - 如果添加侦听器时遇到问题。
      另请参阅:

    • removeNamingListener

      void removeNamingListener(NamingListener l) throws NamingException
      从此EventContext中删除接收命名事件的侦听器。侦听器可能已经使用不同的目标/范围参数多次注册了此EventContext。调用此方法后，侦听器将不再接收此EventContext实例作为事件源的事件（除了那些已经在被分派过程中的事件）。如果侦听器未注册或不再注册到此EventContext实例，则此方法不执行任何操作。
      参数:
      l - 非空侦听器。
      抛出:
      NamingException - 如果移除侦听器时遇到问题。
      另请参阅:

    • targetMustExist

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