Source for javax.swing.event.EventListenerList

   1: /* EventListenerList.java --
   2:    Copyright (C) 2002, 2004, 2005, 2006,  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package javax.swing.event;
  39: 
  40: import java.io.Serializable;
  41: import java.lang.reflect.Array;
  42: import java.util.EventListener;
  43: 
  44: 
  45: /**
  46:  * A utility class for keeping track of {@link EventListener}s.
  47:  *
  48:  * <p><b>Example for using this class:</b>
  49:  *
  50:  * <blockquote><pre> import java.util.EventListener;
  51:  * import javax.swing.event.EventListenerList;
  52:  *
  53:  * class Foo
  54:  * {
  55:  *   protected final EventListenerList listeners = new EventListenerList();
  56:  *   protected BarClosedEvent barClosedEvent = null;
  57:  *
  58:  *   public void addBarListener(BarListener l)
  59:  *   {
  60:  *     listeners.<a href="#add(java.lang.Class, java.util.EventListener)"
  61:  *               >add</a>(BarListener.class, l);
  62:  *   }
  63:  *
  64:  *   public void removeBarListener(BarListener l)
  65:  *   {
  66:  *     listeners.<a href="#remove(java.lang.Class, java.util.EventListener)"
  67:  *               >remove</a>(BarListener.class, l);
  68:  *   }
  69:  *
  70:  *   protected void fireBarClosedEvent()
  71:  *   {
  72:  *     Object[] l = listeners.<a href="#getListenerList()"
  73:  *                            >getListenerList()</a>;
  74:  *
  75:  *     for (int i = l.length - 2; i >= 0; i -= 2)
  76:  *       if (l[i] == BarListener.class)
  77:  *         {
  78:  *           // Create the event on demand, when it is needed the first time.
  79:  *           if (barClosedEvent == null)
  80:  *             barClosedEvent = new BarClosedEvent(this);
  81:  *
  82:  *           ((BarClosedListener) l[i + 1]).barClosed(barClosedEvent);
  83:  *         }
  84:  *   }
  85:  * }</pre></blockquote>
  86:  *
  87:  * @author Andrew Selkirk (aselkirk@sympatico.ca)
  88:  * @author Sascha Brawer (brawer@dandelis.ch)
  89:  */
  90: public class EventListenerList
  91:   implements Serializable
  92: {
  93:   /**
  94:    * An ID for serializing instances of this class; verified with the
  95:    * serialver tool of Sun J2SE 1.4.1_01.
  96:    */
  97:   static final long serialVersionUID = -5677132037850737084L;
  98: 
  99: 
 100:   /**
 101:    * An empty array that is shared by all instances of this class that
 102:    * have no listeners.
 103:    */
 104:   private static final Object[] NO_LISTENERS = new Object[0];
 105:   
 106:   
 107:   /**
 108:    * An array with all currently registered listeners.  The array has
 109:    * twice as many elements as there are listeners.  For an even
 110:    * integer <code>i</code>, <code>listenerList[i]</code> indicates
 111:    * the registered class, and <code>listenerList[i + 1]</code> is the
 112:    * listener.
 113:    */
 114:   protected transient Object[] listenerList = NO_LISTENERS;
 115: 
 116:   
 117:   /**
 118:    * EventListenerList constructor
 119:    */
 120:   public EventListenerList()
 121:   {
 122:     // Nothing to do here.
 123:   }
 124: 
 125: 
 126:   /**
 127:    * Registers a listener of a specific type.
 128:    *
 129:    * @param t the type of the listener.
 130:    *
 131:    * @param listener the listener to add, which must be an instance of
 132:    * <code>t</code>, or of a subclass of <code>t</code>.
 133:    *
 134:    * @throws IllegalArgumentException if <code>listener</code> is not
 135:    * an instance of <code>t</code> (or a subclass thereof).
 136:    *
 137:    * @throws NullPointerException if <code>t</code> is <code>null</code>.
 138:    */
 139:   public void add(Class t, EventListener listener)
 140:   {
 141:     int oldLength;
 142:     Object[] newList;
 143: 
 144:     if (listener == null)
 145:       return;
 146: 
 147:     if (!t.isInstance(listener))
 148:       throw new IllegalArgumentException();
 149: 
 150:     oldLength = listenerList.length;
 151:     newList = new Object[oldLength + 2];
 152:     if (oldLength > 0)
 153:       System.arraycopy(listenerList, 0, newList, 0, oldLength);
 154: 
 155:     newList[oldLength] = t;
 156:     newList[oldLength + 1] = listener;
 157:     listenerList = newList;
 158:   }
 159: 
 160: 
 161:   /**
 162:    * Determines the number of listeners.
 163:    */
 164:   public int getListenerCount()
 165:   {
 166:     return listenerList.length / 2;
 167:   }
 168: 
 169: 
 170:   /**
 171:    * Determines the number of listeners of a particular class.
 172:    *
 173:    * @param t the type of listeners to be counted. In order to get
 174:    * counted, a subscribed listener must be exactly of class
 175:    * <code>t</code>. Thus, subclasses of <code>t</code> will not be
 176:    * counted.
 177:    */
 178:   public int getListenerCount(Class t)
 179:   {
 180:     int result = 0;
 181:     for (int i = 0; i < listenerList.length; i += 2)
 182:       if (t == listenerList[i])
 183:         ++result;
 184: 
 185:     return result;
 186:   }
 187: 
 188: 
 189:   /**
 190:    * Returns an array containing a sequence of listenerType/listener pairs, one
 191:    * for each listener.
 192:    * 
 193:    * @return An array containing the listener types and references.
 194:    */
 195:   public Object[] getListenerList()
 196:   {
 197:     // returning the internal storage is a bad idea, but tests show that the
 198:     // reference implementation does this...
 199:     return listenerList;
 200:   }
 201: 
 202: 
 203:   /**
 204:    * Retrieves the currently subscribed listeners of a particular
 205:    * type.  For a listener to be returned, it must have been
 206:    * registered with exactly the type <code>c</code>; subclasses are
 207:    * not considered equal.
 208:    *
 209:    * <p>The returned array can always be cast to <code>c[]</code>.
 210:    * Since it is a newly allocated copy, the caller may arbitrarily
 211:    * modify the array.
 212:    *
 213:    * @param c the class which was passed to {@link #add}.
 214:    *
 215:    * @throws ClassCastException if <code>c</code> does not implement
 216:    * the {@link EventListener} interface.
 217:    *
 218:    * @throws NullPointerException if <code>c</code> is
 219:    * <code>null</code>.
 220:    *
 221:    * @return an array of <code>c</code> whose elements are the
 222:    * currently subscribed listeners of the specified type.  If there
 223:    * are no such listeners, an empty array is returned.
 224:    *
 225:    * @since 1.3
 226:    */
 227:   public EventListener[] getListeners(Class c)
 228:   {
 229:     int count, f;
 230:     EventListener[] result;
 231: 
 232:     count = getListenerCount(c);
 233:     result = (EventListener[]) Array.newInstance(c, count);
 234:     f = 0;
 235:     for (int i = listenerList.length - 2; i >= 0; i -= 2)
 236:       if (listenerList[i] == c)
 237:         result[f++] = (EventListener) listenerList[i + 1];
 238:     
 239:     return result;
 240:   }
 241: 
 242: 
 243:   /**
 244:    * Removes a listener of a specific type.
 245:    *
 246:    * @param t the type of the listener.
 247:    *
 248:    * @param listener the listener to remove, which must be an instance
 249:    * of <code>t</code>, or of a subclass of <code>t</code>.
 250:    *
 251:    * @throws IllegalArgumentException if <code>listener</code> is not
 252:    * an instance of <code>t</code> (or a subclass thereof).
 253:    *
 254:    * @throws NullPointerException if <code>t</code> is <code>null</code>.
 255:    */
 256:   public void remove(Class t, EventListener listener)
 257:   {
 258:     Object[] oldList, newList;
 259:     int oldLength;
 260: 
 261:     if (listener == null)
 262:       return;
 263: 
 264:     if (!t.isInstance(listener))
 265:       throw new IllegalArgumentException();
 266: 
 267:     oldList = listenerList;
 268:     oldLength = oldList.length;
 269:     for (int i = 0; i < oldLength; i += 2)
 270:       if (oldList[i] == t && oldList[i + 1] == listener)
 271:         {
 272:           if (oldLength == 2)
 273:             newList = NO_LISTENERS;
 274:           else
 275:             {
 276:               newList = new Object[oldLength - 2];
 277:               if (i > 0)
 278:                 System.arraycopy(oldList, 0, newList, 0, i);
 279:               if (i < oldLength - 2)
 280:                 System.arraycopy(oldList, i + 2, newList, i,
 281:                                  oldLength - 2 - i);
 282:             }
 283:           listenerList = newList;
 284:           return;
 285:         }
 286:   }
 287: 
 288: 
 289:   /**
 290:    * Returns a string representation of this object that may be useful
 291:    * for debugging purposes.
 292:    */
 293:   public String toString()
 294:   {
 295:     StringBuffer buf = new StringBuffer("EventListenerList: ");
 296:     buf.append(listenerList.length / 2);
 297:     buf.append(" listeners: ");
 298:     for (int i = 0; i < listenerList.length; i += 2)
 299:       {
 300:         buf.append(" type ");
 301:         buf.append(((Class) listenerList[i]).getName());
 302:         buf.append(" listener ");
 303:         buf.append(listenerList[i + 1]);
 304:       }
 305:     return buf.toString();
 306:   }
 307: }