javax.naming.event

接口
类

javax.naming.event
接口 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

字段摘要
static int OBJECT_SCOPE
          该常量用来表示对涉及目标指定对象的事件感兴趣。
static int ONELEVEL_SCOPE
          该常量用来表示对涉及目标指定上下文中对象的事件感兴趣，不包括目标指定的上下文。
static int SUBTREE_SCOPE
          该常量用来表示对涉及目标指定对象的子树中对象的事件感兴趣，包括目标指定的对象。
 
从接口 javax.naming.Context 继承的字段
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
 
方法摘要
 void addNamingListener(Name target, int scope, NamingListener l)
          添加接收命名事件的侦听器，这些事件在目标和范围所标识的对象发生更改时触发。
 void addNamingListener(String target, int scope, NamingListener l)
          添加接收命名事件的侦听器，这些事件在目标名称和范围指定的对象发生更改时触发。
 void removeNamingListener(NamingListener l)
          从此 EventContext 触发的接收命名事件中移除一个侦听器。
 boolean targetMustExist()
          确定侦听器是否可以注册不存在的感兴趣目标。
 
从接口 javax.naming.Context 继承的方法
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
 

字段详细信息

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 时需要指定上下文，如果 scope 既不是 OBJECT_SCOPE 也不是 SUBTREE_SCOPE，则 target 可能指定非上下文。例如，如果调用者预先不知道 target 是否是上下文，而只想注册以 target 为根的（可能退化的）子树，则使用非上下文的 SUBTREE_SCOPE 可能很有用。

当侦听器收到事件通知时，侦听器可以在没有执行 addNamingListener() 的某个线程中调用。当多个线程并发访问同一个 EventContext 时必须谨慎。有关线程问题的更多信息，请参阅包描述。

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

addNamingListener

void addNamingListener(String target,
                       int scope,
                       NamingListener l)
                       throws NamingException
添加接收命名事件的侦听器，这些事件在目标名称和范围指定的对象发生更改时触发。 有关详细信息，请参阅接受 Name 参数的重载方法。

参数：
target - 相对于此上下文解析的对象的非 null 字符串名称。
scope - OBJECT_SCOPE、 ONELEVEL_SCOPE 或 SUBTREE_SCOPE 之一。
l - 非 null 侦听器。
抛出：
NamingException - 如果在添加侦听器时遇到问题。
另请参见：
removeNamingListener(javax.naming.event.NamingListener)

removeNamingListener

void removeNamingListener(NamingListener l)
                          throws NamingException
从此 EventContext 触发的接收命名事件中移除一个侦听器。该侦听器可能在此 EventContext 中注册过一次以上，并且可能使用不同的目标/范围参数进行。调用此方法后，侦听器将不再使用作为事件源的此 EventContext 实例接收事件（已经在指派过程中那些事件除外）。如果侦听器不（或不再）在此 EventContext 实例中注册，则此方法不执行任何操作。

参数：
l - 非 null 侦听器。
抛出：
NamingException - 如果在移除侦听器时遇到问题。
另请参见：
addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener)

targetMustExist

boolean targetMustExist()
                        throws NamingException
确定侦听器是否可以注册不存在的感兴趣目标。

返回：
如果目标存在，则返回 true；如果目标不必存在，则返回 false。
抛出：
NamingException - 如果无法确定上下文的这一行为。