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 com.sun.jndi.ldap;
  27 
  28 import java.util.Hashtable;
  29 import java.util.Vector;
  30 import java.util.EventObject;
  31 import java.util.Iterator;
  32 import java.util.Map;
  33 
  34 import javax.naming.*;
  35 import javax.naming.event.*;
  36 import javax.naming.directory.SearchControls;
  37 import javax.naming.ldap.UnsolicitedNotificationListener;
  38 import javax.naming.ldap.UnsolicitedNotificationEvent;
  39 import javax.naming.ldap.UnsolicitedNotification;
  40 
  41 /**
  42  * This is a utility class that can be used by a context that supports
  43  * event notification.  You can use an instance of this class as a member field
  44  * of your context and delegate various work to it.
  45  * It is currently structured so that each context should have its own
  46  * EventSupport (instead of static version shared by all contexts
  47  * of a service provider).
  48  *<p>
  49  * This class supports two types of listeners: those that register for
  50  * NamingEvents, and those for UnsolicitedNotificationEvents (they can be mixed
  51  * into the same listener).
  52  * For NamingEvent listeners, it maintains a hashtable that maps
  53  * registration requests--the key--to
  54  * <em>notifiers</em>--the value. Each registration request consists of:
  55  *<ul>
  56  *<li>The name argument of the registration.
  57  *<li>The filter (default is "(objectclass=*)").
  58  *<li>The search controls (default is null SearchControls).
  59  *<li>The events that the listener is interested in. This is determined by
  60  * finding out which {@code NamingListener} interface the listener supports.
  61  *</ul>
  62  *<p>
  63  *A notifier ({@code NamingEventNotifier}) is a worker thread that is responsible
  64  *for gathering information for generating events requested by its listeners.
  65  *Each notifier maintains its own list of listeners; these listeners have
  66  *all made the same registration request (at different times) and implements
  67  *the same {@code NamingListener} interfaces.
  68  *<p>
  69  *For unsolicited listeners, this class maintains a vector, unsolicited.
  70  *When an unsolicited listener is registered, this class adds itself
  71  *to the context's LdapClient. When LdapClient receives an unsolicited
  72  *notification, it notifies this EventSupport to fire an event to the
  73  *the listeners. Special handling in LdapClient is done for the DISCONNECT
  74  *notification. [It results in the EventSupport firing also a
  75  *NamingExceptionEvent to the unsolicited listeners.]
  76  *<p>
  77  *
  78  *When a context no longer needs this EventSupport, it should invoke
  79  *cleanup() on it.
  80  *<p>
  81  *<h2>Registration</h2>
  82  *When a registration request is made, this class attempts to find an
  83  *existing notifier that's already working on the request. If one is
  84  *found, the listener is added to the notifier's list. If one is not found,
  85  *a new notifier is created for the listener.
  86  *
  87  *<h2>Deregistration</h2>
  88  *When a deregistration request is made, this class attempts to find its
  89  *corresponding notifier. If the notifier is found, the listener is removed
  90  *from the notifier's list. If the listener is the last listener on the list,
  91  *the notifier's thread is terminated and removed from this class's hashtable.
  92  *Nothing happens if the notifier is not found.
  93  *
  94  *<h2>Event Dispatching</h2>
  95  *The notifiers are responsible for gather information for generating events
  96  *requested by their respective listeners. When a notifier gets sufficient
  97  *information to generate an event, it creates invokes the
  98  *appropriate {@code fireXXXEvent} on this class with the information and list of
  99  *listeners. This causes an event and the list of listeners to be added
 100  *to the <em>event queue</em>.
 101  *This class maintains an event queue and a dispatching thread that dequeues
 102  *events from the queue and dispatches them to the listeners.
 103  *
 104  *<h2>Synchronization</h2>
 105  *This class is used by the main thread (LdapCtx) to add/remove listeners.
 106  *It is also used asynchronously by NamingEventNotifiers threads and
 107  *the context's Connection thread. It is used by the notifier threads to
 108  *queue events and to update the notifiers list when the notifiers exit.
 109  *It is used by the Connection thread to fire unsolicited notifications.
 110  *Methods that access/update the 'unsolicited' and 'notifiers' lists are
 111  *thread-safe.
 112  *
 113  * @author Rosanna Lee
 114  */
 115 final class EventSupport {
 116     final static private boolean debug = false;
 117 
 118     private LdapCtx ctx;
 119 
 120     /**
 121      * NamingEventNotifiers; hashed by search arguments;
 122      */
 123     private Hashtable<NotifierArgs, NamingEventNotifier> notifiers =
 124             new Hashtable<>(11);
 125 
 126     /**
 127      * List of unsolicited notification listeners.
 128      */
 129     private Vector<UnsolicitedNotificationListener> unsolicited = null;
 130 
 131     /**
 132      * Constructs EventSupport for ctx.
 133      * <em>Do we need to record the name of the target context?
 134      * Or can we assume that EventSupport is called on a resolved
 135      * context? Do we need other add/remove-NamingListener methods?
 136      * package private;
 137      */
 138     EventSupport(LdapCtx ctx) {
 139         this.ctx = ctx;
 140     }
 141 
 142     /**
 143      * Adds {@code l} to list of listeners interested in {@code nm}.
 144      */
 145     /*
 146      * Make the add/removeNamingListeners synchronized to:
 147      * 1. protect usage of 'unsolicited', which may be read by
 148      *    the Connection thread when dispatching unsolicited notification.
 149      * 2. ensure that NamingEventNotifier thread's access to 'notifiers'
 150      *    is safe
 151      */
 152     synchronized void addNamingListener(String nm, int scope,
 153         NamingListener l) throws NamingException {
 154 
 155         if (l instanceof ObjectChangeListener ||
 156             l instanceof NamespaceChangeListener) {
 157             NotifierArgs args = new NotifierArgs(nm, scope, l);
 158 
 159             NamingEventNotifier notifier = notifiers.get(args);
 160             if (notifier == null) {
 161                 notifier = new NamingEventNotifier(this, ctx, args, l);
 162                 notifiers.put(args, notifier);
 163             } else {
 164                 notifier.addNamingListener(l);
 165             }
 166         }
 167         if (l instanceof UnsolicitedNotificationListener) {
 168             // Add listener to this's list of unsolicited notifiers
 169             if (unsolicited == null) {
 170                 unsolicited = new Vector<>(3);
 171             }
 172 
 173             unsolicited.addElement((UnsolicitedNotificationListener)l);
 174         }
 175     }
 176 
 177     /**
 178      * Adds {@code l} to list of listeners interested in {@code nm}
 179      * and filter.
 180      */
 181     synchronized void addNamingListener(String nm, String filter,
 182         SearchControls ctls, NamingListener l) throws NamingException {
 183 
 184         if (l instanceof ObjectChangeListener ||
 185             l instanceof NamespaceChangeListener) {
 186             NotifierArgs args = new NotifierArgs(nm, filter, ctls, l);
 187 
 188             NamingEventNotifier notifier = notifiers.get(args);
 189             if (notifier == null) {
 190                 notifier = new NamingEventNotifier(this, ctx, args, l);
 191                 notifiers.put(args, notifier);
 192             } else {
 193                 notifier.addNamingListener(l);
 194             }
 195         }
 196         if (l instanceof UnsolicitedNotificationListener) {
 197             // Add listener to this's list of unsolicited notifiers
 198             if (unsolicited == null) {
 199                 unsolicited = new Vector<>(3);
 200             }
 201             unsolicited.addElement((UnsolicitedNotificationListener)l);
 202         }
 203     }
 204 
 205     /**
 206      * Removes {@code l} from all notifiers in this context.
 207      */
 208     synchronized void removeNamingListener(NamingListener l) {
 209         if (debug) {
 210             System.err.println("EventSupport removing listener");
 211         }
 212         // Go through list of notifiers, remove 'l' from each.
 213         // If 'l' is notifier's only listener, remove notifier too.
 214         Iterator<NamingEventNotifier> iterator = notifiers.values().iterator();
 215         while (iterator.hasNext()) {
 216             NamingEventNotifier notifier = iterator.next();
 217             if (notifier != null) {
 218                 if (debug) {
 219                     System.err.println("EventSupport removing listener from notifier");
 220                 }
 221                 notifier.removeNamingListener(l);
 222                 if (!notifier.hasNamingListeners()) {
 223                     if (debug) {
 224                         System.err.println("EventSupport stopping notifier");
 225                     }
 226                     notifier.stop();
 227                     iterator.remove();
 228                 }
 229             }
 230         }
 231         // Remove from list of unsolicited notifier
 232         if (debug) {
 233             System.err.println("EventSupport removing unsolicited: " + unsolicited);
 234         }
 235         if (unsolicited != null) {
 236             unsolicited.removeElement(l);
 237         }
 238     }
 239 
 240     synchronized boolean hasUnsolicited() {
 241         return (unsolicited != null && unsolicited.size() > 0);
 242     }
 243 
 244     /**
 245       * package private;
 246       * Called by NamingEventNotifier to remove itself when it encounters
 247       * a NamingException.
 248       */
 249     synchronized void removeDeadNotifier(NotifierArgs info) {
 250         if (debug) {
 251             System.err.println("EventSupport.removeDeadNotifier: " + info.name);
 252         }




 253         notifiers.remove(info);
 254     }

 255 
 256     /**
 257      * Fire an event to unsolicited listeners.
 258      * package private;
 259      * Called by LdapCtx when its clnt receives an unsolicited notification.
 260      */
 261     synchronized void fireUnsolicited(Object obj) {
 262         if (debug) {
 263             System.err.println("EventSupport.fireUnsolicited: " + obj + " "
 264                 + unsolicited);
 265         }
 266         if (unsolicited == null || unsolicited.size() == 0) {
 267             // This shouldn't really happen, but might in case
 268             // there is a timing problem that removes a listener
 269             // before a fired event reaches here.
 270             return;
 271         }
 272 
 273         if (obj instanceof UnsolicitedNotification) {
 274 
 275             // Fire UnsolicitedNotification to unsolicited listeners
 276 
 277             UnsolicitedNotificationEvent evt =
 278                 new UnsolicitedNotificationEvent(ctx, (UnsolicitedNotification)obj);
 279             queueEvent(evt, unsolicited);
 280 
 281         } else if (obj instanceof NamingException) {
 282 
 283             // Fire NamingExceptionEvent to unsolicited listeners.
 284 
 285             NamingExceptionEvent evt =
 286                 new NamingExceptionEvent(ctx, (NamingException)obj);
 287             queueEvent(evt, unsolicited);
 288 
 289             // When an exception occurs, the unsolicited listeners
 290             // are automatically deregistered.
 291             // When LdapClient.processUnsolicited() fires a NamingException,
 292             // it will update its listener list so we don't have to.
 293             // Likewise for LdapCtx.
 294 
 295             unsolicited = null;
 296         }
 297     }
 298 
 299     /**
 300      * Stops notifier threads that are collecting event data and
 301      * stops the event queue from dispatching events.
 302      * Package private; used by LdapCtx.
 303      */
 304     synchronized void cleanup() {
 305         if (debug) System.err.println("EventSupport clean up");
 306         if (notifiers != null) {
 307             for (NamingEventNotifier notifier : notifiers.values()) {
 308                 notifier.stop();
 309             }
 310             notifiers = null;
 311         }
 312         if (eventQueue != null) {
 313             eventQueue.stop();
 314             eventQueue = null;
 315         }
 316         // %%% Should we fire NamingExceptionEvents to unsolicited listeners?
 317     }
 318 
 319     /*
 320      * The queue of events to be delivered.
 321      */
 322     private EventQueue eventQueue;
 323 
 324     /**
 325      * Add the event and vector of listeners to the queue to be delivered.
 326      * An event dispatcher thread dequeues events from the queue and dispatches
 327      * them to the registered listeners.
 328      * Package private; used by NamingEventNotifier to fire events
 329      */
 330     synchronized void queueEvent(EventObject event,
 331                                  Vector<? extends NamingListener> vector) {





 332         if (eventQueue == null)
 333             eventQueue = new EventQueue();
 334 
 335         /*
 336          * Copy the vector in order to freeze the state of the set
 337          * of EventListeners the event should be delivered to prior
 338          * to delivery.  This ensures that any changes made to the
 339          * Vector from a target listener's method during the delivery
 340          * of this event will not take effect until after the event is
 341          * delivered.
 342          */
 343         @SuppressWarnings("unchecked") // clone()
 344         Vector<NamingListener> v =
 345                 (Vector<NamingListener>)vector.clone();
 346         eventQueue.enqueue(event, v);
 347     }
 348 
 349     // No finalize() needed because EventSupport is always owned by
 350     // an LdapCtx. LdapCtx's finalize() and close() always call cleanup() so
 351     // there is no need for EventSupport to have a finalize().
 352 }
--- EOF ---