1. /*
  2. * @(#)EventContext.java 1.10 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.naming.event;
  8. import javax.naming.Name;
  9. import javax.naming.Context;
  10. import javax.naming.NamingException;
  11. /**
  12. * Contains methods for registering/deregistering listeners to be notified of
  13. * events fired when objects named in a context changes.
  14. *<p>
  15. *<h4>Target</h4>
  16. * The name parameter in the <tt>addNamingListener()</tt> methods is referred
  17. * to as the <em>target</em>. The target, along with the scope, identify
  18. * the object(s) that the listener is interested in.
  19. * It is possible to register interest in a target that does not exist, but
  20. * there might be limitations in the extent to which this can be
  21. * supported by the service provider and underlying protocol/service.
  22. *<p>
  23. * If a service only supports registration for existing
  24. * targets, an attempt to register for a nonexistent target
  25. * results in a <tt>NameNotFoundException</tt> being thrown as early as possible,
  26. * preferably at the time <tt>addNamingListener()</tt> is called, or if that is
  27. * not possible, the listener will receive the exception through the
  28. * <tt>NamingExceptionEvent</tt>.
  29. *<p>
  30. * Also, for service providers that only support registration for existing
  31. * targets, when the target that a listener has registered for is
  32. * subsequently removed from the namespace, the listener is notified
  33. * via a <tt>NamingExceptionEvent</tt> (containing a
  34. *<tt>NameNotFoundException</tt>).
  35. *<p>
  36. * An application can use the method <tt>targetMustExist()</tt> to check
  37. * whether a <tt>EventContext</tt> supports registration
  38. * of nonexistent targets.
  39. *<p>
  40. *<h4>Event Source</h4>
  41. * The <tt>EventContext</tt> instance on which you invoke the
  42. * registration methods is the <em>event source</em> of the events that are
  43. * (potentially) generated.
  44. * The source is <em>not necessarily</em> the object named by the target.
  45. * Only when the target is the empty name is the object named by the target
  46. * the source.
  47. * In other words, the target,
  48. * along with the scope parameter, are used to identify
  49. * the object(s) that the listener is interested in, but the event source
  50. * is the <tt>EventContext</tt> instance with which the listener
  51. * has registered.
  52. *<p>
  53. * For example, suppose a listener makes the following registration:
  54. *<blockquote><pre>
  55. * NamespaceChangeListener listener = ...;
  56. * src.addNamingListener("x", SUBTREE_SCOPE, listener);
  57. *</pre></blockquote>
  58. * When an object named "x/y" is subsequently deleted, the corresponding
  59. * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
  60. *<blockquote><pre>
  61. * evt.getEventContext() == src
  62. * evt.getOldBinding().getName().equals("x/y")
  63. *</pre></blockquote>
  64. *<p>
  65. * Furthermore, listener registration/deregistration is with
  66. * the <tt>EventContext</tt>
  67. * <em>instance</em>, and not with the corresponding object in the namespace.
  68. * If the program intends at some point to remove a listener, then it needs to
  69. * keep a reference to the <tt>EventContext</tt> instance on
  70. * which it invoked <tt>addNamingListener()</tt> (just as
  71. * it needs to keep a reference to the listener in order to remove it
  72. * later). It cannot expect to do a <tt>lookup()</tt> and get another instance of
  73. * a <tt>EventContext</tt> on which to perform the deregistration.
  74. *<h4>Lifetime of Registration</h4>
  75. * A registered listener becomes deregistered when:
  76. *<ul>
  77. *<li>It is removed using <tt>removeNamingListener()</tt>.
  78. *<li>An exception is thrown while collecting information about the events.
  79. * That is, when the listener receives a <tt>NamingExceptionEvent</tt>.
  80. *<li><tt>Context.close()</tt> is invoked on the <tt>EventContext</tt>
  81. * instance with which it has registered.
  82. </ul>
  83. * Until that point, a <tt>EventContext</tt> instance that has outstanding
  84. * listeners will continue to exist and be maintained by the service provider.
  85. *
  86. *<h4>Listener Implementations</h4>
  87. * The registration/deregistration methods accept an instance of
  88. * <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>
  89. * for different of event types of <tt>NamingEvent</tt>.
  90. * For example, the <tt>ObjectChangeListener</tt>
  91. * interface is for the <tt>NamingEvent.OBJECT_CHANGED</tt> event type.
  92. * To register interest in multiple event types, the listener implementation
  93. * should implement multiple <tt>NamingListener</tt> subinterfaces and use a
  94. * single invocation of <tt>addNamingListener()</tt>.
  95. * In addition to reducing the number of method calls and possibly the code size
  96. * of the listeners, this allows some service providers to optimize the
  97. * registration.
  98. *
  99. *<h4>Threading Issues</h4>
  100. *
  101. * Like <tt>Context</tt> instances in general, instances of
  102. * <tt>EventContext</tt> are not guaranteed to be thread-safe.
  103. * Care must be taken when multiple threads are accessing the same
  104. * <tt>EventContext</tt> concurrently.
  105. * See the
  106. * <a href=package-summary.html#THREADING>package description</a>
  107. * for more information on threading issues.
  108. *
  109. * @author Rosanna Lee
  110. * @author Scott Seligman
  111. * @version 1.10 03/01/23
  112. * @since 1.3
  113. */
  114. public interface EventContext extends Context {
  115. /**
  116. * Constant for expressing interest in events concerning the object named
  117. * by the target.
  118. *<p>
  119. * The value of this constant is <tt>0</tt>.
  120. */
  121. public final static int OBJECT_SCOPE = 0;
  122. /**
  123. * Constant for expressing interest in events concerning objects
  124. * in the context named by the target,
  125. * excluding the context named by the target.
  126. *<p>
  127. * The value of this constant is <tt>1</tt>.
  128. */
  129. public final static int ONELEVEL_SCOPE = 1;
  130. /**
  131. * Constant for expressing interest in events concerning objects
  132. * in the subtree of the object named by the target, including the object
  133. * named by the target.
  134. *<p>
  135. * The value of this constant is <tt>2</tt>.
  136. */
  137. public final static int SUBTREE_SCOPE = 2;
  138. /**
  139. * Adds a listener for receiving naming events fired
  140. * when the object(s) identified by a target and scope changes.
  141. *
  142. * The event source of those events is this context. See the
  143. * class description for a discussion on event source and target.
  144. * See the descriptions of the constants <tt>OBJECT_SCOPE</tt>,
  145. * <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how
  146. * <tt>scope</tt> affects the registration.
  147. *<p>
  148. * <tt>target</tt> needs to name a context only when <tt>scope</tt> is
  149. * <tt>ONELEVEL_SCOPE</tt>.
  150. * <tt>target</tt> may name a non-context if <tt>scope</tt> is either
  151. * <tt>OBJECT_SCOPE</tt> or <tt>SUBTREE_SCOPE</tt>. Using
  152. * <tt>SUBTREE_SCOPE</tt> for a non-context might be useful,
  153. * for example, if the caller does not know in advance whether <tt>target</tt>
  154. * is a context and just wants to register interest in the (possibly
  155. * degenerate subtree) rooted at <tt>target</tt>.
  156. *<p>
  157. * When the listener is notified of an event, the listener may
  158. * in invoked in a thread other than the one in which
  159. * <tt>addNamingListener()</tt> is executed.
  160. * Care must be taken when multiple threads are accessing the same
  161. * <tt>EventContext</tt> concurrently.
  162. * See the
  163. * <a href=package-summary.html#THREADING>package description</a>
  164. * for more information on threading issues.
  165. *
  166. * @param target A nonnull name to be resolved relative to this context.
  167. * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
  168. * <tt>SUBTREE_SCOPE</tt>.
  169. * @param l The nonnull listener.
  170. * @exception NamingException If a problem was encountered while
  171. * adding the listener.
  172. * @see #removeNamingListener
  173. */
  174. void addNamingListener(Name target, int scope, NamingListener l)
  175. throws NamingException;
  176. /**
  177. * Adds a listener for receiving naming events fired
  178. * when the object named by the string target name and scope changes.
  179. *
  180. * See the overload that accepts a <tt>Name</tt> for details.
  181. *
  182. * @param target The nonnull string name of the object resolved relative
  183. * to this context.
  184. * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
  185. * <tt>SUBTREE_SCOPE</tt>.
  186. * @param l The nonnull listener.
  187. * @exception NamingException If a problem was encountered while
  188. * adding the listener.
  189. * @see #removeNamingListener
  190. */
  191. void addNamingListener(String target, int scope, NamingListener l)
  192. throws NamingException;
  193. /**
  194. * Removes a listener from receiving naming events fired
  195. * by this <tt>EventContext</tt>.
  196. * The listener may have registered more than once with this
  197. * <tt>EventContext</tt>, perhaps with different target/scope arguments.
  198. * After this method is invoked, the listener will no longer
  199. * receive events with this <tt>EventContext</tt> instance
  200. * as the event source (except for those events already in the process of
  201. * being dispatched).
  202. * If the listener was not, or is no longer, registered with
  203. * this <tt>EventContext</tt> instance, this method does not do anything.
  204. *
  205. * @param l The nonnull listener.
  206. * @exception NamingException If a problem was encountered while
  207. * removing the listener.
  208. * @see #addNamingListener
  209. */
  210. void removeNamingListener(NamingListener l) throws NamingException;
  211. /**
  212. * Determines whether a listener can register interest in a target
  213. * that does not exist.
  214. *
  215. * @return true if the target must exist; false if the target need not exist.
  216. * @exception NamingException If the context's behavior in this regard cannot
  217. * be determined.
  218. */
  219. boolean targetMustExist() throws NamingException;
  220. }