NamingEvent


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