/* * 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. * *
* If a service only supports registration for existing * targets, an attempt to register for a nonexistent target * results in a NameNotFoundException being thrown as early as possible, * preferably at the time addNamingListener() is called, or if that is * not possible, the listener will receive the exception through the * NamingExceptionEvent. *
* 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 NamingExceptionEvent (containing a *NameNotFoundException). *
* An application can use the method targetMustExist() to check * whether a EventContext supports registration * of nonexistent targets. * *
* For example, suppose a listener makes the following registration: *
* When an object named "x/y" is subsequently deleted, the corresponding * NamingEvent (evt) must contain: ** NamespaceChangeListener listener = ...; * src.addNamingListener("x", SUBTREE_SCOPE, listener); *
** evt.getEventContext() == src * evt.getOldBinding().getName().equals("x/y") *
* Furthermore, listener registration/deregistration is with * the EventContext * instance, 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 EventContext instance on * which it invoked addNamingListener() (just as * it needs to keep a reference to the listener in order to remove it * later). It cannot expect to do a lookup() and get another instance of * a EventContext on which to perform the deregistration. *
* The value of this constant is 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. *
* The value of this constant is 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. *
* The value of this constant is 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 OBJECT_SCOPE, * ONELEVEL_SCOPE, and SUBTREE_SCOPE to see how * scope affects the registration. *
* target needs to name a context only when scope is * ONELEVEL_SCOPE. * target may name a non-context if scope is either * OBJECT_SCOPE or SUBTREE_SCOPE. Using * SUBTREE_SCOPE for a non-context might be useful, * for example, if the caller does not know in advance whether target * is a context and just wants to register interest in the (possibly * degenerate subtree) rooted at target. *
* When the listener is notified of an event, the listener may * in invoked in a thread other than the one in which * addNamingListener() is executed. * Care must be taken when multiple threads are accessing the same * EventContext concurrently. * See the * package description * for more information on threading issues. * * @param target A nonnull name to be resolved relative to this context. * @param scope One of OBJECT_SCOPE, ONELEVEL_SCOPE, or * 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 Name for details. * * @param target The nonnull string name of the object resolved relative * to this context. * @param scope One of OBJECT_SCOPE, ONELEVEL_SCOPE, or * 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 EventContext. * The listener may have registered more than once with this * EventContext, perhaps with different target/scope arguments. * After this method is invoked, the listener will no longer * receive events with this 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 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; }