/*

 * 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.

  *<p>

  * The {@code NamingEvent}'s state consists of

  * <ul>

  * <li>The event source: the {@code EventContext} 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 {@code EventContext}

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

  * Furthermore, the names of the bindings in

  * the {@code NamingEvent} 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

  * {@code NamingEvent} ({@code evt}) 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

  * {@code EventContext} 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 {@code 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 {@code 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.

     *<p>

     * The old/new binding in {@code NamingEvent} 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 {@code 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.

     *<p>

     * The value of this constant is {@code 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 {@code NamingEvent}.

     *<p>

     * The names in {@code newBd} and {@code oldBd} are to be resolved relative

     * to the event source {@code source}.

     *

     * For an {@code OBJECT_ADDED} event type, {@code newBd} must not be null.

     * For an {@code OBJECT_REMOVED} event type, {@code oldBd} must not be null.

     * For an {@code OBJECT_CHANGED} event type,  {@code newBd} and

     * {@code oldBd} must not be null. For  an {@code OBJECT_RENAMED} event type,

     * one of {@code newBd} or {@code 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 {@code EventObject.getSource()}.

     *<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 {@code Context}

     * are not guaranteed to be thread-safe

     * (and {@code EventContext} is a subinterface of {@code Context}).

     * 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.

     *<p>

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

     * relative to the source context ({@code getEventContext()}).

     * That is, it must be nonnull for {@code OBJECT_REMOVED} and

     * {@code OBJECT_CHANGED}.

     * For {@code 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.

     *<p>

     * The name in the binding is to be resolved relative

     * to the event source {@code getEventContext()}.

     * The object returned by {@code 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.

     *<p>

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

     * relative to the source context ({@code getEventContext()}).

     * That is, it must be nonnull for {@code OBJECT_ADDED} and

     * {@code OBJECT_CHANGED}. For {@code 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.

     *<p>

     * The name in the binding is to be resolved relative

     * to the event source {@code getEventContext()}.

     * The object returned by {@code 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:

     * {@code OBJECT_ADDED, OBJECT_REMOVED,

     * OBJECT_RENAMED, OBJECT_CHANGED}.

     *<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;

}