1. /*
  2. * @(#)NamingEvent.java 1.8 01/02/09
  3. *
  4. * Copyright 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package javax.naming.event;
  11. import javax.naming.Binding;
  12. /**
  13. * This class represents an event fired by a naming/directory service.
  14. *<p>
  15. * The <tt>NamingEvent</tt>'s state consists of
  16. * <ul>
  17. * <li>The event source: the <tt>EventContext</tt> which fired this event.
  18. * <li>The event type.
  19. * <li>The new binding: information about the object after the change.
  20. * <li>The old binding: information about the object before the change.
  21. * <li>Change information: information about the change
  22. * that triggered this event; usually service provider-specific or server-specific
  23. * information.
  24. * </ul>
  25. * <p>
  26. * Note that the event source is always the same <tt>EventContext</tt>
  27. * <em>instance</em> that the listener has registered with.
  28. * Furthermore, the names of the bindings in
  29. * the <tt>NamingEvent</tt> are always relative to that instance.
  30. * For example, suppose a listener makes the following registration:
  31. *<blockquote><pre>
  32. * NamespaceChangeListener listener = ...;
  33. * src.addNamingListener("x", SUBTREE_SCOPE, listener);
  34. *</pre></blockquote>
  35. * When an object named "x/y" is subsequently deleted, the corresponding
  36. * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
  37. *<blockquote><pre>
  38. * evt.getEventContext() == src
  39. * evt.getOldBinding().getName().equals("x/y")
  40. *</pre></blockquote>
  41. *
  42. * Care must be taken when multiple threads are accessing the same
  43. * <tt>EventContext</tt> concurrently.
  44. * See the
  45. * <a href=package-summary.html#THREADING>package description</a>
  46. * for more information on threading issues.
  47. *
  48. * @author Rosanna Lee
  49. * @author Scott Seligman
  50. * @version 1.8 01/02/09
  51. *
  52. * @see NamingListener
  53. * @see EventContext
  54. * @since 1.3
  55. */
  56. public class NamingEvent extends java.util.EventObject {
  57. /**
  58. * Naming event type for indicating that a new object has been added.
  59. * The value of this constant is <tt>0</tt>.
  60. */
  61. public static final int OBJECT_ADDED = 0;
  62. /**
  63. * Naming event type for indicating that an object has been removed.
  64. * The value of this constant is <tt>1</tt>.
  65. */
  66. public static final int OBJECT_REMOVED = 1;
  67. /**
  68. * Naming event type for indicating that an object has been renamed.
  69. * Note that some services might fire multiple events for a single
  70. * logical rename operation. For example, the rename operation might
  71. * be implemented by adding a binding with the new name and removing
  72. * the old binding.
  73. *<p>
  74. * The old/new binding in <tt>NamingEvent</tt> may be null if the old
  75. * name or new name is outside of the scope for which the listener
  76. * has registered.
  77. *<p>
  78. * When an interior node in the namespace tree has been renamed, the
  79. * topmost node which is part of the listener's scope should used to generate
  80. * a rename event. The extent to which this can be supported is
  81. * provider-specific. For example, a service might generate rename
  82. * notifications for all descendants of the changed interior node and the
  83. * corresponding provider might not be able to prevent those
  84. * notifications from being propagated to the listeners.
  85. *<p>
  86. * The value of this constant is <tt>2</tt>.
  87. */
  88. public static final int OBJECT_RENAMED = 2;
  89. /**
  90. * Naming event type for indicating that an object has been changed.
  91. * The changes might include the object's attributes, or the object itself.
  92. * Note that some services might fire multiple events for a single
  93. * modification. For example, the modification might
  94. * be implemented by first removing the old binding and adding
  95. * a new binding containing the same name but a different object.
  96. *<p>
  97. * The value of this constant is <tt>3</tt>.
  98. */
  99. public static final int OBJECT_CHANGED = 3;
  100. /**
  101. * Contains information about the change that generated this event.
  102. * @serial
  103. */
  104. protected Object changeInfo;
  105. /**
  106. * Contains the type of this event.
  107. * @see #OBJECT_ADDED
  108. * @see #OBJECT_REMOVED
  109. * @see #OBJECT_RENAMED
  110. * @see #OBJECT_CHANGED
  111. * @serial
  112. */
  113. protected int type;
  114. /**
  115. * Contains information about the object before the change.
  116. * @serial
  117. */
  118. protected Binding oldBinding;
  119. /**
  120. * Contains information about the object after the change.
  121. * @serial
  122. */
  123. protected Binding newBinding;
  124. /**
  125. * Constructs an instance of <tt>NamingEvent</tt>.
  126. *<p>
  127. * The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative
  128. * to the event source <tt>source</tt>.
  129. *
  130. * For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.
  131. * For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.
  132. * For an <tt>OBJECT_CHANGED</tt> event type, <tt>newBd</tt> and
  133. * <tt>oldBd</tt> must not be null. For an <tt>OBJECT_RENAMED</tt> event type,
  134. * one of <tt>newBd</tt> or <tt>oldBd</tt> may be null if the new or old
  135. * binding is outside of the scope for which the listener has registered.
  136. *
  137. * @param source The non-null context that fired this event.
  138. * @param type The type of the event.
  139. * @param newBd A possibly null binding before the change. See method description.
  140. * @param oldBd A possibly null binding after the change. See method description.
  141. * @param changeInfo A possibly null object containing information about the change.
  142. * @see #OBJECT_ADDED
  143. * @see #OBJECT_REMOVED
  144. * @see #OBJECT_RENAMED
  145. * @see #OBJECT_CHANGED
  146. */
  147. public NamingEvent(EventContext source, int type,
  148. Binding newBd, Binding oldBd, Object changeInfo) {
  149. super(source);
  150. this.type = type;
  151. oldBinding = oldBd;
  152. newBinding = newBd;
  153. this.changeInfo = changeInfo;
  154. }
  155. /**
  156. * Returns the type of this event.
  157. * @return The type of this event.
  158. * @see #OBJECT_ADDED
  159. * @see #OBJECT_REMOVED
  160. * @see #OBJECT_RENAMED
  161. * @see #OBJECT_CHANGED
  162. */
  163. public int getType() {
  164. return type;
  165. }
  166. /**
  167. * Retrieves the event source that fired this event.
  168. * This returns the same object as <tt>EventObject.getSource()</tt>.
  169. *<p>
  170. * If the result of this method is used to access the
  171. * event source, for example, to look up the object or get its attributes,
  172. * then it needs to be locked because implementations of <tt>Context</tt>
  173. * are not guaranteed to be thread-safe
  174. * (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).
  175. * See the
  176. * <a href=package-summary.html#THREADING>package description</a>
  177. * for more information on threading issues.
  178. *
  179. * @return The non-null context that fired this event.
  180. */
  181. public EventContext getEventContext() {
  182. return (EventContext)getSource();
  183. }
  184. /**
  185. * Retrieves the binding of the object before the change.
  186. *<p>
  187. * The binding must be nonnull if the object existed before the change
  188. * relative to the source context (<tt>getEventContext()</tt>).
  189. * That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and
  190. * <tt>OBJECT_CHANGED</tt>.
  191. * For <tt>OBJECT_RENAMED</tt>, it is null if the object before the rename
  192. * is outside of the scope for which the listener has registered interest;
  193. * it is nonnull if the object is inside the scope before the rename.
  194. *<p>
  195. * The name in the binding is to be resolved relative
  196. * to the event source <tt>getEventContext()</tt>.
  197. * The object returned by <tt>Binding.getObject()</tt> may be null if
  198. * such information is unavailable.
  199. *
  200. * @return The possibly null binding of the object before the change.
  201. */
  202. public Binding getOldBinding() {
  203. return oldBinding;
  204. }
  205. /**
  206. * Retrieves the binding of the object after the change.
  207. *<p>
  208. * The binding must be nonnull if the object existed after the change
  209. * relative to the source context (<tt>getEventContext()</tt>).
  210. * That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and
  211. * <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,
  212. * it is null if the object after the rename is outside the scope for
  213. * which the listener registered interest; it is nonnull if the object
  214. * is inside the scope after the rename.
  215. *<p>
  216. * The name in the binding is to be resolved relative
  217. * to the event source <tt>getEventContext()</tt>.
  218. * The object returned by <tt>Binding.getObject()</tt> may be null if
  219. * such information is unavailable.
  220. *
  221. * @return The possibly null binding of the object after the change.
  222. */
  223. public Binding getNewBinding() {
  224. return newBinding;
  225. }
  226. /**
  227. * Retrieves the change information for this event.
  228. * The value of the change information is service-specific. For example,
  229. * it could be an ID that identifies the change in a change log on the server.
  230. *
  231. * @return The possibly null change information of this event.
  232. */
  233. public Object getChangeInfo() {
  234. return changeInfo;
  235. }
  236. /**
  237. * Invokes the appropriate listener method on this event.
  238. * The default implementation of
  239. * this method handles the following event types:
  240. * <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>,
  241. * <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.
  242. *<p>
  243. * The listener method is executed in the same thread
  244. * as this method. See the
  245. * <a href=package-summary.html#THREADING>package description</a>
  246. * for more information on threading issues.
  247. * @param listener The nonnull listener.
  248. */
  249. public void dispatch(NamingListener listener) {
  250. switch (type) {
  251. case OBJECT_ADDED:
  252. ((NamespaceChangeListener)listener).objectAdded(this);
  253. break;
  254. case OBJECT_REMOVED:
  255. ((NamespaceChangeListener)listener).objectRemoved(this);
  256. break;
  257. case OBJECT_RENAMED:
  258. ((NamespaceChangeListener)listener).objectRenamed(this);
  259. break;
  260. case OBJECT_CHANGED:
  261. ((ObjectChangeListener)listener).objectChanged(this);
  262. break;
  263. }
  264. }
  265. private static final long serialVersionUID = -7126752885365133499L;
  266. }