/* * Copyright (c) 1999, 2000, 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 com.sun.jndi.ldap; import java.util.Hashtable;import java.util.Vector;import java.util.Enumeration;import java.util.EventObject; import javax.naming.*;import javax.naming.directory.*;import javax.naming.event.*;import javax.naming.directory.SearchControls;import javax.naming.ldap.UnsolicitedNotificationListener;import javax.naming.ldap.UnsolicitedNotificationEvent;import javax.naming.ldap.UnsolicitedNotification; /** * This is a utility class that can be used by a context that supports * event notification.  You can use an instance of this class as a member field * of your context and delegate various work to it. * It is currently structured so that each context should have its own * EventSupport (instead of static version shared by all contexts * of a service provider). *<p> * This class supports two types of listeners: those that register for * NamingEvents, and those for UnsolicitedNotificationEvents (they can be mixed * into the same listener). * For NamingEvent listeners, it maintains a hashtable that maps * registration requests--the key--to * <em>notifiers</em>--the value. Each registration request consists of: *<ul> *<li>The name argument of the registration. *<li>The filter (default is "(objectclass=*)"). *<li>The search controls (default is null SearchControls). *<li>The events that the listener is interested in. This is determined by * finding out which <tt>NamingListener</tt> interface the listener supports. *</ul> *<p> *A notifier (<tt>NamingEventNotifier</tt>) is a worker thread that is responsible *for gathering information for generating events requested by its listeners. *Each notifier maintains its own list of listeners; these listeners have *all made the same registration request (at different times) and implements *the same <tt>NamingListener</tt> interfaces. *<p> *For unsolicited listeners, this class maintains a vector, unsolicited. *When an unsolicited listener is registered, this class adds itself *to the context's LdapClient. When LdapClient receives an unsolicited *notification, it notifies this EventSupport to fire an event to the *the listeners. Special handling in LdapClient is done for the DISCONNECT *notification. [It results in the EventSupport firing also a *NamingExceptionEvent to the unsolicited listeners.] *<p> * *When a context no longer needs this EventSupport, it should invoke *cleanup() on it. *<p> *<h4>Registration</h4> *When a registration request is made, this class attempts to find an *existing notifier that's already working on the request. If one is *found, the listener is added to the notifier's list. If one is not found, *a new notifier is created for the listener. * *<h4>Deregistration</h4> *When a deregistration request is made, this class attemps to find its *corresponding notifier. If the notifier is found, the listener is removed *from the notifier's list. If the listener is the last listener on the list, *the notifier's thread is terminated and removed from this class's hashtable. *Nothing happens if the notifier is not found. * *<h4>Event Dispatching</h4> *The notifiers are responsible for gather information for generating events *requested by their respective listeners. When a notifier gets sufficient *information to generate an event, it creates invokes the *appropriate <tt>fireXXXEvent</tt> on this class with the information and list of *listeners. This causes an event and the list of listeners to be added *to the <em>event queue</em>. *This class maintains an event queue and a dispatching thread that dequeues *events from the queue and dispatches them to the listeners. * *<h4>Synchronization</h4> *This class is used by the main thread (LdapCtx) to add/remove listeners. *It is also used asynchronously by NamingEventNotifiers threads and *the context's Connection thread. It is used by the notifier threads to *queue events and to update the notifiers list when the notifiers exit. *It is used by the Connection thread to fire unsolicited notifications. *Methods that access/update the 'unsolicited' and 'notifiers' lists are *thread-safe. * * @author Rosanna Lee */final class EventSupport {    final static private boolean debug = false;     private LdapCtx ctx;     /**     * NamingEventNotifiers; hashed by search arguments;     */    private Hashtable notifiers = new Hashtable(11);     /**     * List of unsolicited notification listeners.     */    private Vector unsolicited = null;     /**     * Constructs EventSupport for ctx.     * <em>Do we need to record the name of the target context?     * Or can we assume that EventSupport is called on a resolved     * context? Do we need other add/remove-NamingListener methods?     * package private;     */    EventSupport(LdapCtx ctx) {        this.ctx = ctx;    }     /**     * Adds <tt>l</tt> to list of listeners interested in <tt>nm</tt>.     */    /*     * Make the add/removeNamingListeners synchronized to:     * 1. protect usage of 'unsolicited', which may be read by     *    the Connection thread when dispatching unsolicited notification.     * 2. ensure that NamingEventNotifier thread's access to 'notifiers'     *    is safe     */    synchronized void addNamingListener(String nm, int scope,        NamingListener l) throws NamingException {         if (l instanceof ObjectChangeListener ||            l instanceof NamespaceChangeListener) {            NotifierArgs args = new NotifierArgs(nm, scope, l);             NamingEventNotifier notifier =                (NamingEventNotifier) notifiers.get(args);            if (notifier == null) {                notifier = new NamingEventNotifier(this, ctx, args, l);                notifiers.put(args, notifier);            } else {                notifier.addNamingListener(l);            }        }        if (l instanceof UnsolicitedNotificationListener) {            // Add listener to this's list of unsolicited notifiers            if (unsolicited == null) {                unsolicited = new Vector(3);            }             unsolicited.addElement(l);        }    }     /**     * Adds <tt>l</tt> to list of listeners interested in <tt>nm</tt>     * and filter.     */    synchronized void addNamingListener(String nm, String filter,        SearchControls ctls, NamingListener l) throws NamingException {         if (l instanceof ObjectChangeListener ||            l instanceof NamespaceChangeListener) {            NotifierArgs args = new NotifierArgs(nm, filter, ctls, l);             NamingEventNotifier notifier =                (NamingEventNotifier) notifiers.get(args);            if (notifier == null) {                notifier = new NamingEventNotifier(this, ctx, args, l);                notifiers.put(args, notifier);            } else {                notifier.addNamingListener(l);            }        }        if (l instanceof UnsolicitedNotificationListener) {            // Add listener to this's list of unsolicited notifiers            if (unsolicited == null) {                unsolicited = new Vector(3);            }            unsolicited.addElement(l);        }    }     /**     * Removes <tt>l</tt> from all notifiers in this context.     */    synchronized void removeNamingListener(NamingListener l) {        Enumeration allnotifiers = notifiers.elements();        NamingEventNotifier notifier;         if (debug) System.err.println("EventSupport removing listener");         // Go through list of notifiers, remove 'l' from each.        // If 'l' is notifier's only listener, remove notifier too.        while (allnotifiers.hasMoreElements()) {            notifier = (NamingEventNotifier)allnotifiers.nextElement();            if (notifier != null) {                if (debug)                    System.err.println("EventSupport removing listener from notifier");                notifier.removeNamingListener(l);                if (!notifier.hasNamingListeners()) {                    if (debug)                        System.err.println("EventSupport stopping notifier");                    notifier.stop();                    notifiers.remove(notifier.info);                }            }        }         // Remove from list of unsolicited notifier        if (debug) System.err.println("EventSupport removing unsolicited: " +            unsolicited);        if (unsolicited != null) {            unsolicited.removeElement(l);        }     }     synchronized boolean hasUnsolicited() {        return (unsolicited != null && unsolicited.size() > 0);    }     /**      * package private;      * Called by NamingEventNotifier to remove itself when it encounters      * a NamingException.      */    synchronized void removeDeadNotifier(NotifierArgs info) {        if (debug) {            System.err.println("EventSupport.removeDeadNotifier: " + info.name);        }        notifiers.remove(info);    }     /**     * Fire an event to unsolicited listeners.     * package private;     * Called by LdapCtx when its clnt receives an unsolicited notification.     */    synchronized void fireUnsolicited(Object obj) {        if (debug) {            System.err.println("EventSupport.fireUnsolicited: " + obj + " "                + unsolicited);        }        if (unsolicited == null || unsolicited.size() == 0) {            // This shouldn't really happen, but might in case            // there is a timing problem that removes a listener            // before a fired event event reaches here.            return;        }         if (obj instanceof UnsolicitedNotification) {             // Fire UnsolicitedNotification to unsolicited listeners             UnsolicitedNotificationEvent evt =                new UnsolicitedNotificationEvent(ctx, (UnsolicitedNotification)obj);            queueEvent(evt, unsolicited);         } else if (obj instanceof NamingException) {             // Fire NamingExceptionEvent to unsolicited listeners.             NamingExceptionEvent evt =                new NamingExceptionEvent(ctx, (NamingException)obj);            queueEvent(evt, unsolicited);             // When an exception occurs, the unsolicited listeners            // are automatically deregistered.            // When LdapClient.processUnsolicited() fires a NamingException,            // it will update its listener list so we don't have to.            // Likewise for LdapCtx.             unsolicited = null;        }    }     /**     * Stops notifier threads that are collecting event data and     * stops the event queue from dispatching events.     * Package private; used by LdapCtx.     */    synchronized void cleanup() {        if (debug) System.err.println("EventSupport clean up");        if (notifiers != null) {            for (Enumeration ns = notifiers.elements(); ns.hasMoreElements(); ) {                ((NamingEventNotifier) ns.nextElement()).stop();            }            notifiers = null;        }        if (eventQueue != null) {            eventQueue.stop();            eventQueue = null;        }        // %%% Should we fire NamingExceptionEvents to unsolicited listeners?    }     /*     * The queue of events to be delivered.     */    private EventQueue eventQueue;     /**     * Add the event and vector of listeners to the queue to be delivered.     * An event dispatcher thread dequeues events from the queue and dispatches     * them to the registered listeners.     * Package private; used by NamingEventNotifier to fire events     */    synchronized void queueEvent(EventObject event, Vector vector) {        if (eventQueue == null)            eventQueue = new EventQueue();         /*         * Copy the vector in order to freeze the state of the set         * of EventListeners the event should be delivered to prior         * to delivery.  This ensures that any changes made to the         * Vector from a target listener's method during the delivery         * of this event will not take effect until after the event is         * delivered.         */        Vector v = (Vector)vector.clone();        eventQueue.enqueue(event, v);    }     // No finalize() needed because EventSupport is always owned by    // an LdapCtx. LdapCtx's finalize() and close() always call cleanup() so    // there is no need for EventSupport to have a finalize().}