--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.naming/share/classes/javax/naming/event/NamingEvent.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,300 @@
+/*
+ * 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;
+}