| /* |
| * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.naming.event; |
| |
| import javax.naming.Name; |
| import javax.naming.Context; |
| import javax.naming.NamingException; |
| |
| |
| /** |
| * Contains methods for registering/deregistering listeners to be notified of |
| * events fired when objects named in a context changes. |
| * |
| *<h1>Target</h1> |
| * The name parameter in the {@code addNamingListener()} methods is referred |
| * to as the <em>target</em>. The target, along with the scope, identify |
| * the object(s) that the listener is interested in. |
| * It is possible to register interest in a target that does not exist, but |
| * there might be limitations in the extent to which this can be |
| * supported by the service provider and underlying protocol/service. |
| *<p> |
| * If a service only supports registration for existing |
| * targets, an attempt to register for a nonexistent target |
| * results in a {@code NameNotFoundException} being thrown as early as possible, |
| * preferably at the time {@code addNamingListener()} is called, or if that is |
| * not possible, the listener will receive the exception through the |
| * {@code NamingExceptionEvent}. |
| *<p> |
| * Also, for service providers that only support registration for existing |
| * targets, when the target that a listener has registered for is |
| * subsequently removed from the namespace, the listener is notified |
| * via a {@code NamingExceptionEvent} (containing a |
| *{@code NameNotFoundException}). |
| *<p> |
| * An application can use the method {@code targetMustExist()} to check |
| * whether an {@code EventContext} supports registration |
| * of nonexistent targets. |
| * |
| *<h1>Event Source</h1> |
| * The {@code EventContext} instance on which you invoke the |
| * registration methods is the <em>event source</em> of the events that are |
| * (potentially) generated. |
| * The source is <em>not necessarily</em> the object named by the target. |
| * Only when the target is the empty name is the object named by the target |
| * the source. |
| * In other words, the target, |
| * along with the scope parameter, are used to identify |
| * the object(s) that the listener is interested in, but the event source |
| * is the {@code EventContext} instance with which the listener |
| * has registered. |
| *<p> |
| * For example, suppose a listener makes the following registration: |
| *<blockquote><pre> |
| * NamespaceChangeListener listener = ...; |
| * src.addNamingListener("x", SUBTREE_SCOPE, listener); |
| *</pre></blockquote> |
| * When an object named "x/y" is subsequently deleted, the corresponding |
| * {@code NamingEvent} ({@code evt}) must contain: |
| *<blockquote><pre> |
| * evt.getEventContext() == src |
| * evt.getOldBinding().getName().equals("x/y") |
| *</pre></blockquote> |
| *<p> |
| * Furthermore, listener registration/deregistration is with |
| * the {@code EventContext} |
| * <em>instance</em>, and not with the corresponding object in the namespace. |
| * If the program intends at some point to remove a listener, then it needs to |
| * keep a reference to the {@code EventContext} instance on |
| * which it invoked {@code addNamingListener()} (just as |
| * it needs to keep a reference to the listener in order to remove it |
| * later). It cannot expect to do a {@code lookup()} and get another instance of |
| * an {@code EventContext} on which to perform the deregistration. |
| *<h1>Lifetime of Registration</h1> |
| * A registered listener becomes deregistered when: |
| *<ul> |
| *<li>It is removed using {@code removeNamingListener()}. |
| *<li>An exception is thrown while collecting information about the events. |
| * That is, when the listener receives a {@code NamingExceptionEvent}. |
| *<li>{@code Context.close()} is invoked on the {@code EventContext} |
| * instance with which it has registered. |
| </ul> |
| * Until that point, an {@code EventContext} instance that has outstanding |
| * listeners will continue to exist and be maintained by the service provider. |
| * |
| *<h1>Listener Implementations</h1> |
| * The registration/deregistration methods accept an instance of |
| * {@code NamingListener}. There are subinterfaces of {@code NamingListener} |
| * for different of event types of {@code NamingEvent}. |
| * For example, the {@code ObjectChangeListener} |
| * interface is for the {@code NamingEvent.OBJECT_CHANGED} event type. |
| * To register interest in multiple event types, the listener implementation |
| * should implement multiple {@code NamingListener} subinterfaces and use a |
| * single invocation of {@code addNamingListener()}. |
| * In addition to reducing the number of method calls and possibly the code size |
| * of the listeners, this allows some service providers to optimize the |
| * registration. |
| * |
| *<h1>Threading Issues</h1> |
| * |
| * Like {@code Context} instances in general, instances of |
| * {@code EventContext} are not guaranteed to be thread-safe. |
| * Care must be taken when multiple threads are accessing the same |
| * {@code EventContext} concurrently. |
| * See the |
| * <a href=package-summary.html#THREADING>package description</a> |
| * for more information on threading issues. |
| * |
| * @author Rosanna Lee |
| * @author Scott Seligman |
| * @since 1.3 |
| */ |
| |
| public interface EventContext extends Context { |
| /** |
| * Constant for expressing interest in events concerning the object named |
| * by the target. |
| *<p> |
| * The value of this constant is {@code 0}. |
| */ |
| public final static int OBJECT_SCOPE = 0; |
| |
| /** |
| * Constant for expressing interest in events concerning objects |
| * in the context named by the target, |
| * excluding the context named by the target. |
| *<p> |
| * The value of this constant is {@code 1}. |
| */ |
| public final static int ONELEVEL_SCOPE = 1; |
| |
| /** |
| * Constant for expressing interest in events concerning objects |
| * in the subtree of the object named by the target, including the object |
| * named by the target. |
| *<p> |
| * The value of this constant is {@code 2}. |
| */ |
| public final static int SUBTREE_SCOPE = 2; |
| |
| |
| /** |
| * Adds a listener for receiving naming events fired |
| * when the object(s) identified by a target and scope changes. |
| * |
| * The event source of those events is this context. See the |
| * class description for a discussion on event source and target. |
| * See the descriptions of the constants {@code OBJECT_SCOPE}, |
| * {@code ONELEVEL_SCOPE}, and {@code SUBTREE_SCOPE} to see how |
| * {@code scope} affects the registration. |
| *<p> |
| * {@code target} needs to name a context only when {@code scope} is |
| * {@code ONELEVEL_SCOPE}. |
| * {@code target} may name a non-context if {@code scope} is either |
| * {@code OBJECT_SCOPE} or {@code SUBTREE_SCOPE}. Using |
| * {@code SUBTREE_SCOPE} for a non-context might be useful, |
| * for example, if the caller does not know in advance whether {@code target} |
| * is a context and just wants to register interest in the (possibly |
| * degenerate subtree) rooted at {@code target}. |
| *<p> |
| * When the listener is notified of an event, the listener may |
| * in invoked in a thread other than the one in which |
| * {@code addNamingListener()} is executed. |
| * Care must be taken when multiple threads are accessing the same |
| * {@code EventContext} concurrently. |
| * See the |
| * <a href=package-summary.html#THREADING>package description</a> |
| * for more information on threading issues. |
| * |
| * @param target A nonnull name to be resolved relative to this context. |
| * @param scope One of {@code OBJECT_SCOPE}, {@code ONELEVEL_SCOPE}, or |
| * {@code SUBTREE_SCOPE}. |
| * @param l The nonnull listener. |
| * @exception NamingException If a problem was encountered while |
| * adding the listener. |
| * @see #removeNamingListener |
| */ |
| void addNamingListener(Name target, int scope, NamingListener l) |
| throws NamingException; |
| |
| /** |
| * Adds a listener for receiving naming events fired |
| * when the object named by the string target name and scope changes. |
| * |
| * See the overload that accepts a {@code Name} for details. |
| * |
| * @param target The nonnull string name of the object resolved relative |
| * to this context. |
| * @param scope One of {@code OBJECT_SCOPE}, {@code ONELEVEL_SCOPE}, or |
| * {@code SUBTREE_SCOPE}. |
| * @param l The nonnull listener. |
| * @exception NamingException If a problem was encountered while |
| * adding the listener. |
| * @see #removeNamingListener |
| */ |
| void addNamingListener(String target, int scope, NamingListener l) |
| throws NamingException; |
| |
| /** |
| * Removes a listener from receiving naming events fired |
| * by this {@code EventContext}. |
| * The listener may have registered more than once with this |
| * {@code EventContext}, perhaps with different target/scope arguments. |
| * After this method is invoked, the listener will no longer |
| * receive events with this {@code EventContext} instance |
| * as the event source (except for those events already in the process of |
| * being dispatched). |
| * If the listener was not, or is no longer, registered with |
| * this {@code EventContext} instance, this method does not do anything. |
| * |
| * @param l The nonnull listener. |
| * @exception NamingException If a problem was encountered while |
| * removing the listener. |
| * @see #addNamingListener |
| */ |
| void removeNamingListener(NamingListener l) throws NamingException; |
| |
| /** |
| * Determines whether a listener can register interest in a target |
| * that does not exist. |
| * |
| * @return true if the target must exist; false if the target need not exist. |
| * @exception NamingException If the context's behavior in this regard cannot |
| * be determined. |
| */ |
| boolean targetMustExist() throws NamingException; |
| } |
