/* * @(#)NamingEvent.java 1.10 03/12/19 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package javax.naming.event; import javax.naming.Binding; /** * This class represents an event fired by a naming/directory service. *

* The NamingEvent's state consists of *

*

* Note that the event source is always the same EventContext * instance that the listener has registered with. * Furthermore, the names of the bindings in * the NamingEvent are always relative to that instance. * For example, suppose a listener makes the following registration: *

  *	NamespaceChangeListener listener = ...;
  *	src.addNamingListener("x", SUBTREE_SCOPE, listener);
  *
* When an object named "x/y" is subsequently deleted, the corresponding * NamingEvent (evt) must contain: *
  *	evt.getEventContext() == src
  *	evt.getOldBinding().getName().equals("x/y")
  *
* * Care must be taken when multiple threads are accessing the same * EventContext concurrently. * See the * package description * for more information on threading issues. * * @author Rosanna Lee * @author Scott Seligman * @version 1.10 03/12/19 * * @see NamingListener * @see EventContext * @since 1.3 */ public class NamingEvent extends java.util.EventObject { /** * Naming event type for indicating that a new object has been added. * The value of this constant is 0. */ public static final int OBJECT_ADDED = 0; /** * Naming event type for indicating that an object has been removed. * The value of this constant is 1. */ public static final int OBJECT_REMOVED = 1; /** * Naming event type for indicating that an object has been renamed. * Note that some services might fire multiple events for a single * logical rename operation. For example, the rename operation might * be implemented by adding a binding with the new name and removing * the old binding. *

* The old/new binding in NamingEvent may be null if the old * name or new name is outside of the scope for which the listener * has registered. *

* When an interior node in the namespace tree has been renamed, the * topmost node which is part of the listener's scope should used to generate * a rename event. The extent to which this can be supported is * provider-specific. For example, a service might generate rename * notifications for all descendants of the changed interior node and the * corresponding provider might not be able to prevent those * notifications from being propagated to the listeners. *

* The value of this constant is 2. */ public static final int OBJECT_RENAMED = 2; /** * Naming event type for indicating that an object has been changed. * The changes might include the object's attributes, or the object itself. * Note that some services might fire multiple events for a single * modification. For example, the modification might * be implemented by first removing the old binding and adding * a new binding containing the same name but a different object. *

* The value of this constant is 3. */ public static final int OBJECT_CHANGED = 3; /** * Contains information about the change that generated this event. * @serial */ protected Object changeInfo; /** * Contains the type of this event. * @see #OBJECT_ADDED * @see #OBJECT_REMOVED * @see #OBJECT_RENAMED * @see #OBJECT_CHANGED * @serial */ protected int type; /** * Contains information about the object before the change. * @serial */ protected Binding oldBinding; /** * Contains information about the object after the change. * @serial */ protected Binding newBinding; /** * Constructs an instance of NamingEvent. *

* The names in newBd and oldBd are to be resolved relative * to the event source source. * * For an OBJECT_ADDED event type, newBd must not be null. * For an OBJECT_REMOVED event type, oldBd must not be null. * For an OBJECT_CHANGED event type, newBd and * oldBd must not be null. For an OBJECT_RENAMED event type, * one of newBd or oldBd may be null if the new or old * binding is outside of the scope for which the listener has registered. * * @param source The non-null context that fired this event. * @param type The type of the event. * @param newBd A possibly null binding before the change. See method description. * @param oldBd A possibly null binding after the change. See method description. * @param changeInfo A possibly null object containing information about the change. * @see #OBJECT_ADDED * @see #OBJECT_REMOVED * @see #OBJECT_RENAMED * @see #OBJECT_CHANGED */ public NamingEvent(EventContext source, int type, Binding newBd, Binding oldBd, Object changeInfo) { super(source); this.type = type; oldBinding = oldBd; newBinding = newBd; this.changeInfo = changeInfo; } /** * Returns the type of this event. * @return The type of this event. * @see #OBJECT_ADDED * @see #OBJECT_REMOVED * @see #OBJECT_RENAMED * @see #OBJECT_CHANGED */ public int getType() { return type; } /** * Retrieves the event source that fired this event. * This returns the same object as EventObject.getSource(). *

* If the result of this method is used to access the * event source, for example, to look up the object or get its attributes, * then it needs to be locked because implementations of Context * are not guaranteed to be thread-safe * (and EventContext is a subinterface of Context). * See the * package description * for more information on threading issues. * * @return The non-null context that fired this event. */ public EventContext getEventContext() { return (EventContext)getSource(); } /** * Retrieves the binding of the object before the change. *

* The binding must be nonnull if the object existed before the change * relative to the source context (getEventContext()). * That is, it must be nonnull for OBJECT_REMOVED and * OBJECT_CHANGED. * For OBJECT_RENAMED, it is null if the object before the rename * is outside of the scope for which the listener has registered interest; * it is nonnull if the object is inside the scope before the rename. *

* The name in the binding is to be resolved relative * to the event source getEventContext(). * The object returned by Binding.getObject() may be null if * such information is unavailable. * * @return The possibly null binding of the object before the change. */ public Binding getOldBinding() { return oldBinding; } /** * Retrieves the binding of the object after the change. *

* The binding must be nonnull if the object existed after the change * relative to the source context (getEventContext()). * That is, it must be nonnull for OBJECT_ADDED and * OBJECT_CHANGED. For OBJECT_RENAMED, * it is null if the object after the rename is outside the scope for * which the listener registered interest; it is nonnull if the object * is inside the scope after the rename. *

* The name in the binding is to be resolved relative * to the event source getEventContext(). * The object returned by Binding.getObject() may be null if * such information is unavailable. * * @return The possibly null binding of the object after the change. */ public Binding getNewBinding() { return newBinding; } /** * Retrieves the change information for this event. * The value of the change information is service-specific. For example, * it could be an ID that identifies the change in a change log on the server. * * @return The possibly null change information of this event. */ public Object getChangeInfo() { return changeInfo; } /** * Invokes the appropriate listener method on this event. * The default implementation of * this method handles the following event types: * OBJECT_ADDED, OBJECT_REMOVED, * OBJECT_RENAMED, OBJECT_CHANGED. *

* The listener method is executed in the same thread * as this method. See the * package description * for more information on threading issues. * @param listener The nonnull listener. */ public void dispatch(NamingListener listener) { switch (type) { case OBJECT_ADDED: ((NamespaceChangeListener)listener).objectAdded(this); break; case OBJECT_REMOVED: ((NamespaceChangeListener)listener).objectRemoved(this); break; case OBJECT_RENAMED: ((NamespaceChangeListener)listener).objectRenamed(this); break; case OBJECT_CHANGED: ((ObjectChangeListener)listener).objectChanged(this); break; } } private static final long serialVersionUID = -7126752885365133499L; }