001 /*
002 * Copyright 1999-2000 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.event;
027
028 import javax.naming.Binding;
029
030 /**
031 * This class represents an event fired by a naming/directory service.
032 *<p>
033 * The <tt>NamingEvent</tt>'s state consists of
034 * <ul>
035 * <li>The event source: the <tt>EventContext</tt> which fired this event.
036 * <li>The event type.
037 * <li>The new binding: information about the object after the change.
038 * <li>The old binding: information about the object before the change.
039 * <li>Change information: information about the change
040 * that triggered this event; usually service provider-specific or server-specific
041 * information.
042 * </ul>
043 * <p>
044 * Note that the event source is always the same <tt>EventContext</tt>
045 * <em>instance</em> that the listener has registered with.
046 * Furthermore, the names of the bindings in
047 * the <tt>NamingEvent</tt> are always relative to that instance.
048 * For example, suppose a listener makes the following registration:
049 *<blockquote><pre>
050 * NamespaceChangeListener listener = ...;
051 * src.addNamingListener("x", SUBTREE_SCOPE, listener);
052 *</pre></blockquote>
053 * When an object named "x/y" is subsequently deleted, the corresponding
054 * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
055 *<blockquote><pre>
056 * evt.getEventContext() == src
057 * evt.getOldBinding().getName().equals("x/y")
058 *</pre></blockquote>
059 *
060 * Care must be taken when multiple threads are accessing the same
061 * <tt>EventContext</tt> concurrently.
062 * See the
063 * <a href=package-summary.html#THREADING>package description</a>
064 * for more information on threading issues.
065 *
066 * @author Rosanna Lee
067 * @author Scott Seligman
068 * @version 1.17 07/05/05
069 *
070 * @see NamingListener
071 * @see EventContext
072 * @since 1.3
073 */
074 public class NamingEvent extends java.util.EventObject {
075 /**
076 * Naming event type for indicating that a new object has been added.
077 * The value of this constant is <tt>0</tt>.
078 */
079 public static final int OBJECT_ADDED = 0;
080
081 /**
082 * Naming event type for indicating that an object has been removed.
083 * The value of this constant is <tt>1</tt>.
084 */
085 public static final int OBJECT_REMOVED = 1;
086
087 /**
088 * Naming event type for indicating that an object has been renamed.
089 * Note that some services might fire multiple events for a single
090 * logical rename operation. For example, the rename operation might
091 * be implemented by adding a binding with the new name and removing
092 * the old binding.
093 *<p>
094 * The old/new binding in <tt>NamingEvent</tt> may be null if the old
095 * name or new name is outside of the scope for which the listener
096 * has registered.
097 *<p>
098 * When an interior node in the namespace tree has been renamed, the
099 * topmost node which is part of the listener's scope should used to generate
100 * a rename event. The extent to which this can be supported is
101 * provider-specific. For example, a service might generate rename
102 * notifications for all descendants of the changed interior node and the
103 * corresponding provider might not be able to prevent those
104 * notifications from being propagated to the listeners.
105 *<p>
106 * The value of this constant is <tt>2</tt>.
107 */
108 public static final int OBJECT_RENAMED = 2;
109
110 /**
111 * Naming event type for indicating that an object has been changed.
112 * The changes might include the object's attributes, or the object itself.
113 * Note that some services might fire multiple events for a single
114 * modification. For example, the modification might
115 * be implemented by first removing the old binding and adding
116 * a new binding containing the same name but a different object.
117 *<p>
118 * The value of this constant is <tt>3</tt>.
119 */
120 public static final int OBJECT_CHANGED = 3;
121
122 /**
123 * Contains information about the change that generated this event.
124 * @serial
125 */
126 protected Object changeInfo;
127
128 /**
129 * Contains the type of this event.
130 * @see #OBJECT_ADDED
131 * @see #OBJECT_REMOVED
132 * @see #OBJECT_RENAMED
133 * @see #OBJECT_CHANGED
134 * @serial
135 */
136 protected int type;
137
138 /**
139 * Contains information about the object before the change.
140 * @serial
141 */
142 protected Binding oldBinding;
143
144 /**
145 * Contains information about the object after the change.
146 * @serial
147 */
148 protected Binding newBinding;
149
150 /**
151 * Constructs an instance of <tt>NamingEvent</tt>.
152 *<p>
153 * The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative
154 * to the event source <tt>source</tt>.
155 *
156 * For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.
157 * For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.
158 * For an <tt>OBJECT_CHANGED</tt> event type, <tt>newBd</tt> and
159 * <tt>oldBd</tt> must not be null. For an <tt>OBJECT_RENAMED</tt> event type,
160 * one of <tt>newBd</tt> or <tt>oldBd</tt> may be null if the new or old
161 * binding is outside of the scope for which the listener has registered.
162 *
163 * @param source The non-null context that fired this event.
164 * @param type The type of the event.
165 * @param newBd A possibly null binding before the change. See method description.
166 * @param oldBd A possibly null binding after the change. See method description.
167 * @param changeInfo A possibly null object containing information about the change.
168 * @see #OBJECT_ADDED
169 * @see #OBJECT_REMOVED
170 * @see #OBJECT_RENAMED
171 * @see #OBJECT_CHANGED
172 */
173 public NamingEvent(EventContext source, int type, Binding newBd,
174 Binding oldBd, Object changeInfo) {
175 super (source);
176 this .type = type;
177 oldBinding = oldBd;
178 newBinding = newBd;
179 this .changeInfo = changeInfo;
180 }
181
182 /**
183 * Returns the type of this event.
184 * @return The type of this event.
185 * @see #OBJECT_ADDED
186 * @see #OBJECT_REMOVED
187 * @see #OBJECT_RENAMED
188 * @see #OBJECT_CHANGED
189 */
190 public int getType() {
191 return type;
192 }
193
194 /**
195 * Retrieves the event source that fired this event.
196 * This returns the same object as <tt>EventObject.getSource()</tt>.
197 *<p>
198 * If the result of this method is used to access the
199 * event source, for example, to look up the object or get its attributes,
200 * then it needs to be locked because implementations of <tt>Context</tt>
201 * are not guaranteed to be thread-safe
202 * (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).
203 * See the
204 * <a href=package-summary.html#THREADING>package description</a>
205 * for more information on threading issues.
206 *
207 * @return The non-null context that fired this event.
208 */
209 public EventContext getEventContext() {
210 return (EventContext) getSource();
211 }
212
213 /**
214 * Retrieves the binding of the object before the change.
215 *<p>
216 * The binding must be nonnull if the object existed before the change
217 * relative to the source context (<tt>getEventContext()</tt>).
218 * That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and
219 * <tt>OBJECT_CHANGED</tt>.
220 * For <tt>OBJECT_RENAMED</tt>, it is null if the object before the rename
221 * is outside of the scope for which the listener has registered interest;
222 * it is nonnull if the object is inside the scope before the rename.
223 *<p>
224 * The name in the binding is to be resolved relative
225 * to the event source <tt>getEventContext()</tt>.
226 * The object returned by <tt>Binding.getObject()</tt> may be null if
227 * such information is unavailable.
228 *
229 * @return The possibly null binding of the object before the change.
230 */
231 public Binding getOldBinding() {
232 return oldBinding;
233 }
234
235 /**
236 * Retrieves the binding of the object after the change.
237 *<p>
238 * The binding must be nonnull if the object existed after the change
239 * relative to the source context (<tt>getEventContext()</tt>).
240 * That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and
241 * <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,
242 * it is null if the object after the rename is outside the scope for
243 * which the listener registered interest; it is nonnull if the object
244 * is inside the scope after the rename.
245 *<p>
246 * The name in the binding is to be resolved relative
247 * to the event source <tt>getEventContext()</tt>.
248 * The object returned by <tt>Binding.getObject()</tt> may be null if
249 * such information is unavailable.
250 *
251 * @return The possibly null binding of the object after the change.
252 */
253 public Binding getNewBinding() {
254 return newBinding;
255 }
256
257 /**
258 * Retrieves the change information for this event.
259 * The value of the change information is service-specific. For example,
260 * it could be an ID that identifies the change in a change log on the server.
261 *
262 * @return The possibly null change information of this event.
263 */
264 public Object getChangeInfo() {
265 return changeInfo;
266 }
267
268 /**
269 * Invokes the appropriate listener method on this event.
270 * The default implementation of
271 * this method handles the following event types:
272 * <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>,
273 * <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.
274 *<p>
275 * The listener method is executed in the same thread
276 * as this method. See the
277 * <a href=package-summary.html#THREADING>package description</a>
278 * for more information on threading issues.
279 * @param listener The nonnull listener.
280 */
281 public void dispatch(NamingListener listener) {
282 switch (type) {
283 case OBJECT_ADDED:
284 ((NamespaceChangeListener) listener).objectAdded(this );
285 break;
286
287 case OBJECT_REMOVED:
288 ((NamespaceChangeListener) listener).objectRemoved(this );
289 break;
290
291 case OBJECT_RENAMED:
292 ((NamespaceChangeListener) listener).objectRenamed(this );
293 break;
294
295 case OBJECT_CHANGED:
296 ((ObjectChangeListener) listener).objectChanged(this );
297 break;
298 }
299 }
300
301 private static final long serialVersionUID = -7126752885365133499L;
302 }
|