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