KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > update > internal > core > ListenersList


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.update.internal.core;
12
13 import org.eclipse.core.runtime.Assert;
14
15 /**
16  * This class is used to maintain a list of listeners, and
17  * is used in the implementations of several classes within JFace
18  * which allow you to register listeners of various kinds.
19  * It is a fairly lightweight object, occupying minimal space when
20  * no listeners are registered.
21  * <p>
22  * Note that the <code>add</code> method checks for and eliminates
23  * duplicates based on identity (not equality). Likewise, the
24  * <code>remove</code> method compares based on identity.
25  * </p>
26  * <p>
27  * Use the <code>getListeners</code> method when notifying listeners.
28  * Note that no garbage is created if no listeners are registered.
29  * The recommended code sequence for notifying all registered listeners
30  * of say, <code>FooListener.eventHappened</code>, is:
31  * <pre>
32  * Object[] listeners = myListenerList.getListeners();
33  * for (int i = 0; i < listeners.length; ++i) {
34  * ((FooListener) listeners[i]).eventHappened(event);
35  * }
36  * </pre>
37  * </p>
38  */

39
40 public class ListenersList {
41     /**
42      * The initial capacity of the list. Always >= 1.
43      */

44     private int capacity;
45
46     /**
47      * The current number of listeners.
48      * Maintains invariant: 0 <= size <= listeners.length.
49      */

50     private int size;
51
52     /**
53      * The list of listeners. Initially <code>null</code> but initialized
54      * to an array of size capacity the first time a listener is added.
55      * Maintains invariant: listeners != null IFF size != 0
56      */

57     private Object JavaDoc[] listeners = null;
58
59     /**
60      * The empty array singleton instance, returned by getListeners()
61      * when size == 0.
62      */

63     private static final Object JavaDoc[] EmptyArray = new Object JavaDoc[0];
64 /**
65  * Creates a listener list with an initial capacity of 3.
66  */

67 public ListenersList() {
68     this(3);
69 }
70 /**
71  * Creates a listener list with the given initial capacity.
72  *
73  * @param capacity the number of listeners which this list can initially accept
74  * without growing its internal representation; must be at least 1
75  */

76 public ListenersList(int capacity) {
77     Assert.isTrue(capacity >= 1);
78     this.capacity = capacity;
79 }
80 /**
81  * Adds the given listener to this list. Has no effect if an identical listener
82  * is already registered.
83  *
84  * @param listener the listener
85  */

86 public void add(Object JavaDoc listener) {
87     Assert.isNotNull(listener);
88     if (size == 0) {
89         listeners = new Object JavaDoc[capacity];
90     } else {
91         // check for duplicates using identity
92
for (int i = 0; i < size; ++i) {
93             if (listeners[i] == listener) {
94                 return;
95             }
96         }
97         // grow array if necessary
98
if (size == listeners.length) {
99             System.arraycopy(listeners, 0, listeners = new Object JavaDoc[size * 2 + 1], 0, size);
100         }
101     }
102     listeners[size++] = listener;
103 }
104 /**
105  * Returns an array containing all the registered listeners.
106  * The resulting array is unaffected by subsequent adds or removes.
107  * If there are no listeners registered, the result is an empty array
108  * singleton instance (no garbage is created).
109  * Use this method when notifying listeners, so that any modifications
110  * to the listener list during the notification will have no effect on the
111  * notification itself.
112  *
113  * @return the list of registered listeners
114  */

115 public Object JavaDoc[] getListeners() {
116     if (size == 0)
117         return EmptyArray;
118     Object JavaDoc[] result = new Object JavaDoc[size];
119     System.arraycopy(listeners, 0, result, 0, size);
120     return result;
121 }
122 /**
123  * Returns whether this listener list is empty.
124  *
125  * @return <code>true</code> if there are no registered listeners, and
126  * <code>false</code> otherwise
127  */

128 public boolean isEmpty() {
129     return size == 0;
130 }
131 /**
132  * Removes the given listener from this list. Has no effect if an identical
133  * listener was not already registered.
134  *
135  * @param listener the listener
136  */

137 public void remove(Object JavaDoc listener) {
138     Assert.isNotNull(listener);
139     for (int i = 0; i < size; ++i) {
140         if (listeners[i] == listener) {
141             if (size == 1) {
142                 listeners = null;
143                 size = 0;
144             }
145             else {
146                 System.arraycopy(listeners, i + 1, listeners, i, --size - i);
147                 listeners[size] = null;
148             }
149             return;
150         }
151     }
152 }
153 /**
154  * Returns the number of registered listeners.
155  *
156  * @return the number of registered listeners
157  */

158 public int size() {
159     return size;
160 }
161 }
162     
163
164
165
166
Popular Tags