https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

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

    

  • The event source: the EventContext which fired this event.

  • The event type.

  • The new binding: information about the object after the change.

  • The old binding: information about the object before the change.

  • Change information: information about the change
that triggered this event; usually service provider-specific or server-specific
information.




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, Scott Seligman
See Also:
Since:1.3
/**
  * This class represents an event fired by a naming/directory service.
  *<p>
  * The <tt>NamingEvent</tt>'s state consists of
  * <ul>
  * <li>The event source: the <tt>EventContext</tt> which fired this event.
  * <li>The event type.
  * <li>The new binding: information about the object after the change.
  * <li>The old binding: information about the object before the change.
  * <li>Change information: information about the change
  * that triggered this event; usually service provider-specific or server-specific
  * information.
  * </ul>
  * <p>
  * Note that the event source is always the same <tt>EventContext</tt>
  * <em>instance</em>  that the listener has registered with.
  * Furthermore, the names of the bindings in
  * the <tt>NamingEvent</tt> are always relative to that instance.
  * For example, suppose a listener makes the following registration:
  *<blockquote><pre>
  *     NamespaceChangeListener listener = ...;
  *     src.addNamingListener("x", SUBTREE_SCOPE, listener);
  *</pre></blockquote>
  * When an object named "x/y" is subsequently deleted, the corresponding
  * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
  *<blockquote><pre>
  *     evt.getEventContext() == src
  *     evt.getOldBinding().getName().equals("x/y")
  *</pre></blockquote>
  *
  * Care must be taken when multiple threads are accessing the same
  * <tt>EventContext</tt> concurrently.
  * See the
  * <a href=package-summary.html#THREADING>package description</a>
  * for more information on threading issues.
  *
  * @author Rosanna Lee
  * @author Scott Seligman
  *
  * @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.

/**
     * Naming event type for indicating that a new object has been added.
     * The value of this constant is <tt>0</tt>.
     */
    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.

/**
     * Naming event type for indicating that an object has been removed.
     * The value of this constant is <tt>1</tt>.
     */
    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.

/**
     * 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.
     *<p>
     * The old/new binding in <tt>NamingEvent</tt> may be null if the old
     * name or new name is outside of the scope for which the listener
     * has registered.
     *<p>
     * 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.
     *<p>
     * The value of this constant is <tt>2</tt>.
     */
    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.

/**
     * 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.
     *<p>
     * The value of this constant is <tt>3</tt>.
     */
    public static final int OBJECT_CHANGED = 3;

    
Contains information about the change that generated this event.

@serial
/**
     * Contains information about the change that generated this event.
     * @serial
     */
    protected Object changeInfo;

    
Contains the type of this event.

See Also:
@serial
/**
     * 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
/**
     * Contains information about the object before the change.
     * @serial
     */
    protected Binding oldBinding;

    
Contains information about the object after the change.

@serial
/**
     * 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.

Params:
  • source – The non-null context that fired this event.
  • type – The type of the event.
  • newBd – A possibly null binding before the change. See method description.
  • oldBd – A possibly null binding after the change. See method description.
  • changeInfo – A possibly null object containing information about the change.
See Also:
/**
     * Constructs an instance of <tt>NamingEvent</tt>.
     *<p>
     * The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative
     * to the event source <tt>source</tt>.
     *
     * For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.
     * For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.
     * For an <tt>OBJECT_CHANGED</tt> event type,  <tt>newBd</tt> and
     * <tt>oldBd</tt> must not be null. For  an <tt>OBJECT_RENAMED</tt> event type,
     * one of <tt>newBd</tt> or <tt>oldBd</tt> 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.

See Also:
Returns:The type of this event.
/**
     * 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.

Returns:The non-null context that fired this event.
/**
     * Retrieves the event source that fired this event.
     * This returns the same object as <tt>EventObject.getSource()</tt>.
     *<p>
     * 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 <tt>Context</tt>
     * are not guaranteed to be thread-safe
     * (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).
     * See the
     * <a href=package-summary.html#THREADING>package description</a>
     * 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.

Returns:The possibly null binding of the object before the change.
/**
     * Retrieves the binding of the object before the change.
     *<p>
     * The binding must be nonnull if the object existed before the change
     * relative to the source context (<tt>getEventContext()</tt>).
     * That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and
     * <tt>OBJECT_CHANGED</tt>.
     * For <tt>OBJECT_RENAMED</tt>, 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.
     *<p>
     * The name in the binding is to be resolved relative
     * to the event source <tt>getEventContext()</tt>.
     * The object returned by <tt>Binding.getObject()</tt> 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.

Returns:The possibly null binding of the object after the change.
/**
     * Retrieves the binding of the object after the change.
     *<p>
     * The binding must be nonnull if the object existed after the change
     * relative to the source context (<tt>getEventContext()</tt>).
     * That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and
     * <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,
     * 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.
     *<p>
     * The name in the binding is to be resolved relative
     * to the event source <tt>getEventContext()</tt>.
     * The object returned by <tt>Binding.getObject()</tt> 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.

Returns:The possibly null change information of this event.
/**
     * 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.

Params:
  • listener – The nonnull listener.
/**
     * Invokes the appropriate listener method on this event.
     * The default implementation of
     * this method handles the following event types:
     * <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>,
     * <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.
     *<p>
     * The listener method is executed in the same thread
     * as this method.  See the
     * <a href=package-summary.html#THREADING>package description</a>
     * 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;
}