EventContext


1   /*
2    * @(#)EventContext.java    1.11 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.Name  ;
11  import javax.naming.Context  ;
12  import javax.naming.NamingException  ;
13  
14  
15  /**
16   * Contains methods for registering/deregistering listeners to be notified of
17   * events fired when objects named in a context changes.
18   *<p>
19   *<h4>Target</h4>
20   * The name parameter in the <tt>addNamingListener()</tt> methods is referred
21   * to as the <em>target</em>. The target, along with the scope, identify
22   * the object(s) that the listener is interested in.
23   * It is possible to register interest in a target that does not exist, but
24   * there might be limitations in the extent to which this can be
25   * supported by the service provider and underlying protocol/service. 
26   *<p>
27   * If a service only supports registration for existing
28   * targets, an attempt to register for a nonexistent target
29   * results in a <tt>NameNotFoundException</tt> being thrown as early as possible,
30   * preferably at the time <tt>addNamingListener()</tt> is called, or if that is
31   * not possible, the listener will receive the exception through the 
32   * <tt>NamingExceptionEvent</tt>.
33   *<p>
34   * Also, for service providers that only support registration for existing
35   * targets, when the target that a listener has registered for is
36   * subsequently removed from the namespace, the listener is notified
37   * via a <tt>NamingExceptionEvent</tt> (containing a 
38   *<tt>NameNotFoundException</tt>).
39   *<p>
40   * An application can use the method <tt>targetMustExist()</tt> to check
41   * whether a <tt>EventContext</tt> supports registration
42   * of nonexistent targets.
43   *<p>
44   *<h4>Event Source</h4>
45   * The <tt>EventContext</tt> instance on which you invoke the 
46   * registration methods is the <em>event source</em> of the events that are
47   * (potentially) generated. 
48   * The source is <em>not necessarily</em> the object named by the target.
49   * Only when the target is the empty name is the object named by the target 
50   * the source. 
51   * In other words, the target,
52   * along with the scope parameter, are used to identify
53   * the object(s) that the listener is interested in, but the event source
54   * is the <tt>EventContext</tt> instance with which the listener 
55   * has registered.
56   *<p>
57   * For example, suppose a listener makes the following registration:
58   *<blockquote><pre>
59   *  NamespaceChangeListener listener = ...;
60   *  src.addNamingListener("x", SUBTREE_SCOPE, listener);
61   *</pre></blockquote>
62   * When an object named "x/y" is subsequently deleted, the corresponding
63   * <tt>NamingEvent</tt> (<tt>evt</tt>)  must contain:
64   *<blockquote><pre>
65   *  evt.getEventContext() == src
66   *  evt.getOldBinding().getName().equals("x/y")
67   *</pre></blockquote>
68   *<p>
69   * Furthermore, listener registration/deregistration is with 
70   * the <tt>EventContext</tt>
71   * <em>instance</em>, and not with the corresponding object in the namespace.
72   * If the program intends at some point to remove a listener, then it needs to 
73   * keep a reference to the <tt>EventContext</tt> instance on 
74   * which it invoked <tt>addNamingListener()</tt> (just as
75   * it needs to keep a reference to the listener in order to remove it
76   * later). It cannot expect to do a <tt>lookup()</tt> and get another instance of
77   * a <tt>EventContext</tt> on which to perform the deregistration.
78   *<h4>Lifetime of Registration</h4>
79   * A registered listener becomes deregistered when:
80   *<ul>
81   *<li>It is removed using <tt>removeNamingListener()</tt>.
82   *<li>An exception is thrown while collecting information about the events.
83   *  That is, when the listener receives a <tt>NamingExceptionEvent</tt>.
84   *<li><tt>Context.close()</tt> is invoked on the <tt>EventContext</tt> 
85   * instance with which it has registered.
86   </ul>
87   * Until that point, a <tt>EventContext</tt> instance that has outstanding
88   * listeners will continue to exist and be maintained by the service provider.
89   *
90   *<h4>Listener Implementations</h4>
91   * The registration/deregistration methods accept an instance of
92   * <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>
93   * for different of event types of <tt>NamingEvent</tt>. 
94   * For example, the <tt>ObjectChangeListener</tt>
95   * interface is for the <tt>NamingEvent.OBJECT_CHANGED</tt> event type.
96   * To register interest in multiple event types, the listener implementation
97   * should implement multiple <tt>NamingListener</tt> subinterfaces and use a
98   * single invocation of <tt>addNamingListener()</tt>.
99   * In addition to reducing the number of method calls and possibly the code size
100  * of the listeners, this allows some service providers to optimize the
101  * registration.
102  *
103  *<h4>Threading Issues</h4>
104  *
105  * Like <tt>Context</tt> instances in general, instances of
106  * <tt>EventContext</tt> are not guaranteed to be thread-safe.
107  * Care must be taken when multiple threads are accessing the same
108  * <tt>EventContext</tt> concurrently.
109  * See the
110  * <a HREF=package-summary.html#THREADING>package description</a>
111  * for more information on threading issues.
112  * 
113  * @author Rosanna Lee
114  * @author Scott Seligman
115  * @version 1.11 03/12/19
116  * @since 1.3
117  */
118 
119 public interface EventContext extends Context   {
120     /**
121      * Constant for expressing interest in events concerning the object named 
122      * by the target.
123      *<p>
124      * The value of this constant is <tt>0</tt>.
125      */
126     public final static int OBJECT_SCOPE = 0;
127 
128     /**
129      * Constant for expressing interest in events concerning objects 
130      * in the context named by the target, 
131      * excluding the context named by the target.
132      *<p>
133      * The value of this constant is <tt>1</tt>.
134      */
135     public final static int ONELEVEL_SCOPE = 1;
136 
137     /**
138      * Constant for expressing interest in events concerning objects 
139      * in the subtree of the object named by the target, including the object
140      * named by the target.
141      *<p>
142      * The value of this constant is <tt>2</tt>.
143      */
144     public final static int SUBTREE_SCOPE = 2;
145     
146 
147     /**
148      * Adds a listener for receiving naming events fired
149      * when the object(s) identified by a target and scope changes.
150      *
151      * The event source of those events is this context. See the
152      * class description for a discussion on event source and target.
153      * See the descriptions of the constants <tt>OBJECT_SCOPE</tt>,
154      * <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how
155      * <tt>scope</tt> affects the registration.
156      *<p>
157      * <tt>target</tt> needs to name a context only when <tt>scope</tt> is 
158      * <tt>ONELEVEL_SCOPE</tt>.
159      * <tt>target</tt> may name a non-context if <tt>scope</tt> is either 
160      * <tt>OBJECT_SCOPE</tt> or <tt>SUBTREE_SCOPE</tt>.  Using 
161      * <tt>SUBTREE_SCOPE</tt> for a non-context might be useful,
162      * for example, if the caller does not know in advance whether <tt>target</tt> 
163      * is a context and just wants to register interest in the (possibly
164      * degenerate subtree) rooted at <tt>target</tt>.
165      *<p>
166      * When the listener is notified of an event, the listener may
167      * in invoked in a thread other than the one in which
168      * <tt>addNamingListener()</tt> is executed.
169      * Care must be taken when multiple threads are accessing the same
170      * <tt>EventContext</tt> concurrently.
171      * See the
172      * <a HREF=package-summary.html#THREADING>package description</a>
173      * for more information on threading issues.
174      *
175      * @param target A nonnull name to be resolved relative to this context.
176      * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
177      * <tt>SUBTREE_SCOPE</tt>.
178      * @param l  The nonnull listener.
179      * @exception NamingException If a problem was encountered while
180      * adding the listener.
181      * @see #removeNamingListener
182      */
183     void addNamingListener(Name   target, int scope, NamingListener   l) 
184     throws NamingException  ;
185 
186     /**
187      * Adds a listener for receiving naming events fired
188      * when the object named by the string target name and scope changes.
189      *
190      * See the overload that accepts a <tt>Name</tt> for details.
191      *
192      * @param target The nonnull string name of the object resolved relative 
193      * to this context.
194      * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
195      * <tt>SUBTREE_SCOPE</tt>.
196      * @param l  The nonnull listener.
197      * @exception NamingException If a problem was encountered while
198      * adding the listener.
199      * @see #removeNamingListener
200      */
201     void addNamingListener(String   target, int scope, NamingListener   l) 
202     throws NamingException  ;
203 
204     /**
205      * Removes a listener from receiving naming events fired
206      * by this <tt>EventContext</tt>.
207      * The listener may have registered more than once with this
208      * <tt>EventContext</tt>, perhaps with different target/scope arguments.
209      * After this method is invoked, the listener will no longer
210      * receive events with this <tt>EventContext</tt> instance 
211      * as the event source (except for those events already in the process of
212      * being dispatched).
213      * If the listener was not, or is no longer, registered with 
214      * this <tt>EventContext</tt> instance, this method does not do anything.
215      *
216      * @param l  The nonnull listener.
217      * @exception NamingException If a problem was encountered while
218      * removing the listener.
219      * @see #addNamingListener
220      */
221     void removeNamingListener(NamingListener   l) throws NamingException  ;
222 
223     /**
224      * Determines whether a listener can register interest in a target
225      * that does not exist.
226      *
227      * @return true if the target must exist; false if the target need not exist.
228      * @exception NamingException If the context's behavior in this regard cannot
229      * be determined.
230      */
231     boolean targetMustExist() throws NamingException  ;
232 }
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags