001 /*
002 * Copyright 1999-2004 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.Name;
029 import javax.naming.Context;
030 import javax.naming.NamingException;
031
032 /**
033 * Contains methods for registering/deregistering listeners to be notified of
034 * events fired when objects named in a context changes.
035 *<p>
036 *<h4>Target</h4>
037 * The name parameter in the <tt>addNamingListener()</tt> methods is referred
038 * to as the <em>target</em>. The target, along with the scope, identify
039 * the object(s) that the listener is interested in.
040 * It is possible to register interest in a target that does not exist, but
041 * there might be limitations in the extent to which this can be
042 * supported by the service provider and underlying protocol/service.
043 *<p>
044 * If a service only supports registration for existing
045 * targets, an attempt to register for a nonexistent target
046 * results in a <tt>NameNotFoundException</tt> being thrown as early as possible,
047 * preferably at the time <tt>addNamingListener()</tt> is called, or if that is
048 * not possible, the listener will receive the exception through the
049 * <tt>NamingExceptionEvent</tt>.
050 *<p>
051 * Also, for service providers that only support registration for existing
052 * targets, when the target that a listener has registered for is
053 * subsequently removed from the namespace, the listener is notified
054 * via a <tt>NamingExceptionEvent</tt> (containing a
055 *<tt>NameNotFoundException</tt>).
056 *<p>
057 * An application can use the method <tt>targetMustExist()</tt> to check
058 * whether a <tt>EventContext</tt> supports registration
059 * of nonexistent targets.
060 *<p>
061 *<h4>Event Source</h4>
062 * The <tt>EventContext</tt> instance on which you invoke the
063 * registration methods is the <em>event source</em> of the events that are
064 * (potentially) generated.
065 * The source is <em>not necessarily</em> the object named by the target.
066 * Only when the target is the empty name is the object named by the target
067 * the source.
068 * In other words, the target,
069 * along with the scope parameter, are used to identify
070 * the object(s) that the listener is interested in, but the event source
071 * is the <tt>EventContext</tt> instance with which the listener
072 * has registered.
073 *<p>
074 * For example, suppose a listener makes the following registration:
075 *<blockquote><pre>
076 * NamespaceChangeListener listener = ...;
077 * src.addNamingListener("x", SUBTREE_SCOPE, listener);
078 *</pre></blockquote>
079 * When an object named "x/y" is subsequently deleted, the corresponding
080 * <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
081 *<blockquote><pre>
082 * evt.getEventContext() == src
083 * evt.getOldBinding().getName().equals("x/y")
084 *</pre></blockquote>
085 *<p>
086 * Furthermore, listener registration/deregistration is with
087 * the <tt>EventContext</tt>
088 * <em>instance</em>, and not with the corresponding object in the namespace.
089 * If the program intends at some point to remove a listener, then it needs to
090 * keep a reference to the <tt>EventContext</tt> instance on
091 * which it invoked <tt>addNamingListener()</tt> (just as
092 * it needs to keep a reference to the listener in order to remove it
093 * later). It cannot expect to do a <tt>lookup()</tt> and get another instance of
094 * a <tt>EventContext</tt> on which to perform the deregistration.
095 *<h4>Lifetime of Registration</h4>
096 * A registered listener becomes deregistered when:
097 *<ul>
098 *<li>It is removed using <tt>removeNamingListener()</tt>.
099 *<li>An exception is thrown while collecting information about the events.
100 * That is, when the listener receives a <tt>NamingExceptionEvent</tt>.
101 *<li><tt>Context.close()</tt> is invoked on the <tt>EventContext</tt>
102 * instance with which it has registered.
103 </ul>
104 * Until that point, a <tt>EventContext</tt> instance that has outstanding
105 * listeners will continue to exist and be maintained by the service provider.
106 *
107 *<h4>Listener Implementations</h4>
108 * The registration/deregistration methods accept an instance of
109 * <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>
110 * for different of event types of <tt>NamingEvent</tt>.
111 * For example, the <tt>ObjectChangeListener</tt>
112 * interface is for the <tt>NamingEvent.OBJECT_CHANGED</tt> event type.
113 * To register interest in multiple event types, the listener implementation
114 * should implement multiple <tt>NamingListener</tt> subinterfaces and use a
115 * single invocation of <tt>addNamingListener()</tt>.
116 * In addition to reducing the number of method calls and possibly the code size
117 * of the listeners, this allows some service providers to optimize the
118 * registration.
119 *
120 *<h4>Threading Issues</h4>
121 *
122 * Like <tt>Context</tt> instances in general, instances of
123 * <tt>EventContext</tt> are not guaranteed to be thread-safe.
124 * Care must be taken when multiple threads are accessing the same
125 * <tt>EventContext</tt> concurrently.
126 * See the
127 * <a href=package-summary.html#THREADING>package description</a>
128 * for more information on threading issues.
129 *
130 * @author Rosanna Lee
131 * @author Scott Seligman
132 * @version 1.11 03/12/19
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 <tt>0</tt>.
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 <tt>1</tt>.
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 <tt>2</tt>.
160 */
161 public final static int SUBTREE_SCOPE = 2;
162
163 /**
164 * Adds a listener for receiving naming events fired
165 * when the object(s) identified by a target and scope changes.
166 *
167 * The event source of those events is this context. See the
168 * class description for a discussion on event source and target.
169 * See the descriptions of the constants <tt>OBJECT_SCOPE</tt>,
170 * <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how
171 * <tt>scope</tt> affects the registration.
172 *<p>
173 * <tt>target</tt> needs to name a context only when <tt>scope</tt> is
174 * <tt>ONELEVEL_SCOPE</tt>.
175 * <tt>target</tt> may name a non-context if <tt>scope</tt> is either
176 * <tt>OBJECT_SCOPE</tt> or <tt>SUBTREE_SCOPE</tt>. Using
177 * <tt>SUBTREE_SCOPE</tt> for a non-context might be useful,
178 * for example, if the caller does not know in advance whether <tt>target</tt>
179 * is a context and just wants to register interest in the (possibly
180 * degenerate subtree) rooted at <tt>target</tt>.
181 *<p>
182 * When the listener is notified of an event, the listener may
183 * in invoked in a thread other than the one in which
184 * <tt>addNamingListener()</tt> is executed.
185 * Care must be taken when multiple threads are accessing the same
186 * <tt>EventContext</tt> concurrently.
187 * See the
188 * <a href=package-summary.html#THREADING>package description</a>
189 * for more information on threading issues.
190 *
191 * @param target A nonnull name to be resolved relative to this context.
192 * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
193 * <tt>SUBTREE_SCOPE</tt>.
194 * @param l The nonnull listener.
195 * @exception NamingException If a problem was encountered while
196 * adding the listener.
197 * @see #removeNamingListener
198 */
199 void addNamingListener(Name target, int scope, NamingListener l)
200 throws NamingException;
201
202 /**
203 * Adds a listener for receiving naming events fired
204 * when the object named by the string target name and scope changes.
205 *
206 * See the overload that accepts a <tt>Name</tt> for details.
207 *
208 * @param target The nonnull string name of the object resolved relative
209 * to this context.
210 * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
211 * <tt>SUBTREE_SCOPE</tt>.
212 * @param l The nonnull listener.
213 * @exception NamingException If a problem was encountered while
214 * adding the listener.
215 * @see #removeNamingListener
216 */
217 void addNamingListener(String target, int scope, NamingListener l)
218 throws NamingException;
219
220 /**
221 * Removes a listener from receiving naming events fired
222 * by this <tt>EventContext</tt>.
223 * The listener may have registered more than once with this
224 * <tt>EventContext</tt>, perhaps with different target/scope arguments.
225 * After this method is invoked, the listener will no longer
226 * receive events with this <tt>EventContext</tt> instance
227 * as the event source (except for those events already in the process of
228 * being dispatched).
229 * If the listener was not, or is no longer, registered with
230 * this <tt>EventContext</tt> instance, this method does not do anything.
231 *
232 * @param l The nonnull listener.
233 * @exception NamingException If a problem was encountered while
234 * removing the listener.
235 * @see #addNamingListener
236 */
237 void removeNamingListener(NamingListener l) throws NamingException;
238
239 /**
240 * Determines whether a listener can register interest in a target
241 * that does not exist.
242 *
243 * @return true if the target must exist; false if the target need not exist.
244 * @exception NamingException If the context's behavior in this regard cannot
245 * be determined.
246 */
247 boolean targetMustExist() throws NamingException;
248 }
|