1 /*
2 * Copyright (c) 1999, 2017, 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
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 *<h4>Registration</h4>
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 *<h4>Deregistration</h4>
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 *<h4>Event Dispatching</h4>
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 *<h4>Synchronization</h4>
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);
|
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
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);
|