View Javadoc
1   /*
2    * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.naming.event;
27  
28  import javax.naming.Binding;
29  
30  /**
31    * This class represents an event fired by a naming/directory service.
32    *<p>
33    * The <tt>NamingEvent</tt>'s state consists of
34    * <ul>
35    * <li>The event source: the <tt>EventContext</tt> which fired this event.
36    * <li>The event type.
37    * <li>The new binding: information about the object after the change.
38    * <li>The old binding: information about the object before the change.
39    * <li>Change information: information about the change
40    * that triggered this event; usually service provider-specific or server-specific
41    * information.
42    * </ul>
43    * <p>
44    * Note that the event source is always the same <tt>EventContext</tt>
45    * <em>instance</em>  that the listener has registered with.
46    * Furthermore, the names of the bindings in
47    * the <tt>NamingEvent</tt> are always relative to that instance.
48    * For example, suppose a listener makes the following registration:
49    *<blockquote><pre>
50    *     NamespaceChangeListener listener = ...;
51    *     src.addNamingListener("x", SUBTREE_SCOPE, listener);
52    *</pre></blockquote>
53    * When an object named "x/y" is subsequently deleted, the corresponding
54    * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
55    *<blockquote><pre>
56    *     evt.getEventContext() == src
57    *     evt.getOldBinding().getName().equals("x/y")
58    *</pre></blockquote>
59    *
60    * Care must be taken when multiple threads are accessing the same
61    * <tt>EventContext</tt> concurrently.
62    * See the
63    * <a href=package-summary.html#THREADING>package description</a>
64    * for more information on threading issues.
65    *
66    * @author Rosanna Lee
67    * @author Scott Seligman
68    *
69    * @see NamingListener
70    * @see EventContext
71    * @since 1.3
72    */
73  public class NamingEvent extends java.util.EventObject {
74      /**
75       * Naming event type for indicating that a new object has been added.
76       * The value of this constant is <tt>0</tt>.
77       */
78      public static final int OBJECT_ADDED = 0;
79  
80      /**
81       * Naming event type for indicating that an object has been removed.
82       * The value of this constant is <tt>1</tt>.
83       */
84      public static final int OBJECT_REMOVED = 1;
85  
86      /**
87       * Naming event type for indicating that an object has been renamed.
88       * Note that some services might fire multiple events for a single
89       * logical rename operation. For example, the rename operation might
90       * be implemented by adding a binding with the new name and removing
91       * the old binding.
92       *<p>
93       * The old/new binding in <tt>NamingEvent</tt> may be null if the old
94       * name or new name is outside of the scope for which the listener
95       * has registered.
96       *<p>
97       * When an interior node in the namespace tree has been renamed, the
98       * topmost node which is part of the listener's scope should used to generate
99       * a rename event. The extent to which this can be supported is
100      * provider-specific. For example, a service might generate rename
101      * notifications for all descendants of the changed interior node and the
102      * corresponding provider might not be able to prevent those
103      * notifications from being propagated to the listeners.
104      *<p>
105      * The value of this constant is <tt>2</tt>.
106      */
107     public static final int OBJECT_RENAMED = 2;
108 
109     /**
110      * Naming event type for indicating that an object has been changed.
111      * The changes might include the object's attributes, or the object itself.
112      * Note that some services might fire multiple events for a single
113      * modification. For example, the modification might
114      * be implemented by first removing the old binding and adding
115      * a new binding containing the same name but a different object.
116      *<p>
117      * The value of this constant is <tt>3</tt>.
118      */
119     public static final int OBJECT_CHANGED = 3;
120 
121     /**
122      * Contains information about the change that generated this event.
123      * @serial
124      */
125     protected Object changeInfo;
126 
127     /**
128      * Contains the type of this event.
129      * @see #OBJECT_ADDED
130      * @see #OBJECT_REMOVED
131      * @see #OBJECT_RENAMED
132      * @see #OBJECT_CHANGED
133      * @serial
134      */
135     protected int type;
136 
137     /**
138      * Contains information about the object before the change.
139      * @serial
140      */
141     protected Binding oldBinding;
142 
143     /**
144      * Contains information about the object after the change.
145      * @serial
146      */
147     protected Binding newBinding;
148 
149     /**
150      * Constructs an instance of <tt>NamingEvent</tt>.
151      *<p>
152      * The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative
153      * to the event source <tt>source</tt>.
154      *
155      * For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.
156      * For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.
157      * For an <tt>OBJECT_CHANGED</tt> event type,  <tt>newBd</tt> and
158      * <tt>oldBd</tt> must not be null. For  an <tt>OBJECT_RENAMED</tt> event type,
159      * one of <tt>newBd</tt> or <tt>oldBd</tt> may be null if the new or old
160      * binding is outside of the scope for which the listener has registered.
161      *
162      * @param source The non-null context that fired this event.
163      * @param type The type of the event.
164      * @param newBd A possibly null binding before the change. See method description.
165      * @param oldBd A possibly null binding after the change. See method description.
166      * @param changeInfo A possibly null object containing information about the change.
167      * @see #OBJECT_ADDED
168      * @see #OBJECT_REMOVED
169      * @see #OBJECT_RENAMED
170      * @see #OBJECT_CHANGED
171      */
172     public NamingEvent(EventContext source, int type,
173         Binding newBd, Binding oldBd, Object changeInfo) {
174         super(source);
175         this.type = type;
176         oldBinding = oldBd;
177         newBinding = newBd;
178         this.changeInfo = changeInfo;
179     }
180 
181     /**
182      * Returns the type of this event.
183      * @return The type of this event.
184      * @see #OBJECT_ADDED
185      * @see #OBJECT_REMOVED
186      * @see #OBJECT_RENAMED
187      * @see #OBJECT_CHANGED
188      */
189     public int getType() {
190         return type;
191     }
192 
193     /**
194      * Retrieves the event source that fired this event.
195      * This returns the same object as <tt>EventObject.getSource()</tt>.
196      *<p>
197      * If the result of this method is used to access the
198      * event source, for example, to look up the object or get its attributes,
199      * then it needs to be locked  because implementations of <tt>Context</tt>
200      * are not guaranteed to be thread-safe
201      * (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).
202      * See the
203      * <a href=package-summary.html#THREADING>package description</a>
204      * for more information on threading issues.
205      *
206      * @return The non-null context that fired this event.
207      */
208     public EventContext getEventContext() {
209         return (EventContext)getSource();
210     }
211 
212     /**
213      * Retrieves the binding of the object before the change.
214      *<p>
215      * The binding must be nonnull if the object existed before the change
216      * relative to the source context (<tt>getEventContext()</tt>).
217      * That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and
218      * <tt>OBJECT_CHANGED</tt>.
219      * For <tt>OBJECT_RENAMED</tt>, it is null if the object before the rename
220      * is outside of the scope for which the listener has registered interest;
221      * it is nonnull if the object is inside the scope before the rename.
222      *<p>
223      * The name in the binding is to be resolved relative
224      * to the event source <tt>getEventContext()</tt>.
225      * The object returned by <tt>Binding.getObject()</tt> may be null if
226      * such information is unavailable.
227      *
228      * @return The possibly null binding of the object before the change.
229      */
230     public Binding getOldBinding() {
231         return oldBinding;
232     }
233 
234     /**
235      * Retrieves the binding of the object after the change.
236      *<p>
237      * The binding must be nonnull if the object existed after the change
238      * relative to the source context (<tt>getEventContext()</tt>).
239      * That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and
240      * <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,
241      * it is null if the object after the rename is outside the scope for
242      * which the listener registered interest; it is nonnull if the object
243      * is inside the scope after the rename.
244      *<p>
245      * The name in the binding is to be resolved relative
246      * to the event source <tt>getEventContext()</tt>.
247      * The object returned by <tt>Binding.getObject()</tt> may be null if
248      * such information is unavailable.
249      *
250      * @return The possibly null binding of the object after the change.
251      */
252     public Binding getNewBinding() {
253         return newBinding;
254     }
255 
256     /**
257      * Retrieves the change information for this event.
258      * The value of the change information is service-specific. For example,
259      * it could be an ID that identifies the change in a change log on the server.
260      *
261      * @return The possibly null change information of this event.
262      */
263     public Object getChangeInfo() {
264         return changeInfo;
265     }
266 
267     /**
268      * Invokes the appropriate listener method on this event.
269      * The default implementation of
270      * this method handles the following event types:
271      * <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>,
272      * <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.
273      *<p>
274      * The listener method is executed in the same thread
275      * as this method.  See the
276      * <a href=package-summary.html#THREADING>package description</a>
277      * for more information on threading issues.
278      * @param listener The nonnull listener.
279      */
280     public void dispatch(NamingListener listener) {
281         switch (type) {
282         case OBJECT_ADDED:
283             ((NamespaceChangeListener)listener).objectAdded(this);
284             break;
285 
286         case OBJECT_REMOVED:
287             ((NamespaceChangeListener)listener).objectRemoved(this);
288             break;
289 
290         case OBJECT_RENAMED:
291             ((NamespaceChangeListener)listener).objectRenamed(this);
292             break;
293 
294         case OBJECT_CHANGED:
295             ((ObjectChangeListener)listener).objectChanged(this);
296             break;
297         }
298     }
299     private static final long serialVersionUID = -7126752885365133499L;
300 }