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. 

  11. package javax.naming.event;

  12. 

  13. import javax.naming.Binding;

  14. 

  15. /**

  16.   * This class represents an event fired by a naming/directory service.

  17.   *<p>

  18.   * The <tt>NamingEvent</tt>'s state consists of

  19.   * <ul>

  20.   * <li>The event source: the <tt>EventContext</tt> which fired this event.

  21.   * <li>The event type.

  22.   * <li>The new binding: information about the object after the change.

  23.   * <li>The old binding: information about the object before the change.

  24.   * <li>Change information: information about the change

  25.   * that triggered this event; usually service provider-specific or server-specific

  26.   * information.

  27.   * </ul>

  28.   * <p>

  29.   * Note that the event source is always the same <tt>EventContext</tt>

  30.   * <em>instance</em>  that the listener has registered with.  

  31.   * Furthermore, the names of the bindings in

  32.   * the <tt>NamingEvent</tt> are always relative to that instance.

  33.   * For example, suppose a listener makes the following registration:

  34.   *<blockquote><pre>

  35.   *	NamespaceChangeListener listener = ...;

  36.   *	src.addNamingListener("x", SUBTREE_SCOPE, listener);

  37.   *</pre></blockquote>

  38.   * When an object named "x/y" is subsequently deleted, the corresponding

  39.   * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:

  40.   *<blockquote><pre>

  41.   *	evt.getEventContext() == src

  42.   *	evt.getOldBinding().getName().equals("x/y")

  43.   *</pre></blockquote>

  44.   *

  45.   * Care must be taken when multiple threads are accessing the same

  46.   * <tt>EventContext</tt> concurrently.

  47.   * See the

  48.   * <a href=package-summary.html#THREADING>package description</a>

  49.   * for more information on threading issues.

  50.   * 

  51.   * @author Rosanna Lee

  52.   * @author Scott Seligman

  53.   * @version 1.8 01/02/09

  54.   *

  55.   * @see NamingListener

  56.   * @see EventContext

  57.   * @since 1.3

  58.   */

  59. public class NamingEvent extends java.util.EventObject {

  60.     /**

  61.      * Naming event type for indicating that a new object has been added.

  62.      * The value of this constant is <tt>0</tt>.

  63.      */

  64.     public static final int OBJECT_ADDED = 0;

  65. 

  66.     /**

  67.      * Naming event type for indicating that an object has been removed.

  68.      * The value of this constant is <tt>1</tt>.

  69.      */

  70.     public static final int OBJECT_REMOVED = 1;

  71. 

  72.     /**

  73.      * Naming event type for indicating that an object has been renamed.

  74.      * Note that some services might fire multiple events for a single

  75.      * logical rename operation. For example, the rename operation might

  76.      * be implemented by adding a binding with the new name and removing

  77.      * the old binding.

  78.      *<p>

  79.      * The old/new binding in <tt>NamingEvent</tt> may be null if the old

  80.      * name or new name is outside of the scope for which the listener 

  81.      * has registered.

  82.      *<p>

  83.      * When an interior node in the namespace tree has been renamed, the

  84.      * topmost node which is part of the listener's scope should used to generate

  85.      * a rename event. The extent to which this can be supported is

  86.      * provider-specific. For example, a service might generate rename

  87.      * notifications for all descendants of the changed interior node and the

  88.      * corresponding provider might not be able to prevent those

  89.      * notifications from being propagated to the listeners.

  90.      *<p>

  91.      * The value of this constant is <tt>2</tt>.

  92.      */

  93.     public static final int OBJECT_RENAMED = 2;

  94. 

  95.     /**

  96.      * Naming event type for indicating that an object has been changed.

  97.      * The changes might include the object's attributes, or the object itself.

  98.      * Note that some services might fire multiple events for a single

  99.      * modification. For example, the modification might

  100.      * be implemented by first removing the old binding and adding

  101.      * a new binding containing the same name but a different object.

  102.      *<p>

  103.      * The value of this constant is <tt>3</tt>.

  104.      */

  105.     public static final int OBJECT_CHANGED = 3;

  106.     

  107.     /**

  108.      * Contains information about the change that generated this event.

  109.      * @serial

  110.      */

  111.     protected Object changeInfo;

  112.     

  113.     /**

  114.      * Contains the type of this event.

  115.      * @see #OBJECT_ADDED

  116.      * @see #OBJECT_REMOVED

  117.      * @see #OBJECT_RENAMED

  118.      * @see #OBJECT_CHANGED

  119.      * @serial

  120.      */

  121.     protected int type;

  122. 

  123.     /**

  124.      * Contains information about the object before the change.

  125.      * @serial

  126.      */

  127.     protected Binding oldBinding;

  128.     

  129.     /**

  130.      * Contains information about the object after the change.

  131.      * @serial

  132.      */

  133.     protected Binding newBinding;

  134. 

  135.     /**

  136.      * Constructs an instance of <tt>NamingEvent</tt>.

  137.      *<p>

  138.      * The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative

  139.      * to the event source <tt>source</tt>.

  140.      *

  141.      * For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.

  142.      * For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.

  143.      * For an <tt>OBJECT_CHANGED</tt> event type,  <tt>newBd</tt> and 

  144.      * <tt>oldBd</tt> must not be null. For  an <tt>OBJECT_RENAMED</tt> event type,

  145.      * one of <tt>newBd</tt> or <tt>oldBd</tt> may be null if the new or old

  146.      * binding is outside of the scope for which the listener has registered.

  147.      *

  148.      * @param source The non-null context that fired this event.

  149.      * @param type The type of the event.

  150.      * @param newBd A possibly null binding before the change. See method description.

  151.      * @param oldBd A possibly null binding after the change. See method description.

  152.      * @param changeInfo A possibly null object containing information about the change.

  153.      * @see #OBJECT_ADDED

  154.      * @see #OBJECT_REMOVED

  155.      * @see #OBJECT_RENAMED

  156.      * @see #OBJECT_CHANGED

  157.      */

  158.     public NamingEvent(EventContext source, int type,

  159. 	Binding newBd, Binding oldBd, Object changeInfo) {

  160. 	super(source);

  161. 	this.type = type;

  162. 	oldBinding = oldBd;

  163. 	newBinding = newBd;

  164. 	this.changeInfo = changeInfo;

  165.     }

  166. 

  167.     /**

  168.      * Returns the type of this event.

  169.      * @return The type of this event.

  170.      * @see #OBJECT_ADDED

  171.      * @see #OBJECT_REMOVED

  172.      * @see #OBJECT_RENAMED

  173.      * @see #OBJECT_CHANGED

  174.      */

  175.     public int getType() {

  176. 	return type;

  177.     }

  178. 

  179.     /**

  180.      * Retrieves the event source that fired this event.

  181.      * This returns the same object as <tt>EventObject.getSource()</tt>.

  182.      *<p>

  183.      * If the result of this method is used to access the 

  184.      * event source, for example, to look up the object or get its attributes,

  185.      * then it needs to be locked  because implementations of <tt>Context</tt>

  186.      * are not guaranteed to be thread-safe

  187.      * (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).

  188.      * See the

  189.      * <a href=package-summary.html#THREADING>package description</a>

  190.      * for more information on threading issues.

  191.      *

  192.      * @return The non-null context that fired this event.

  193.      */

  194.     public EventContext getEventContext() {

  195. 	return (EventContext)getSource();

  196.     }

  197. 

  198.     /**

  199.      * Retrieves the binding of the object before the change.

  200.      *<p>

  201.      * The binding must be nonnull if the object existed before the change

  202.      * relative to the source context (<tt>getEventContext()</tt>).

  203.      * That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and

  204.      * <tt>OBJECT_CHANGED</tt>.

  205.      * For <tt>OBJECT_RENAMED</tt>, it is null if the object before the rename

  206.      * is outside of the scope for which the listener has registered interest;

  207.      * it is nonnull if the object is inside the scope before the rename.

  208.      *<p>

  209.      * The name in the binding is to be resolved relative

  210.      * to the event source <tt>getEventContext()</tt>.

  211.      * The object returned by <tt>Binding.getObject()</tt> may be null if

  212.      * such information is unavailable.

  213.      *

  214.      * @return The possibly null binding of the object before the change. 

  215.      */

  216.     public Binding getOldBinding() {

  217. 	return oldBinding;

  218.     }

  219. 

  220.     /**

  221.      * Retrieves the binding of the object after the change.

  222.      *<p>

  223.      * The binding must be nonnull if the object existed after the change

  224.      * relative to the source context (<tt>getEventContext()</tt>).

  225.      * That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and

  226.      * <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,

  227.      * it is null if the object after the rename is outside the scope for

  228.      * which the listener registered interest; it is nonnull if the object

  229.      * is inside the scope after the rename.

  230.      *<p>

  231.      * The name in the binding is to be resolved relative

  232.      * to the event source <tt>getEventContext()</tt>.

  233.      * The object returned by <tt>Binding.getObject()</tt> may be null if

  234.      * such information is unavailable.

  235.      *

  236.      * @return The possibly null binding of the object after the change. 

  237.      */

  238.     public Binding getNewBinding() {

  239. 	return newBinding;

  240.     }

  241. 

  242.     /**

  243.      * Retrieves the change information for this event.

  244.      * The value of the change information is service-specific. For example,

  245.      * it could be an ID that identifies the change in a change log on the server.

  246.      *

  247.      * @return The possibly null change information of this event.

  248.      */

  249.     public Object getChangeInfo() {

  250. 	return changeInfo;

  251.     }

  252. 

  253.     /**

  254.      * Invokes the appropriate listener method on this event.

  255.      * The default implementation of

  256.      * this method handles the following event types:

  257.      * <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>, 

  258.      * <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.

  259.      *<p>

  260.      * The listener method is executed in the same thread

  261.      * as this method.  See the

  262.      * <a href=package-summary.html#THREADING>package description</a>

  263.      * for more information on threading issues.

  264.      * @param listener The nonnull listener.

  265.      */

  266.     public void dispatch(NamingListener listener) {

  267. 	switch (type) {

  268. 	case OBJECT_ADDED:

  269. 	    ((NamespaceChangeListener)listener).objectAdded(this);

  270. 	    break;

  271. 

  272. 	case OBJECT_REMOVED:

  273. 	    ((NamespaceChangeListener)listener).objectRemoved(this);

  274. 	    break;

  275. 

  276. 	case OBJECT_RENAMED:

  277. 	    ((NamespaceChangeListener)listener).objectRenamed(this);

  278. 	    break;

  279. 

  280. 	case OBJECT_CHANGED:

  281. 	    ((ObjectChangeListener)listener).objectChanged(this);

  282. 	    break;

  283. 	}

  284.     }

  285.     private static final long serialVersionUID = -7126752885365133499L;

  286. }