Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.lang3.event;
019
020import java.io.ByteArrayOutputStream;
021import java.io.IOException;
022import java.io.ObjectInputStream;
023import java.io.ObjectOutputStream;
024import java.io.Serializable;
025import java.lang.reflect.InvocationHandler;
026import java.lang.reflect.InvocationTargetException;
027import java.lang.reflect.Method;
028import java.lang.reflect.Proxy;
029import java.util.ArrayList;
030import java.util.List;
031import java.util.Objects;
032import java.util.concurrent.CopyOnWriteArrayList;
033
034import org.apache.commons.lang3.ArrayUtils;
035import org.apache.commons.lang3.Validate;
036
037/**
038 * An EventListenerSupport object can be used to manage a list of event
039 * listeners of a particular type. The class provides
040 * {@link #addListener(Object)} and {@link #removeListener(Object)} methods
041 * for registering listeners, as well as a {@link #fire()} method for firing
042 * events to the listeners.
043 *
044 * <p>
045 * To use this class, suppose you want to support ActionEvents.  You would do:
046 * </p>
047 * <pre><code>
048 * public class MyActionEventSource
049 * {
050 *   private EventListenerSupport&lt;ActionListener&gt; actionListeners =
051 *       EventListenerSupport.create(ActionListener.class);
052 *
053 *   public void someMethodThatFiresAction()
054 *   {
055 *     ActionEvent e = new ActionEvent(this, ActionEvent.ACTION_PERFORMED, "somethingCool");
056 *     actionListeners.fire().actionPerformed(e);
057 *   }
058 * }
059 * </code></pre>
060 *
061 * <p>
062 * Serializing an {@link EventListenerSupport} instance will result in any
063 * non-{@link Serializable} listeners being silently dropped.
064 * </p>
065 *
066 * @param <L> the type of event listener that is supported by this proxy.
067 *
068 * @since 3.0
069 */
070public class EventListenerSupport<L> implements Serializable {
071
072    /**
073     * An invocation handler used to dispatch the event(s) to all the listeners.
074     */
075    protected class ProxyInvocationHandler implements InvocationHandler {
076
077        /**
078         * Propagates the method call to all registered listeners in place of the proxy listener object.
079         *
080         * @param unusedProxy the proxy object representing a listener on which the invocation was called; not used
081         * @param method the listener method that will be called on all of the listeners.
082         * @param args event arguments to propagate to the listeners.
083         * @return the result of the method call
084         * @throws InvocationTargetException if an error occurs
085         * @throws IllegalArgumentException if an error occurs
086         * @throws IllegalAccessException if an error occurs
087         */
088        @Override
089        public Object invoke(final Object unusedProxy, final Method method, final Object[] args)
090                throws IllegalAccessException, IllegalArgumentException, InvocationTargetException {
091            for (final L listener : listeners) {
092                method.invoke(listener, args);
093            }
094            return null;
095        }
096    }
097
098    /** Serialization version */
099    private static final long serialVersionUID = 3593265990380473632L;
100
101    /**
102     * Creates an EventListenerSupport object which supports the specified
103     * listener type.
104     *
105     * @param <T> the type of the listener interface
106     * @param listenerInterface the type of listener interface that will receive
107     *        events posted using this class.
108     *
109     * @return an EventListenerSupport object which supports the specified
110     *         listener type.
111     *
112     * @throws NullPointerException if {@code listenerInterface} is
113     *         {@code null}.
114     * @throws IllegalArgumentException if {@code listenerInterface} is
115     *         not an interface.
116     */
117    public static <T> EventListenerSupport<T> create(final Class<T> listenerInterface) {
118        return new EventListenerSupport<>(listenerInterface);
119    }
120
121    /**
122     * The list used to hold the registered listeners. This list is
123     * intentionally a thread-safe copy-on-write-array so that traversals over
124     * the list of listeners will be atomic.
125     */
126    private List<L> listeners = new CopyOnWriteArrayList<>();
127
128    /**
129     * The proxy representing the collection of listeners. Calls to this proxy
130     * object will be sent to all registered listeners.
131     */
132    private transient L proxy;
133
134    /**
135     * Empty typed array for #getListeners().
136     */
137    private transient L[] prototypeArray;
138
139    /**
140     * Create a new EventListenerSupport instance.
141     * Serialization-friendly constructor.
142     */
143    private EventListenerSupport() {
144    }
145
146    /**
147     * Creates an EventListenerSupport object which supports the provided
148     * listener interface.
149     *
150     * @param listenerInterface the type of listener interface that will receive
151     *        events posted using this class.
152     *
153     * @throws NullPointerException if {@code listenerInterface} is
154     *         {@code null}.
155     * @throws IllegalArgumentException if {@code listenerInterface} is
156     *         not an interface.
157     */
158    public EventListenerSupport(final Class<L> listenerInterface) {
159        this(listenerInterface, Thread.currentThread().getContextClassLoader());
160    }
161
162    /**
163     * Creates an EventListenerSupport object which supports the provided
164     * listener interface using the specified class loader to create the JDK
165     * dynamic proxy.
166     *
167     * @param listenerInterface the listener interface.
168     * @param classLoader       the class loader.
169     *
170     * @throws NullPointerException if {@code listenerInterface} or
171     *         {@code classLoader} is {@code null}.
172     * @throws IllegalArgumentException if {@code listenerInterface} is
173     *         not an interface.
174     */
175    public EventListenerSupport(final Class<L> listenerInterface, final ClassLoader classLoader) {
176        this();
177        Objects.requireNonNull(listenerInterface, "listenerInterface");
178        Objects.requireNonNull(classLoader, "classLoader");
179        Validate.isTrue(listenerInterface.isInterface(), "Class %s is not an interface",
180                listenerInterface.getName());
181        initializeTransientFields(listenerInterface, classLoader);
182    }
183
184//**********************************************************************************************************************
185// Other Methods
186//**********************************************************************************************************************
187
188    /**
189     * Registers an event listener.
190     *
191     * @param listener the event listener (may not be {@code null}).
192     *
193     * @throws NullPointerException if {@code listener} is
194     *         {@code null}.
195     */
196    public void addListener(final L listener) {
197        addListener(listener, true);
198    }
199
200    /**
201     * Registers an event listener.  Will not add a pre-existing listener
202     * object to the list if {@code allowDuplicate} is false.
203     *
204     * @param listener the event listener (may not be {@code null}).
205     * @param allowDuplicate the flag for determining if duplicate listener
206     * objects are allowed to be registered.
207     *
208     * @throws NullPointerException if {@code listener} is {@code null}.
209     * @since 3.5
210     */
211    public void addListener(final L listener, final boolean allowDuplicate) {
212        Objects.requireNonNull(listener, "listener");
213        if (allowDuplicate || !listeners.contains(listener)) {
214            listeners.add(listener);
215        }
216    }
217
218    /**
219     * Create the {@link InvocationHandler} responsible for broadcasting calls
220     * to the managed listeners.  Subclasses can override to provide custom behavior.
221     * @return ProxyInvocationHandler
222     */
223    protected InvocationHandler createInvocationHandler() {
224        return new ProxyInvocationHandler();
225    }
226
227    /**
228     * Create the proxy object.
229     * @param listenerInterface the class of the listener interface
230     * @param classLoader the class loader to be used
231     */
232    private void createProxy(final Class<L> listenerInterface, final ClassLoader classLoader) {
233        proxy = listenerInterface.cast(Proxy.newProxyInstance(classLoader,
234                new Class[] { listenerInterface }, createInvocationHandler()));
235    }
236
237    /**
238     * Returns a proxy object which can be used to call listener methods on all
239     * of the registered event listeners. All calls made to this proxy will be
240     * forwarded to all registered listeners.
241     *
242     * @return a proxy object which can be used to call listener methods on all
243     * of the registered event listeners
244     */
245    public L fire() {
246        return proxy;
247    }
248
249    /**
250     * Returns the number of registered listeners.
251     *
252     * @return the number of registered listeners.
253     */
254    int getListenerCount() {
255        return listeners.size();
256    }
257
258    /**
259     * Gets an array containing the currently registered listeners.
260     * Modification to this array's elements will have no effect on the
261     * {@link EventListenerSupport} instance.
262     * @return L[]
263     */
264    public L[] getListeners() {
265        return listeners.toArray(prototypeArray);
266    }
267
268    /**
269     * Initialize transient fields.
270     * @param listenerInterface the class of the listener interface
271     * @param classLoader the class loader to be used
272     */
273    private void initializeTransientFields(final Class<L> listenerInterface, final ClassLoader classLoader) {
274        // Will throw CCE here if not correct
275        this.prototypeArray = ArrayUtils.newInstance(listenerInterface, 0);
276        createProxy(listenerInterface, classLoader);
277    }
278
279    /**
280     * Deserialize.
281     * @param objectInputStream the input stream
282     * @throws IOException if an IO error occurs
283     * @throws ClassNotFoundException if the class cannot be resolved
284     */
285    private void readObject(final ObjectInputStream objectInputStream) throws IOException, ClassNotFoundException {
286        @SuppressWarnings("unchecked") // Will throw CCE here if not correct
287        final L[] srcListeners = (L[]) objectInputStream.readObject();
288
289        this.listeners = new CopyOnWriteArrayList<>(srcListeners);
290
291        final Class<L> listenerInterface = ArrayUtils.getComponentType(srcListeners);
292
293        initializeTransientFields(listenerInterface, Thread.currentThread().getContextClassLoader());
294    }
295
296    /**
297     * Unregisters an event listener.
298     *
299     * @param listener the event listener (may not be {@code null}).
300     *
301     * @throws NullPointerException if {@code listener} is
302     *         {@code null}.
303     */
304    public void removeListener(final L listener) {
305        Objects.requireNonNull(listener, "listener");
306        listeners.remove(listener);
307    }
308
309    /**
310     * Serialize.
311     * @param objectOutputStream the output stream
312     * @throws IOException if an IO error occurs
313     */
314    private void writeObject(final ObjectOutputStream objectOutputStream) throws IOException {
315        final ArrayList<L> serializableListeners = new ArrayList<>();
316
317        // don't just rely on instanceof Serializable:
318        ObjectOutputStream testObjectOutputStream = new ObjectOutputStream(new ByteArrayOutputStream());
319        for (final L listener : listeners) {
320            try {
321                testObjectOutputStream.writeObject(listener);
322                serializableListeners.add(listener);
323            } catch (final IOException exception) {
324                //recreate test stream in case of indeterminate state
325                testObjectOutputStream = new ObjectOutputStream(new ByteArrayOutputStream());
326            }
327        }
328        /*
329         * we can reconstitute everything we need from an array of our listeners,
330         * which has the additional advantage of typically requiring less storage than a list:
331         */
332        objectOutputStream.writeObject(serializableListeners.toArray(prototypeArray));
333    }
334}